update docstrings

eks/core.py

@@ -186,9 +186,9 @@ def run_kalman_smoother(
         Qs: (K, D, D) base process covariances (scaled by `s`).
         ensemble_vars: (T, K, obs) per-frame ensemble variances; used to build
             R_{k,t} via diag(clip(ensemble_vars[t, k, :], 1e-12, ∞)).
-        s_frames: Optional list of (start, end) tuples (1-based, inclusive end)
+        s_frames: Optional list of (start, end) tuples (0-based, half-open [start, end))
             to crop the time axis *for the loss only*. Final smoothing always
-            uses the full sequence.
+            uses the full sequence. Use None for open ends.
         smooth_param: If provided, bypass optimization. Either a scalar (shared
             across all keypoints) or a list/array of length K (per-keypoint).
         blocks: Optional list of lists of keypoint indices; each block shares one
@@ -317,11 +317,12 @@ def optimize_smooth_param(
     s_finals : np.ndarray, shape (K,)
         Output array filled with final per-keypoint `s` (block optimum broadcast
         to all members of that block). Modified in place.
-    s_frames : list[tuple[int, int]] or None
-        Optional list of frame ranges (start, end), using 1-based indexing with
-        inclusive end. These ranges are used to crop the time axis *for the loss
-        computation only* (both y and R_t); optimization ignores frames outside
-        these ranges. If None, all frames [1, T] are used.
+    s_frames : list[tuple[int | None, int | None]] or None
+        Optional list of frame ranges (start, end), using 0-based indexing with
+        half-open intervals [start, end). These ranges are used to crop the time
+        axis *for the loss computation only* (both y and R_t); optimization ignores
+        frames outside these ranges. Use None for open ends. If None, all frames
+        are used.
     s_guess_per_k : np.ndarray, shape (K,)
         Heuristic initial guesses of `s` per keypoint. For each block, the
         initial log(s) is seeded from the mean of member guesses.

eks/ibl_paw_multicam_smoother.py

@@ -40,7 +40,7 @@ def fit_eks_multicam_ibl_paw(
     save_dir: str,
     smooth_param: float | list | None = None,
     s_frames: list | None = None,
-    quantile_keep_pca: float = 95.0,
+    quantile_keep_pca: float = 50.0,
     avg_mode: str = 'median',
     var_mode: str = 'confidence_weighted_var',
     verbose: bool = False,
@@ -55,8 +55,14 @@ def fit_eks_multicam_ibl_paw(
             input_source: Directory path or list of CSV file paths with columns for all cameras.
             save_dir: Directory to save output DataFrame.
             smooth_param: Value in (0, Inf); smaller values lead to more smoothing.
-            s_frames: Frames for automatic optimization if smooth_param is not provided.
-            quantile_keep_pca: Percentage of points kept for PCA (default: 95).
+            s_frames: Frame ranges used to optimize the smoothing parameter, as a list of
+                (start, end) tuples. Indices are 0-based with half-open intervals [start, end),
+                so end is excluded. Use None for open ends: (None, 100) selects frames 0–99,
+                (50, None) selects frame 50 through the last frame. Multiple non-overlapping
+                ranges are allowed, e.g. [(0, 100), (200, 300)]. If None (default), all frames
+                are used. Ignored when smooth_param is provided. Note: only affects parameter
+                optimization; final smoothing always runs over all frames.
+            quantile_keep_pca: Percentage of points kept for PCA (default: 50.0).
             avg_mode: Mode for averaging across ensemble ('median', 'mean').
             var_mode: mode for computing ensemble variance
                 'var' | 'confidence_weighted_var'

eks/ibl_pupil_smoother.py

@@ -111,7 +111,13 @@ def fit_eks_pupil(
         save_file: File to save output dataframe.
         smooth_params: [diameter param, center of mass param]
             each value should be in (0, 1); closer to 1 means more smoothing
-        s_frames: Frames for automatic optimization if needed.
+        s_frames: Frame ranges used to optimize the smoothing parameter, as a list of
+            (start, end) tuples. Indices are 0-based with half-open intervals [start, end),
+            so end is excluded. Use None for open ends: (None, 100) selects frames 0–99,
+            (50, None) selects frame 50 through the last frame. Multiple non-overlapping
+            ranges are allowed, e.g. [(0, 100), (200, 300)]. If None (default), all frames
+            are used. Ignored when smooth_params are fully provided. Note: only affects
+            parameter optimization; final smoothing always runs over all frames.
         avg_mode: mode for averaging across ensemble
             'median' | 'mean'
         var_mode: mode for computing ensemble variance
@@ -173,7 +179,13 @@ def ensemble_kalman_smoother_ibl_pupil(
             each list element is a dataframe of predictions from one ensemble member
         keypoint_names: List of body parts to run smoothing on
         smooth_params: contains smoothing parameters for diameter and center of mass
-        s_frames: frames for automatic optimization if s is not provided
+        s_frames: Frame ranges used to optimize the smoothing parameter, as a list of
+            (start, end) tuples. Indices are 0-based with half-open intervals [start, end),
+            so end is excluded. Use None for open ends: (None, 100) selects frames 0–99,
+            (50, None) selects frame 50 through the last frame. Multiple non-overlapping
+            ranges are allowed, e.g. [(0, 100), (200, 300)]. If None (default), all frames
+            are used. Ignored when smooth_params are fully provided. Note: only affects
+            parameter optimization; final smoothing always runs over all frames.
         avg_mode: mode for averaging across ensemble
             'median' | 'mean'
         var_mode: mode for computing ensemble variance
@@ -444,7 +456,8 @@ def pupil_optimize_smooth(
     x_var, y_var : Real
         Variance scales for com_x and com_y latents.
     s_frames : list[(start, end)] or None
-        1-based start, inclusive end cropping ranges for the loss only.
+        0-based, half-open [start, end) cropping ranges for the loss only.
+        Use None for open ends.
     smooth_params : Optional[Sequence[Real]]
         If provided and both values are not None, bypass optimization and use them directly.
     lr : float

eks/multicam_smoother.py

@@ -30,7 +30,7 @@ def fit_eks_mirrored_multicam(
     smooth_param: float | list | None = None,
     s_frames: list | None = None,
     camera_names: list | None = None,
-    quantile_keep_pca: float = 95.0,
+    quantile_keep_pca: float = 50.0,
     avg_mode: str = 'median',
     var_mode: str = 'confidence_weighted_var',
     verbose: bool = False,
@@ -45,9 +45,15 @@ def fit_eks_mirrored_multicam(
         save_file: Directory to save output DataFrame.
         bodypart_list: List of body parts.
         smooth_param: Value in (0, Inf); smaller values lead to more smoothing.
-        s_frames: Frames for automatic optimization if smooth_param is not provided.
+        s_frames: Frame ranges used to optimize the smoothing parameter, as a list of
+            (start, end) tuples. Indices are 0-based with half-open intervals [start, end),
+            so end is excluded. Use None for open ends: (None, 100) selects frames 0–99,
+            (50, None) selects frame 50 through the last frame. Multiple non-overlapping
+            ranges are allowed, e.g. [(0, 100), (200, 300)]. If None (default), all frames
+            are used. Ignored when smooth_param is provided. Note: only affects parameter
+            optimization; final smoothing always runs over all frames.
         camera_names: List of camera names corresponding to the input data.
-        quantile_keep_pca: Percentage of points kept for PCA (default: 95).
+        quantile_keep_pca: Percentage of points kept for PCA (default: 50.0).
         avg_mode: Mode for averaging across ensemble ('median', 'mean').
         var_mode: mode for computing ensemble variance
             'var' | 'confidence_weighted_var'
@@ -129,7 +135,7 @@ def fit_eks_multicam(
     smooth_param: float | list | None = None,
     s_frames: list | None = None,
     camera_names: list | None = None,
-    quantile_keep_pca: float = 95.0,
+    quantile_keep_pca: float = 50.0,
     avg_mode: str = 'median',
     var_mode: str = 'confidence_weighted_var',
     inflate_vars: bool = False,
@@ -146,9 +152,15 @@ def fit_eks_multicam(
         save_dir: Directory to save output DataFrame.
         bodypart_list: List of body parts.
         smooth_param: Value in (0, Inf); smaller values lead to more smoothing.
-        s_frames: Frames for automatic optimization if smooth_param is not provided.
+        s_frames: Frame ranges used to optimize the smoothing parameter, as a list of
+            (start, end) tuples. Indices are 0-based with half-open intervals [start, end),
+            so end is excluded. Use None for open ends: (None, 100) selects frames 0–99,
+            (50, None) selects frame 50 through the last frame. Multiple non-overlapping
+            ranges are allowed, e.g. [(0, 100), (200, 300)]. If None (default), all frames
+            are used. Ignored when smooth_param is provided. Note: only affects parameter
+            optimization; final smoothing always runs over all frames.
         camera_names: List of camera names corresponding to the input data.
-        quantile_keep_pca: Percentage of points kept for PCA (default: 95).
+        quantile_keep_pca: Percentage of points kept for PCA (default: 50.0).
         avg_mode: Mode for averaging across ensemble ('median', 'mean').
         var_mode: mode for computing ensemble variance
             'var' | 'confidence_weighted_var'
@@ -209,7 +221,7 @@ def ensemble_kalman_smoother_multicam(
     marker_array: MarkerArray,
     keypoint_names: list,
     smooth_param: float | list | None = None,
-    quantile_keep_pca: float = 95.0,
+    quantile_keep_pca: float = 50.0,
     camera_names: list | None = None,
     s_frames: list | None = None,
     avg_mode: str = 'median',
@@ -236,9 +248,15 @@ def ensemble_kalman_smoother_multicam(
             Shape (n_models, n_cameras, n_frames, n_keypoints, 3 (for x, y, likelihood))
         keypoint_names: List of body parts to run smoothing on
         smooth_param: Value in (0, Inf); smaller values lead to more smoothing (default: None).
-        quantile_keep_pca: Percentage of points kept for PCA (default: 95).
+        quantile_keep_pca: Percentage of points kept for PCA (default: 50.0).
         camera_names: List of camera names corresponding to the input data (default: None).
-        s_frames: Frames for auto-optimization if smooth_param is not provided (default: None).
+        s_frames: Frame ranges used to optimize the smoothing parameter, as a list of
+            (start, end) tuples. Indices are 0-based with half-open intervals [start, end),
+            so end is excluded. Use None for open ends: (None, 100) selects frames 0–99,
+            (50, None) selects frame 50 through the last frame. Multiple non-overlapping
+            ranges are allowed, e.g. [(0, 100), (200, 300)]. If None (default), all frames
+            are used. Ignored when smooth_param is provided. Note: only affects parameter
+            optimization; final smoothing always runs over all frames.
         avg_mode: mode for averaging across ensemble
             'median' | 'mean'
         var_mode: mode for computing ensemble variance

eks/singlecam_smoother.py

@@ -30,7 +30,13 @@ def fit_eks_singlecam(
         save_file: File to save output dataframe.
         bodypart_list: list of body parts to analyze.
         smooth_param: value in (0, Inf); smaller values lead to more smoothing
-        s_frames: Frames for automatic optimization if smooth_param is not provided.
+        s_frames: Frame ranges used to optimize the smoothing parameter, as a list of
+            (start, end) tuples. Indices are 0-based with half-open intervals [start, end),
+            so end is excluded. Use None for open ends: (None, 100) selects frames 0–99,
+            (50, None) selects frame 50 through the last frame. Multiple non-overlapping
+            ranges are allowed, e.g. [(0, 100), (200, 300)]. If None (default), all frames
+            are used. Ignored when smooth_param is provided. Note: only affects parameter
+            optimization; final smoothing always runs over all frames.
         blocks: keypoints to be blocked for correlated noise. Generates on smoothing param per
             block, as opposed to per keypoint.
             Specified by the form "x1, x2, x3; y1, y2" referring to keypoint indices (start at 0)
@@ -93,7 +99,13 @@ def ensemble_kalman_smoother_singlecam(
             Shape (n_models, n_cameras, n_frames, n_keypoints, 3 (for x, y, likelihood))
         keypoint_names: List of body parts to run smoothing on
         smooth_param: value in (0, Inf); smaller values lead to more smoothing
-        s_frames: List of frames for automatic computation of smoothing parameter
+        s_frames: Frame ranges used to optimize the smoothing parameter, as a list of
+            (start, end) tuples. Indices are 0-based with half-open intervals [start, end),
+            so end is excluded. Use None for open ends: (None, 100) selects frames 0–99,
+            (50, None) selects frame 50 through the last frame. Multiple non-overlapping
+            ranges are allowed, e.g. [(0, 100), (200, 300)]. If None (default), all frames
+            are used. Ignored when smooth_param is provided. Note: only affects parameter
+            optimization; final smoothing always runs over all frames.
         blocks: keypoints to be blocked for correlated noise. Generates one smoothing param per
             block, as opposed to per keypoint.
             Specified by the form "x1, x2, x3; y1, y2" referring to keypoint indices (start at 0)