Merge branch 'main' into divya/slumbr_base

Author: gitttt-1234

docs/config.md

@@ -123,7 +123,7 @@ trainer_config:
     step_lr: null
     reduce_lr_on_plateau:
       threshold: 1.0e-06
-      threshold_mode: rel
+      threshold_mode: abs
       cooldown: 3
       patience: 5
       factor: 0.5
@@ -739,7 +739,7 @@ trainer_config:
 ### Optimizer Configuration
 - `optimizer_name`: (str) Optimizer to be used. One of ["Adam", "AdamW"]. **Default**: `"Adam"`
 - `optimizer`:
-    - `lr`: (float) Learning rate of type float. **Default**: `1e-3`
+    - `lr`: (float) Learning rate of type float. **Default**: `1e-4`
     - `amsgrad`: (bool) Enable AMSGrad with the optimizer. **Default**: `False`
 
 ### Learning Rate Schedulers
@@ -752,12 +752,12 @@ trainer_config:
 
 #### Reduce LR on Plateau
 - `lr_scheduler.reduce_lr_on_plateau`:
-    - `threshold`: (float) Threshold for measuring the new optimum, to only focus on significant changes. **Default**: `1e-4`
-    - `threshold_mode`: (str) One of "rel", "abs". In rel mode, dynamic_threshold = best * ( 1 + threshold ) in max mode or best * ( 1 - threshold ) in min mode. In abs mode, dynamic_threshold = best + threshold in max mode or best - threshold in min mode. **Default**: `"rel"`
-    - `cooldown`: (int) Number of epochs to wait before resuming normal operation after lr has been reduced. **Default**: `0`
-    - `patience`: (int) Number of epochs with no improvement after which learning rate will be reduced. For example, if patience = 2, then we will ignore the first 2 epochs with no improvement, and will only decrease the LR after the third epoch if the loss still hasn't improved then. **Default**: `10`
-    - `factor`: (float) Factor by which the learning rate will be reduced. new_lr = lr * factor. **Default**: `0.1`
-    - `min_lr`: (float or List[float]) A scalar or a list of scalars. A lower bound on the learning rate of all param groups or each group respectively. **Default**: `0.0`
+    - `threshold`: (float) Threshold for measuring the new optimum, to only focus on significant changes. **Default**: `1e-6`
+    - `threshold_mode`: (str) One of "rel", "abs". In rel mode, dynamic_threshold = best * ( 1 + threshold ) in max mode or best * ( 1 - threshold ) in min mode. In abs mode, dynamic_threshold = best + threshold in max mode or best - threshold in min mode. **Default**: `"abs"`
+    - `cooldown`: (int) Number of epochs to wait before resuming normal operation after lr has been reduced. **Default**: `3`
+    - `patience`: (int) Number of epochs with no improvement after which learning rate will be reduced. For example, if patience = 2, then we will ignore the first 2 epochs with no improvement, and will only decrease the LR after the third epoch if the loss still hasn't improved then. **Default**: `5`
+    - `factor`: (float) Factor by which the learning rate will be reduced. new_lr = lr * factor. **Default**: `0.5`
+    - `min_lr`: (float or List[float]) A scalar or a list of scalars. A lower bound on the learning rate of all param groups or each group respectively. **Default**: `1e-8`
 
 **Example Learning Rate Scheduler configurations:**
 
@@ -786,7 +786,7 @@ trainer_config:
     step_lr: null
     reduce_lr_on_plateau:
       threshold: 1e-6
-      threshold_mode: "rel"
+      threshold_mode: "abs"
       cooldown: 3
       patience: 5
       factor: 0.5
@@ -795,9 +795,9 @@ trainer_config:
 
 ### Early Stopping
 - `early_stopping`:
-    - `stop_training_on_plateau`: (bool) True if early stopping should be enabled. **Default**: `False`
-    - `min_delta`: (float) Minimum change in the monitored quantity to qualify as an improvement, i.e. an absolute change of less than or equal to min_delta, will count as no improvement. **Default**: `0.0`
-    - `patience`: (int) Number of checks with no improvement after which training will be stopped. Under the default configuration, one check happens after every training epoch. **Default**: `1`
+    - `stop_training_on_plateau`: (bool) True if early stopping should be enabled. **Default**: `True`
+    - `min_delta`: (float) Minimum change in the monitored quantity to qualify as an improvement, i.e. an absolute change of less than or equal to min_delta, will count as no improvement. **Default**: `1e-8`
+    - `patience`: (int) Number of checks with no improvement after which training will be stopped. Under the default configuration, one check happens after every training epoch. **Default**: `10`
 
 ### Online Hard Keypoint Mining (OHKM)
 - `online_hard_keypoint_mining`:

docs/installation.md

@@ -79,6 +79,18 @@ Python 3.11 (or) 3.12 (or) 3.13 (required for all installation methods)
 sleap-nn --help
 ```
 
+### Updating Dependencies
+
+To update sleap-nn and its dependencies (e.g., sleap-io) to their latest versions:
+
+```bash
+# Upgrade sleap-nn to the latest version
+uv tool upgrade sleap-nn
+```
+
+!!! note
+    When upgrading, uv respects any version constraints specified during installation. The upgrade will only update within those constraints. To change version constraints, reinstall with new specifications using `uv tool install`.
+
 ---
 
 ## Installation with uvx
@@ -123,6 +135,15 @@ sleap-nn --help
 !!! note "uvx Installation"
     Because `uvx` installs packages fresh on every run, it's ideal for quick tests or use in remote environments. For regular use, you could install with [`uv tool install`](#installation-as-a-system-wide-tool-with-uv) or setting up a development environment with [`uv sync`](#installation-from-source) to avoid repeated downloads.
 
+### Updating Dependencies
+
+With `uvx`, no separate update command is needed:
+
+!!! tip "Automatic Updates"
+    `uvx` automatically fetches and installs the latest version of sleap-nn and its dependencies (e.g., sleap-io) each time you run a command. This means you're always using the most recent version unless you specify version constraints like `uvx "sleap-nn[torch]==0.0.3" ...`.
+
+    To ensure you're using the latest version, simply run your `uvx` command as usual - it will automatically download and use the newest available version.
+
 ---
 
 ## Installation with uv add
@@ -215,9 +236,33 @@ uv run sleap-nn --help
       ```
       This ensures the command runs in the correct environment.
 
-    - **Another workaround (not recommended):**  
+    - **Another workaround (not recommended):**
       Check if you have any *empty* `pyproject.toml` or `uv.lock` files in `Users/<your-user-name>`. If you find empty files with these names, delete them and try again. (Empty files here can sometimes interfere with uv's environment resolution.)
 
+### Updating Dependencies
+
+To update sleap-nn and its dependencies to their latest versions:
+
+=== "Upgrade a Specific Package"
+    ```bash
+    # Upgrade sleap-nn and update the lock file
+    uv add "sleap-nn[torch]" --upgrade-package sleap-nn
+
+    # Upgrade a specific dependency like sleap-io
+    uv add sleap-io --upgrade-package sleap-io
+    ```
+
+=== "Upgrade All Dependencies"
+    ```bash
+    # Upgrade all packages to their latest compatible versions
+    uv sync --upgrade
+    ```
+
+!!! note
+    - `uv add --upgrade-package <package>` forces the specified package to update to its latest compatible version, even if a valid version is already installed.
+    - `uv sync --upgrade` refreshes the entire lockfile and updates all dependencies to their newest compatible versions while maintaining compatibility with your `pyproject.toml` constraints.
+    - By default, `uv add` only updates the locked version if necessary to satisfy new constraints. Use `--upgrade-package` to force an update.
+
 ---
 
 ## Installation with pip
@@ -270,6 +315,35 @@ sleap-nn --help
 python -c "import torch; print(f'PyTorch: {torch.__version__}'); print(f'CUDA available: {torch.cuda.is_available()}')"
 ```
 
+### Updating Dependencies
+
+To update sleap-nn and its dependencies to their latest versions:
+
+=== "Windows/Linux (CUDA)"
+    ```bash
+    # CUDA 12.8
+    pip install --upgrade sleap-nn[torch] --index-url https://pypi.org/simple --extra-index-url https://download.pytorch.org/whl/cu128
+
+    # CUDA 11.8
+    pip install --upgrade sleap-nn[torch] --index-url https://pypi.org/simple --extra-index-url https://download.pytorch.org/whl/cu118
+    ```
+
+=== "Windows/Linux (CPU)"
+    ```bash
+    pip install --upgrade sleap-nn[torch] --index-url https://pypi.org/simple --extra-index-url https://download.pytorch.org/whl/cpu
+    ```
+
+=== "macOS"
+    ```bash
+    pip install --upgrade "sleap-nn[torch]"
+    ```
+
+!!! tip "Upgrading Specific Dependencies"
+    To upgrade a specific dependency like sleap-io independently:
+    ```bash
+    pip install --upgrade sleap-io
+    ```
+
 ---
 
 ## Installation from source
@@ -315,12 +389,27 @@ cd sleap-nn
     uv sync --extra dev --extra torch-cpu
     ```
 
-!!! tip "Upgrading All Dependencies"
-    To ensure you have the latest versions of all dependencies, use the `--upgrade` flag with `uv sync`:
+#### 4. Updating Dependencies
+
+To update sleap-nn and its dependencies to their latest versions:
+
+=== "Windows/Linux (CUDA 11.8)"
     ```bash
-    uv sync --extra dev --upgrade
+    uv sync --extra dev --extra torch-cuda118 --upgrade
     ```
-    This will upgrade all installed packages in your environment to the latest available versions compatible with your `pyproject.toml`.
+
+=== "Windows/Linux (CUDA 12.8)"
+    ```bash
+    uv sync --extra dev --extra torch-cuda128 --upgrade
+    ```
+
+=== "macOS/CPU Only"
+    ```bash
+    uv sync --extra dev --extra torch-cpu --upgrade
+    ```
+
+!!! tip "How --upgrade Works"
+    The `--upgrade` flag refreshes the lockfile and updates all dependencies to their newest compatible versions while maintaining compatibility with your `pyproject.toml` constraints. This ensures you have the latest versions of all dependency packages.
 
 
 ### Verify Installation

docs/sample_configs/config_bottomup_convnext.yaml

@@ -122,7 +122,7 @@ trainer_config:
     step_lr: null
     reduce_lr_on_plateau:
       threshold: 1.0e-06
-      threshold_mode: rel
+      threshold_mode: abs
       cooldown: 3
       patience: 5
       factor: 0.5

docs/sample_configs/config_bottomup_unet_large_rf.yaml

@@ -133,7 +133,7 @@ trainer_config:
     step_lr: null
     reduce_lr_on_plateau:
       threshold: 1.0e-08
-      threshold_mode: rel
+      threshold_mode: abs
       cooldown: 3
       patience: 8
       factor: 0.5

docs/sample_configs/config_bottomup_unet_medium_rf.yaml

@@ -133,7 +133,7 @@ trainer_config:
     step_lr: null
     reduce_lr_on_plateau:
       threshold: 1.0e-08
-      threshold_mode: rel
+      threshold_mode: abs
       cooldown: 3
       patience: 8
       factor: 0.5

docs/sample_configs/config_centroid_swint.yaml

@@ -126,7 +126,7 @@ trainer_config:
     step_lr: null
     reduce_lr_on_plateau:
       threshold: 1.0e-06
-      threshold_mode: rel
+      threshold_mode: abs
       cooldown: 3
       patience: 5
       factor: 0.5

docs/sample_configs/config_centroid_unet.yaml

@@ -127,7 +127,7 @@ trainer_config:
     step_lr: null
     reduce_lr_on_plateau:
       threshold: 1.0e-08
-      threshold_mode: rel
+      threshold_mode: abs
       cooldown: 3
       patience: 5
       factor: 0.5

docs/sample_configs/config_multi_class_bottomup_unet.yaml

@@ -122,7 +122,7 @@ trainer_config:
     step_lr: null
     reduce_lr_on_plateau:
       threshold: 1.0e-06
-      threshold_mode: rel
+      threshold_mode: abs
       cooldown: 3
       patience: 5
       factor: 0.5

docs/sample_configs/config_single_instance_unet_large_rf.yaml

@@ -127,7 +127,7 @@ trainer_config:
     step_lr: null
     reduce_lr_on_plateau:
       threshold: 1.0e-05
-      threshold_mode: rel
+      threshold_mode: abs
       cooldown: 3
       patience: 5
       factor: 0.5

docs/sample_configs/config_single_instance_unet_medium_rf.yaml

@@ -127,7 +127,7 @@ trainer_config:
     step_lr: null
     reduce_lr_on_plateau:
       threshold: 1.0e-08
-      threshold_mode: rel
+      threshold_mode: abs
       cooldown: 3
       patience: 5
       factor: 0.5