lbm_suite2p_python 3.1.1__tar.gz → 3.2.1__tar.gz

{lbm_suite2p_python-3.1.1/lbm_suite2p_python.egg-info → lbm_suite2p_python-3.2.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: lbm_suite2p_python
-Version: 3.1.1
+Version: 3.2.1
 Summary: Calcium Imaging Pipeline built with Suite2p, Cellpose and Rastermap
 License-Expression: BSD-3-Clause
 Project-URL: homepage, https://github.com/MillerBrainObservatory/LBM-Suite2p-Python

{lbm_suite2p_python-3.1.1 → lbm_suite2p_python-3.2.1}/lbm_suite2p_python/cellpose.py

@@ -390,7 +390,7 @@ def cellpose(
     # cellpose eval parameters
     diameter: float = None,
     flow_threshold: float = 0.0,
-    cellprob_threshold: float = -6.0,
+    cellprob_threshold: float = -4.0,
     min_size: int = 2,
     max_size: int = None,
     max_size_fraction: float = None,
@@ -445,9 +445,9 @@ def cellpose(
         Use GPU if available.
     diameter : float, optional
         Expected cell diameter in pixels. If None, Cellpose auto-estimates.
-    flow_threshold : float, default 0.4
-        Maximum allowed error of flows for each mask.
-    cellprob_threshold : float, default 0.0
+    flow_threshold : float, default 0.0
+        Maximum allowed error of flows for each mask (0 = flow check off).
+    cellprob_threshold : float, default -4.0
         Probability threshold for cell detection. Lower = more cells.
     min_size : int, default 2
         Minimum number of pixels per mask.
@@ -932,8 +932,8 @@ def save_gui_results(
     flows: tuple = None,
     styles: np.ndarray = None,
     diameter: float = None,
-    cellprob_threshold: float = 0.0,
-    flow_threshold: float = 0.4,
+    cellprob_threshold: float = -4.0,
+    flow_threshold: float = 0.0,
     name: str = None,
 ) -> Path:
     """

{lbm_suite2p_python-3.1.1 → lbm_suite2p_python-3.2.1}/lbm_suite2p_python/cli.py

@@ -134,13 +134,21 @@ Examples:
         "--planes", nargs="*", type=int, dest="planes",
         help="z-planes to process (1-indexed, e.g., --planes 1 2 3)"
     )
+    pipeline.add_argument(
+        "--timepoints", nargs="*", type=int, dest="timepoints",
+        help="timepoints to process (1-indexed, e.g., --timepoints 1 50 100)"
+    )
     pipeline.add_argument(
         "--roi-mode", "--roi", type=int, dest="roi_mode",
         help="ROI mode: None=stitch, 0=split all, N=specific ROI"
     )
     pipeline.add_argument(
         "--num-timepoints", "--frames", type=int, dest="num_timepoints",
-        help="number of frames/timepoints to process (for quick testing)"
+        help="number of timepoints to process (first N, for quick testing)"
+    )
+    pipeline.add_argument(
+        "--num-zplanes", type=int, dest="num_zplanes",
+        help="number of z-planes to process (first N)"
     )
     pipeline.add_argument(
         "--overwrite", action="store_true",
@@ -566,8 +574,10 @@ def main():
             save_path=output_path,
             ops=ops,
             planes=args.planes,
+            timepoints=args.timepoints,
             roi_mode=args.roi_mode,
             num_timepoints=args.num_timepoints,
+            num_zplanes=args.num_zplanes,
             keep_reg=args.keep_reg,
             keep_raw=args.keep_raw,
             force_reg=args.force_reg or args.overwrite,

{lbm_suite2p_python-3.1.1 → lbm_suite2p_python-3.2.1}/lbm_suite2p_python/conversion.py

@@ -622,8 +622,8 @@ def export_for_gui(suite2p_dir, output_path=None, name=None):
         "filename": str(proj_path),
         "flows": None,
         "est_diam": ops.get("diameter"),
-        "cellprob_threshold": ops.get("cellprob_threshold", 0.0),
-        "flow_threshold": ops.get("flow_threshold", 0.4),
+        "cellprob_threshold": ops.get("cellprob_threshold", -4.0),
+        "flow_threshold": ops.get("flow_threshold", 0.0),
     }
 
     seg_file = output_dir / f"{name}_seg.npy"

{lbm_suite2p_python-3.1.1 → lbm_suite2p_python-3.2.1}/lbm_suite2p_python/default_ops.py

@@ -1,84 +1,96 @@
-"""Default ops for the LBM pipeline.
-
-Historically this module hard-coded a flat ops dict whose values
-diverged from suite2p's own defaults in a handful of fields
-(`batch_size=500`, `chan2_thres=0.65`, `tau=1.3`, `diameter=4`, etc.).
-That divergence made the round-trip through `settings.npy` confusing —
-on-disk values that matched the lsp default were flagged as "modified"
-against suite2p's schema, and vice versa.
-
-This module now exposes exactly suite2p's defaults (the values from
-`suite2p.default_settings()` + `suite2p.default_db()`), flattened to the
-fork's flat-ops shape via the same `db_settings_to_ops` translation
-that the rest of lsp uses. There is now ONE source of truth for "what
-default means": suite2p's parameter schema. Any LBM-specific tweaks
-(diameter, tau, etc.) belong in user code, not in the default.
-"""
-
-from mbo_utilities.metadata import get_param, get_voxel_size
-
-
-def s2p_ops() -> dict:
-    """Suite2p's default ops in flat (fork-style) form.
-
-    Composed from `suite2p.default_settings()` + `suite2p.default_db()`
-    via `db_settings_to_ops`, so the rename map and per-section
-    flat-key disambiguation (e.g. extraction.batch_size →
-    extract_batch_size) are applied consistently.
-    """
-    from suite2p import default_settings, default_db
-    from lbm_suite2p_python.db_settings import db_settings_to_ops
-
-    return db_settings_to_ops(default_db(), default_settings())
-
-
-def default_ops(metadata: dict | None = None, ops: dict | None = None) -> dict:
-    """Return default ops for the LBM Suite2p pipeline.
-
-    Parameters
-    ----------
-    metadata : dict, optional
-        Source-data metadata. When provided, `fs` and the (`dx`, `dy`)
-        voxel-size pair are pulled in from the metadata and overlaid
-        onto the suite2p defaults.
-    ops : dict, optional
-        A user-supplied ops dict to start from. When None, starts from
-        `s2p_ops()` (suite2p's defaults).
-
-    Returns
-    -------
-    dict
-        Flat ops dict ready to be passed to `pipeline()` / `run_plane()`.
-
-    Notes
-    -----
-    `nplanes=1` and `nchannels=1` are forced at the end. The lsp
-    pipeline always processes one plane at a time, so these stay fixed
-    regardless of caller input.
-
-    Examples
-    --------
-    >>> import lbm_suite2p_python as lsp
-    >>> ops = lsp.default_ops()
-    >>> lsp.run_plane(
-    ...     ops=ops,
-    ...     input_tiff="D:/demo/raw_data/raw_file_00001.tif",
-    ...     save_path="D:/demo/results",
-    ...     save_folder="v1",
-    ... )
-    """
-    if ops is None:
-        ops = s2p_ops()
-
-    if metadata is not None:
-        fs = get_param(metadata, "fs")
-        if fs is not None:
-            ops["fs"] = fs
-        voxel = get_voxel_size(metadata)
-        if voxel.dx != 1.0 or voxel.dy != 1.0:
-            ops["dx"] = voxel.dx
-            ops["dy"] = voxel.dy
-
-    ops["nplanes"] = 1
-    ops["nchannels"] = 1
-    return ops
+"""Default ops for the LBM pipeline.
+
+Historically this module hard-coded a flat ops dict whose values
+diverged from suite2p's own defaults in a handful of fields
+(`batch_size=500`, `chan2_thres=0.65`, `tau=1.3`, `diameter=4`, etc.).
+That divergence made the round-trip through `settings.npy` confusing —
+on-disk values that matched the lsp default were flagged as "modified"
+against suite2p's schema, and vice versa.
+
+`s2p_ops()` exposes exactly suite2p's defaults (the values from
+`suite2p.default_settings()` + `suite2p.default_db()`), flattened to the
+fork's flat-ops shape via the same `db_settings_to_ops` translation
+that the rest of lsp uses. `default_ops()` then applies a small set of
+LBM detection defaults (`_LBM_DETECTION_DEFAULTS`) on top, so a notebook,
+a bare `pipeline()` / `run_plane()` call, and the GUI all start from the
+same place. An explicit caller-supplied `ops=` is respected, not overlaid.
+"""
+
+from mbo_utilities.metadata import get_param, get_voxel_size
+
+
+# LBM detection defaults that intentionally differ from suite2p's schema.
+# default_ops() applies these on top of the suite2p mirror so notebook,
+# function-call, and GUI runs share one set of defaults.
+_LBM_DETECTION_DEFAULTS = {
+    "do_regmetrics": False,      # PC reg-quality metrics: ~40s/plane on >=1500 frames
+    "cellprob_threshold": -4.0,  # more permissive than suite2p's 0.0 for LBM data
+    "flow_threshold": 0.0,       # flow check disabled
+}
+
+
+def s2p_ops() -> dict:
+    """Suite2p's default ops in flat (fork-style) form.
+
+    Composed from `suite2p.default_settings()` + `suite2p.default_db()`
+    via `db_settings_to_ops`, so the rename map and per-section
+    flat-key disambiguation (e.g. extraction.batch_size →
+    extract_batch_size) are applied consistently.
+    """
+    from suite2p import default_settings, default_db
+    from lbm_suite2p_python.db_settings import db_settings_to_ops
+
+    return db_settings_to_ops(default_db(), default_settings())
+
+
+def default_ops(metadata: dict | None = None, ops: dict | None = None) -> dict:
+    """Return default ops for the LBM Suite2p pipeline.
+
+    Parameters
+    ----------
+    metadata : dict, optional
+        Source-data metadata. When provided, `fs` and the (`dx`, `dy`)
+        voxel-size pair are pulled in from the metadata and overlaid
+        onto the suite2p defaults.
+    ops : dict, optional
+        A user-supplied ops dict to start from. When None, starts from
+        `s2p_ops()` (suite2p's defaults).
+
+    Returns
+    -------
+    dict
+        Flat ops dict ready to be passed to `pipeline()` / `run_plane()`.
+
+    Notes
+    -----
+    `nplanes=1` and `nchannels=1` are forced at the end. The lsp
+    pipeline always processes one plane at a time, so these stay fixed
+    regardless of caller input.
+
+    Examples
+    --------
+    >>> import lbm_suite2p_python as lsp
+    >>> ops = lsp.default_ops()
+    >>> lsp.run_plane(
+    ...     ops=ops,
+    ...     input_tiff="D:/demo/raw_data/raw_file_00001.tif",
+    ...     save_path="D:/demo/results",
+    ...     save_folder="v1",
+    ... )
+    """
+    if ops is None:
+        ops = s2p_ops()
+        ops.update(_LBM_DETECTION_DEFAULTS)
+
+    if metadata is not None:
+        fs = get_param(metadata, "fs")
+        if fs is not None:
+            ops["fs"] = fs
+        voxel = get_voxel_size(metadata)
+        if voxel.dx != 1.0 or voxel.dy != 1.0:
+            ops["dx"] = voxel.dx
+            ops["dy"] = voxel.dy
+
+    ops["nplanes"] = 1
+    ops["nchannels"] = 1
+    return ops

{lbm_suite2p_python-3.1.1 → lbm_suite2p_python-3.2.1}/lbm_suite2p_python/run_lsp.py

@@ -446,14 +446,15 @@ def _is_valid_torch_checkpoint(path) -> bool:
 def _prewarm_cellpose_model(ops) -> None:
     """Download the cellpose model once, in the parent, before workers fan out.
 
-    cellpose's cache_CPSAM_model_path downloads to a temp file then renames
-    with no cross-process lock. Multiple workers hitting an empty cache at once
+    cellpose's model cache downloads to a temp file then renames with no
+    cross-process lock. Multiple workers hitting an empty cache at once
     race: one wins the rename, the rest fail (Windows WinError 32/183) or read a
     half-written file (PytorchStreamReader miniz error). Warming here serializes
     the download so workers only ever read a complete file. A corrupt leftover
     from a prior failed run is removed and re-downloaded.
     """
-    if not (ops.get("roidetect", True) and ops.get("anatomical_only", 0) > 0):
+    if not (ops.get("roidetect", True)
+            and (ops.get("anatomical_only", 0) > 0 or ops.get("algorithm") == "cellpose")):
         return
     try:
         from cellpose import models as cp_models
@@ -467,7 +468,11 @@ def _prewarm_cellpose_model(ops) -> None:
         except OSError:
             pass
     try:
-        cp_models.cache_CPSAM_model_path()
+        # cellpose 4.x renamed cache_CPSAM_model_path() -> cache_model_path(backbone)
+        if hasattr(cp_models, "cache_model_path"):
+            cp_models.cache_model_path("cpsam")
+        else:
+            cp_models.cache_CPSAM_model_path()
     except Exception as exc:
         print(
             f"Warning: could not pre-download cellpose model ({exc}); "
@@ -780,6 +785,38 @@ def _prepare_plane_ops(*, base_ops, plane_idx, num_planes, input_arr,
     return current_ops
 
 
+def _resolve_timepoints(timepoints=None, frames=None, frame_indices=None):
+    """Resolve the canonical 1-based ``timepoints`` selection.
+
+    ``frames`` (1-based) and ``frame_indices`` (0-based) are deprecated
+    aliases and emit a DeprecationWarning. Returns a 1-based list, or
+    None for all timepoints.
+    """
+    import warnings
+
+    if frames is not None:
+        warnings.warn(
+            "'frames' is deprecated, use 'timepoints' (1-based)",
+            DeprecationWarning,
+            stacklevel=3,
+        )
+        if timepoints is None:
+            timepoints = frames
+    if frame_indices is not None:
+        warnings.warn(
+            "'frame_indices' is deprecated, use 'timepoints' (1-based)",
+            DeprecationWarning,
+            stacklevel=3,
+        )
+        if timepoints is None:
+            timepoints = [int(i) + 1 for i in frame_indices]
+    if timepoints is None:
+        return None
+    if isinstance(timepoints, (int, np.integer)):
+        return [int(timepoints)]
+    return [int(t) for t in timepoints]
+
+
 def pipeline(
     input_data,
     save_path: str | Path = None,
@@ -792,7 +829,10 @@ def pipeline(
     keep_raw: bool = False,
     force_reg: bool = False,
     force_detect: bool = False,
+    replot: bool = True,
+    timepoints: list | int | None = None,
     num_timepoints: int = None,
+    num_zplanes: int = None,
     frame_indices: list | None = None,
     dff_window_size: int = None,
     dff_percentile: int = 20,
@@ -854,16 +894,25 @@ def pipeline(
         Force re-registration even if already complete.
     force_detect : bool, default False
         Force ROI detection even if stat.npy exists.
-    num_timepoints : int, optional
-        Limit processing to first N frames (truncation only). For an
-        explicit set of frames or a strided selection, use
-        ``frame_indices`` instead.
-    frame_indices : list[int], optional
-        Explicit 0-based frame indices to process. Supports stride
-        (e.g. ``list(range(0, 1574, 2))`` for every other frame).
+    replot : bool, default True
+        Regenerate per-plane figures. Set False to skip per-plane figure
+        regeneration (e.g. the volumetric aggregate over already-plotted
+        planes); suite2p and the volumetric plots are unaffected.
+    timepoints : list[int] or int, optional
+        Explicit 1-based timepoints to process. Supports stride
+        (e.g. ``list(range(1, 1575, 2))`` for every other timepoint).
         When provided, the implicit stride is used by `OutputMetadata`
         to reactively scale `fs` (e.g. stride of 2 → `fs / 2` in the
         output ops.npy). Takes precedence over ``num_timepoints``.
+    num_timepoints : int, optional
+        Limit processing to first N timepoints (truncation only). For an
+        explicit set or a strided selection, use ``timepoints`` instead.
+    num_zplanes : int, optional
+        Limit processing to the first N z-planes. Shortcut for
+        ``planes=[1..N]``; ignored when ``planes`` is given.
+    frame_indices : list[int], optional
+        Deprecated alias for ``timepoints`` (0-based). Emits a
+        DeprecationWarning.
     dff_window_size : int, optional
         Window size for rolling percentile dF/F baseline (frames).
         If None, auto-calculated as ~10 * tau * fs.
@@ -976,7 +1025,15 @@ def pipeline(
             DeprecationWarning,
             stacklevel=2,
         )
-        num_timepoints = num_frames
+        if num_timepoints is None:
+            num_timepoints = num_frames
+
+    # canonical 1-based timepoint selection (frames/frame_indices deprecated).
+    timepoints = _resolve_timepoints(timepoints, kwargs.pop("frames", None), frame_indices)
+    frame_indices = None
+    # num_zplanes is a count shortcut for planes=[1..N].
+    if num_zplanes is not None and planes is None:
+        planes = list(range(1, int(num_zplanes) + 1))
 
     # flatten (db, settings) into ops so downstream run_volume / run_plane
     # don't each need to forward the pair. explicit ops keys still win.
@@ -986,14 +1043,10 @@ def pipeline(
 
     reader_kwargs = reader_kwargs or {}
     writer_kwargs = writer_kwargs or {}
+    # num_timepoints truncation reaches the writer; an explicit `timepoints`
+    # selection is forwarded as a param and rebuilt by run_plane.
     if num_timepoints is not None:
-        writer_kwargs["num_frames"] = num_timepoints
-
-    # 1-based frame numbers.
-    if frame_indices is not None:
-        writer_kwargs["frames"] = [int(i) + 1 for i in frame_indices]
-        # don't double-pass num_frames; len(frame_indices) is implicit
-        writer_kwargs.pop("num_frames", None)
+        writer_kwargs["num_timepoints"] = num_timepoints
 
     # Always load array to check dimensions and ensure downstream functions have the array shape
     # If input is already array, this is fast. If path or list of paths, it loads lazy array.
@@ -1028,7 +1081,8 @@ def pipeline(
             keep_raw=keep_raw,
             force_reg=force_reg,
             force_detect=force_detect,
-            frame_indices=frame_indices,
+            replot=replot,
+            timepoints=timepoints,
             dff_window_size=dff_window_size,
             dff_percentile=dff_percentile,
             dff_smooth_window=dff_smooth_window,
@@ -1067,7 +1121,8 @@ def pipeline(
             keep_raw=keep_raw,
             force_reg=force_reg,
             force_detect=force_detect,
-            frame_indices=frame_indices,
+            replot=replot,
+            timepoints=timepoints,
             dff_window_size=dff_window_size,
             dff_percentile=dff_percentile,
             dff_smooth_window=dff_smooth_window,
@@ -1238,6 +1293,10 @@ def run_volume(
     keep_raw: bool = False,
     force_reg: bool = False,
     force_detect: bool = False,
+    replot: bool = True,
+    timepoints: list | int | None = None,
+    num_timepoints: int = None,
+    num_zplanes: int = None,
     frame_indices: list | None = None,
     dff_window_size: int = None,
     dff_percentile: int = 20,
@@ -1281,6 +1340,9 @@ def run_volume(
         Force re-registration.
     force_detect : bool, default False
         Force detection.
+    replot : bool, default True
+        Regenerate per-plane figures (passed to run_plane). Set False to skip
+        per-plane figure regeneration during a volumetric aggregate.
     frame_indices : list, default None
         List of frame indices to process.
     dff_window_size, dff_percentile, dff_smooth_window : optional
@@ -1326,6 +1388,17 @@ def run_volume(
     _resolve_gpu_env()
     _apply_thread_limits(threads_per_worker)
 
+    # canonical 1-based timepoints (frames/frame_indices deprecated); keep a
+    # 0-based frame_indices for this function's reactive-metadata plumbing,
+    # and forward `timepoints` to run_plane.
+    timepoints = _resolve_timepoints(timepoints, kwargs.pop("frames", None), frame_indices)
+    frame_indices = [int(t) - 1 for t in timepoints] if timepoints is not None else None
+    if num_zplanes is not None and planes is None:
+        planes = list(range(1, int(num_zplanes) + 1))
+    writer_kwargs = dict(writer_kwargs or {})
+    if num_timepoints is not None:
+        writer_kwargs.setdefault("num_timepoints", num_timepoints)
+
     # Handle input data
     input_arr = None
     input_paths = []
@@ -1418,7 +1491,8 @@ def run_volume(
         keep_raw=keep_raw,
         force_reg=force_reg,
         force_detect=force_detect,
-        frame_indices=frame_indices,
+        replot=replot,
+        timepoints=timepoints,
         dff_window_size=dff_window_size,
         dff_percentile=dff_percentile,
         dff_smooth_window=dff_smooth_window,
@@ -2270,6 +2344,9 @@ def run_plane(
     keep_reg: bool = True,
     force_reg: bool = False,
     force_detect: bool = False,
+    replot: bool = True,
+    timepoints: list | int | None = None,
+    num_timepoints: int = None,
     frame_indices: list | None = None,
     dff_window_size: int = None,
     dff_percentile: int = 20,
@@ -2314,6 +2391,9 @@ def run_plane(
         If True, force a new registration.
     force_detect : bool, default False
         If True, force ROI detection.
+    replot : bool, default True
+        Generate per-plane figures. Set False to skip figure generation
+        (keeps ROI stats; only the figures are skipped).
     dff_window_size : int, optional
         Frames for rolling percentile baseline. Default: auto-calculated (~10*tau*fs).
     dff_percentile : int, default 20
@@ -2337,13 +2417,18 @@ def run_plane(
         Example: {"n_clusters": 50, "n_PCs": 64}.
     save_json : bool, default False
         Save ops as JSON.
-    frame_indices : list[int], optional
-        Explicit 0-based timepoint indices. Supports stride
-        (e.g. ``list(range(0, 1574, 2))`` for every other frame).
+    timepoints : list[int] or int, optional
+        Explicit 1-based timepoints. Supports stride
+        (e.g. ``list(range(1, 1575, 2))`` for every other timepoint).
         When provided, the binary on disk contains exactly these
-        frames, and `OutputMetadata` reactively scales `fs` in ops.npy
-        based on the implicit stride. Takes precedence over any
-        ``num_frames`` in ``writer_kwargs``.
+        timepoints, and `OutputMetadata` reactively scales `fs` in ops.npy
+        based on the implicit stride. Takes precedence over
+        ``num_timepoints``.
+    num_timepoints : int, optional
+        Limit processing to first N timepoints (truncation only).
+    frame_indices : list[int], optional
+        Deprecated alias for ``timepoints`` (0-based). Emits a
+        DeprecationWarning.
     plane_name : str, optional
         Custom name for the plane subdirectory.
     reader_kwargs : dict, optional
@@ -2363,6 +2448,14 @@ def run_plane(
 
     _resolve_gpu_env()
 
+    # canonical 1-based timepoints (frames/frame_indices deprecated); convert to
+    # the 0-based frame_indices this function consumes internally.
+    timepoints = _resolve_timepoints(timepoints, kwargs.pop("frames", None), frame_indices)
+    frame_indices = [int(t) - 1 for t in timepoints] if timepoints is not None else None
+    writer_kwargs = dict(writer_kwargs or {})
+    if num_timepoints is not None:
+        writer_kwargs.setdefault("num_timepoints", num_timepoints)
+
     progress_callback = kwargs.pop("progress_callback", None)
 
     if "debug" in kwargs:
@@ -2621,7 +2714,8 @@ def run_plane(
         else:
             # prefer the user-specified frame limit over raw array shape
             nframes_hint = (
-                writer_kwargs.get("num_frames")
+                writer_kwargs.get("num_timepoints")
+                or writer_kwargs.get("num_frames")
                 or ops.get("nframes")
             )
             if not nframes_hint and input_arr is not None and hasattr(input_arr, "shape"):
@@ -2650,8 +2744,8 @@ def run_plane(
         ops_file = plane_dir / "ops.npy"
 
         # extract expected dims from input for cache validation
-        # honors writer_kwargs["num_frames"] limit if user requested fewer frames
-        exp_nframes = writer_kwargs.get("num_frames")
+        # honors num_timepoints truncation if user requested fewer frames
+        exp_nframes = writer_kwargs.get("num_timepoints") or writer_kwargs.get("num_frames")
         exp_ly = exp_lx = None
         if input_arr is not None and hasattr(input_arr, "shape"):
             if exp_nframes is None:
@@ -2780,12 +2874,13 @@ def run_plane(
         write_planes = [plane] if _get_num_planes(file) > 1 else None
 
         write_kw = dict(writer_kwargs)
-        # If the caller gave us explicit frame indices, pass them as
-        # `frames=` (1-based) to imwrite. This wins over any stale
-        # `num_frames` truncation in writer_kwargs — strided semantics
-        # require an explicit index list, not a count.
+        # If the caller gave us explicit timepoints, pass them as
+        # `timepoints=` (1-based) to imwrite. This wins over any stale
+        # truncation count in writer_kwargs — strided semantics require an
+        # explicit index list, not a count.
         if frame_indices is not None:
-            write_kw["frames"] = [int(i) + 1 for i in frame_indices]
+            write_kw["timepoints"] = [int(i) + 1 for i in frame_indices]
+            write_kw.pop("num_timepoints", None)
             write_kw.pop("num_frames", None)
 
         imwrite(
@@ -3143,7 +3238,7 @@ def run_plane(
         except Exception as _e:
             print(f"  Warning: persisting post-processing kwargs failed: {_e}")
 
-    # 3b. ROI statistics
+    # 3b. ROI statistics (cheap; feeds the volumetric aggregate, so always run).
     try:
         from lbm_suite2p_python.postprocessing import compute_roi_stats
 
@@ -3152,20 +3247,35 @@ def run_plane(
     except Exception as e:
         print(f"  Warning: ROI stats computation failed: {e}")
 
-    # 4. Plots and Cleanup
-    try:
-        plot_zplane_figures(
-            plane_dir,
-            dff_percentile=dff_percentile,
-            dff_window_size=dff_window_size,
-            dff_smooth_window=dff_smooth_window,
-            norm_method=norm_method,
-            correct_neuropil=correct_neuropil,
-            run_rastermap=rastermap_kwargs is not None,
-            rastermap_kwargs=rastermap_kwargs,
-        )
-    except Exception as e:
-        print(f"  Warning: Plot generation failed: {e}")
+    # 4. Per-plane figures. Timed as the "plots" step (recorded in
+    # processing_history). Skipped when replot=False — e.g. the volumetric
+    # aggregate re-running already-plotted planes, where regenerating the
+    # per-plane figures is the dominant redundant cost.
+    if replot:
+        plot_start = time.time()
+        try:
+            plot_zplane_figures(
+                plane_dir,
+                dff_percentile=dff_percentile,
+                dff_window_size=dff_window_size,
+                dff_smooth_window=dff_smooth_window,
+                norm_method=norm_method,
+                correct_neuropil=correct_neuropil,
+                run_rastermap=rastermap_kwargs is not None,
+                rastermap_kwargs=rastermap_kwargs,
+            )
+        except Exception as e:
+            print(f"  Warning: Plot generation failed: {e}")
+
+        if ops_file.exists():
+            try:
+                _t_ops = load_ops(ops_file)
+                _add_processing_step(_t_ops, "plots", duration_seconds=time.time() - plot_start)
+                save_ops_db_settings(ops_file, _t_ops)
+            except Exception as _e:
+                print(f"  Warning: recording plot timing failed: {_e}")
+    else:
+        print("  replot=False: keeping existing per-plane figures")
 
     if save_json:
         ops_to_json(ops_file)

lbm_suite2p_python-3.2.1/lbm_suite2p_python/utils.py

@@ -0,0 +1,229 @@
+import os
+import numpy as np
+from pathlib import Path
+
+
+# mbo_utilities >= 4.0 exposes a single LazyArray base; isinstance covers
+# every built-in and any third-party plugin. The class-name tuple is the
+# fallback for mbo_utilities < 4.0, which has no shared base.
+try:
+    from mbo_utilities import LazyArray as _LazyArray
+except ImportError:  # mbo_utilities < 4.0
+    _LazyArray = None
+
+_LAZY_ARRAY_TYPES = (
+    "ScanImageArray",
+    "LBMArray",
+    "PiezoArray",
+    "SinglePlaneArray",
+    "Suite2pArray",
+    "MBOTiffArray",
+    "MboRawArray",
+    "TiffArray",
+    "ZarrArray",
+    "H5Array",
+    "NumpyArray",
+    "BinArray",
+)
+
+
+def _is_lazy_array(obj):
+    """Check if obj is an mbo_utilities lazy array type."""
+    if _LazyArray is not None and isinstance(obj, _LazyArray):
+        return True
+    return type(obj).__name__ in _LAZY_ARRAY_TYPES
+
+
+def _get_num_planes(arr):
+    """
+    Get number of z-planes from a lazy array.
+
+    mbo_utilities arrays are always 5D TCZYX, so Z is at shape[2].
+    Falls back to legacy 4D TZYX (Z at shape[1]) and other heuristics
+    for non-mbo arrays.
+
+    Parameters
+    ----------
+    arr : array-like
+        Input array, typically from mbo_utilities.
+
+    Returns
+    -------
+    int
+        Number of z-planes (1 if no Z dimension).
+    """
+    # mbo_utilities Shape5DMixin
+    if hasattr(arr, "nz"):
+        return arr.nz
+    if hasattr(arr, "num_planes") and arr.num_planes is not None:
+        return arr.num_planes
+    shape = arr.shape
+    if len(shape) == 5:
+        return shape[2]  # 5D TCZYX
+    if len(shape) == 4:
+        return shape[1]  # legacy 4D TZYX
+    return 1
+
+
+def _resize_masks_fit_crop(mask, target_shape):
+    """Centers a mask within the target shape, cropping if too large or padding if too small."""
+    sy, sx = mask.shape
+    ty, tx = target_shape
+
+    # If mask is larger, crop it
+    if sy > ty or sx > tx:
+        start_y = (sy - ty) // 2
+        start_x = (sx - tx) // 2
+        return mask[start_y : start_y + ty, start_x : start_x + tx]
+
+    # If mask is smaller, pad it
+    resized_mask = np.zeros(target_shape, dtype=mask.dtype)
+    start_y = (ty - sy) // 2
+    start_x = (tx - sx) // 2
+    resized_mask[start_y : start_y + sy, start_x : start_x + sx] = mask
+    return resized_mask
+
+
+def get_common_path(ops_files: list | tuple):
+    """
+    Find the common parent path of all files.
+
+    Parameters
+    ----------
+    ops_files : list or tuple
+        List of file paths.
+
+    Returns
+    -------
+    Path
+        Common parent directory of all files.
+    """
+    if not isinstance(ops_files, (list, tuple)):
+        ops_files = [ops_files]
+    if len(ops_files) == 1:
+        path = Path(ops_files[0]).parent
+        while (
+            path.exists() and len(list(path.iterdir())) <= 1
+        ):  # Traverse up if only one item exists
+            path = path.parent
+        return path
+    else:
+        return Path(os.path.commonpath(ops_files))
+
+
+def estimate_peak_memory(ops, Ly, Lx, n_frames, device="cuda", workers=1):
+    """
+    Estimate peak memory for one Suite2p plane from its parameters.
+
+    Registration and detection run sequentially in suite2p's pipeline, so
+    the peak for a plane is ``max(registration, detection)``, not the sum.
+    The two stages load different pools:
+
+    - Registration compute runs on ``device``. When ``device`` is cuda the
+      per-batch float32/FFT buffers live in VRAM, scaled by
+      ``batch_size * Ly * Lx``. The reference-image correlation
+      (``pick_initial_reference``) and the binary read stay on host.
+    - Detection's binned movie is a host numpy array, and the default
+      ``sparsery`` / ``sourcery`` detectors run on CPU. ``device`` is only
+      used by the cellpose path, which sees the 2D meanImg / max_proj, not
+      the movie. So the binned movie never enters VRAM.
+
+    Host RAM therefore peaks during detection (binned movie plus the
+    high-pass / sparsery copies, ~2.5x); VRAM peaks during registration
+    (or cellpose inference, when enabled). Neither VRAM term scales with
+    ``n_frames``; host detection plateaus once ``n_frames // bin_size``
+    exceeds ``nbins``.
+
+    Parameters
+    ----------
+    ops : dict
+        Flat Suite2p ops. Reads ``nimg_init``, ``batch_size`` (registration
+        batch), ``nbins``, ``bin_size``, ``tau``, ``fs``, ``nchannels``, and
+        ``anatomical_only``. Missing keys fall back to suite2p defaults.
+    Ly, Lx : int
+        Frame height and width in pixels. The detection crop (yrange/xrange)
+        is unknown before registration, so full ``Ly``/``Lx`` are used as an
+        upper bound.
+    n_frames : int
+        Number of frames in the plane.
+    device : str, optional (default "cuda")
+        Torch device. VRAM terms are reported only when this starts with
+        "cuda".
+    workers : int, optional (default 1)
+        Concurrent plane workers. Per-plane peaks are multiplied by this for
+        the ``*_total`` fields.
+
+    Returns
+    -------
+    dict
+        Bytes for ``host_per_plane``, ``vram_per_plane``, ``host_total``,
+        ``vram_total``. VRAM fields are 0 when ``device`` is not cuda.
+
+    Notes
+    -----
+    The 2.5x detection multiplier and the cpsam VRAM constant are rough; the
+    real values depend on data and hardware. Calibrate with
+    ``torch.cuda.max_memory_allocated()`` and an RSS sample around the
+    registration / detection calls for tight bounds.
+    """
+    cuda = str(device).startswith("cuda")
+
+    nimg_init = min(int(ops.get("nimg_init", 400)), n_frames)
+    reg_host = nimg_init * Ly * Lx * 10  # int16 frames + float64 ref corr (CPU)
+
+    nbins = int(ops.get("nbins", 5000))
+    bin_size = ops.get("bin_size") or max(
+        1, n_frames // nbins, round(ops.get("tau", 1.0) * ops.get("fs", 10.0))
+    )
+    nbinned = min(nbins, n_frames // bin_size)
+    detect_host = int(2.5 * nbinned * Ly * Lx * 4)  # binned movie + hp/sparsery copies (CPU)
+
+    host_peak = max(reg_host, detect_host)
+
+    vram_peak = 0
+    if cuda:
+        reg_batch = int(ops.get("batch_size", 100))
+        nchan = int(ops.get("nchannels", 1))
+        reg_vram = nchan * 8 * reg_batch * Ly * Lx * 4  # ~8 float32/FFT buffers per batch
+        cpsam_vram = 1_500_000_000 if ops.get("anatomical_only", 0) else 0  # cpsam weights + activations
+        vram_peak = max(reg_vram, cpsam_vram)
+
+    return {
+        "host_per_plane": host_peak,
+        "vram_per_plane": vram_peak,
+        "host_total": host_peak * max(1, workers),
+        "vram_total": vram_peak * max(1, workers),
+    }
+
+
+def bin1d(X, bin_size, axis=0):
+    """
+    Mean bin over `axis` of `X` with bin `bin_size`.
+
+    Parameters
+    ----------
+    X : np.ndarray
+        Input array to be binned.
+    bin_size : int
+        Size of the bin. If <=0, no binning is performed.
+    axis : int, optional
+        Axis along which to bin. Default is 0.
+
+    Returns
+    -------
+    np.ndarray
+        Binned array with reduced size along the specified axis.
+    """
+    if bin_size > 0:
+        size = list(X.shape)
+        Xb = X.swapaxes(0, axis)
+        size_new = Xb.shape
+        Xb = (
+            Xb[: size[axis] // bin_size * bin_size]
+            .reshape((size[axis] // bin_size, bin_size, *size_new[1:]))
+            .mean(axis=1)
+        )
+        Xb = Xb.swapaxes(axis, 0)
+        return Xb
+    else:
+        return X

{lbm_suite2p_python-3.1.1 → lbm_suite2p_python-3.2.1/lbm_suite2p_python.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: lbm_suite2p_python
-Version: 3.1.1
+Version: 3.2.1
 Summary: Calcium Imaging Pipeline built with Suite2p, Cellpose and Rastermap
 License-Expression: BSD-3-Clause
 Project-URL: homepage, https://github.com/MillerBrainObservatory/LBM-Suite2p-Python

{lbm_suite2p_python-3.1.1 → lbm_suite2p_python-3.2.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "lbm_suite2p_python"
-version = "3.1.1"
+version = "3.2.1"
 description = "Calcium Imaging Pipeline built with Suite2p, Cellpose and Rastermap"
 readme = "README.md"
 license = "BSD-3-Clause"

lbm_suite2p_python-3.1.1/lbm_suite2p_python/utils.py

@@ -1,144 +0,0 @@
-import os
-import numpy as np
-from pathlib import Path
-
-
-# mbo_utilities >= 4.0 exposes a single LazyArray base; isinstance covers
-# every built-in and any third-party plugin. The class-name tuple is the
-# fallback for mbo_utilities < 4.0, which has no shared base.
-try:
-    from mbo_utilities import LazyArray as _LazyArray
-except ImportError:  # mbo_utilities < 4.0
-    _LazyArray = None
-
-_LAZY_ARRAY_TYPES = (
-    "ScanImageArray",
-    "LBMArray",
-    "PiezoArray",
-    "SinglePlaneArray",
-    "Suite2pArray",
-    "MBOTiffArray",
-    "MboRawArray",
-    "TiffArray",
-    "ZarrArray",
-    "H5Array",
-    "NumpyArray",
-    "BinArray",
-)
-
-
-def _is_lazy_array(obj):
-    """Check if obj is an mbo_utilities lazy array type."""
-    if _LazyArray is not None and isinstance(obj, _LazyArray):
-        return True
-    return type(obj).__name__ in _LAZY_ARRAY_TYPES
-
-
-def _get_num_planes(arr):
-    """
-    Get number of z-planes from a lazy array.
-
-    mbo_utilities arrays are always 5D TCZYX, so Z is at shape[2].
-    Falls back to legacy 4D TZYX (Z at shape[1]) and other heuristics
-    for non-mbo arrays.
-
-    Parameters
-    ----------
-    arr : array-like
-        Input array, typically from mbo_utilities.
-
-    Returns
-    -------
-    int
-        Number of z-planes (1 if no Z dimension).
-    """
-    # mbo_utilities Shape5DMixin
-    if hasattr(arr, "nz"):
-        return arr.nz
-    if hasattr(arr, "num_planes") and arr.num_planes is not None:
-        return arr.num_planes
-    shape = arr.shape
-    if len(shape) == 5:
-        return shape[2]  # 5D TCZYX
-    if len(shape) == 4:
-        return shape[1]  # legacy 4D TZYX
-    return 1
-
-
-def _resize_masks_fit_crop(mask, target_shape):
-    """Centers a mask within the target shape, cropping if too large or padding if too small."""
-    sy, sx = mask.shape
-    ty, tx = target_shape
-
-    # If mask is larger, crop it
-    if sy > ty or sx > tx:
-        start_y = (sy - ty) // 2
-        start_x = (sx - tx) // 2
-        return mask[start_y : start_y + ty, start_x : start_x + tx]
-
-    # If mask is smaller, pad it
-    resized_mask = np.zeros(target_shape, dtype=mask.dtype)
-    start_y = (ty - sy) // 2
-    start_x = (tx - sx) // 2
-    resized_mask[start_y : start_y + sy, start_x : start_x + sx] = mask
-    return resized_mask
-
-
-def get_common_path(ops_files: list | tuple):
-    """
-    Find the common parent path of all files.
-
-    Parameters
-    ----------
-    ops_files : list or tuple
-        List of file paths.
-
-    Returns
-    -------
-    Path
-        Common parent directory of all files.
-    """
-    if not isinstance(ops_files, (list, tuple)):
-        ops_files = [ops_files]
-    if len(ops_files) == 1:
-        path = Path(ops_files[0]).parent
-        while (
-            path.exists() and len(list(path.iterdir())) <= 1
-        ):  # Traverse up if only one item exists
-            path = path.parent
-        return path
-    else:
-        return Path(os.path.commonpath(ops_files))
-
-
-def bin1d(X, bin_size, axis=0):
-    """
-    Mean bin over `axis` of `X` with bin `bin_size`.
-
-    Parameters
-    ----------
-    X : np.ndarray
-        Input array to be binned.
-    bin_size : int
-        Size of the bin. If <=0, no binning is performed.
-    axis : int, optional
-        Axis along which to bin. Default is 0.
-
-    Returns
-    -------
-    np.ndarray
-        Binned array with reduced size along the specified axis.
-    """
-    if bin_size > 0:
-        size = list(X.shape)
-        Xb = X.swapaxes(0, axis)
-        size_new = Xb.shape
-        Xb = (
-            Xb[: size[axis] // bin_size * bin_size]
-            .reshape((size[axis] // bin_size, bin_size, *size_new[1:]))
-            .mean(axis=1)
-        )
-        Xb = Xb.swapaxes(axis, 0)
-        return Xb
-    else:
-        return X