lbm_suite2p_python 3.0.8__tar.gz → 3.1.1__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: lbm_suite2p_python
-Version: 3.0.8
+Version: 3.1.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
@@ -11,7 +11,7 @@ Classifier: Programming Language :: Python :: 3 :: Only
 Requires-Python: <3.14,>=3.12.7
 Description-Content-Type: text/markdown
 License-File: LICENSE.md
-Requires-Dist: mbo_utilities>=3.0.7
+Requires-Dist: mbo_utilities>=3.2.1
 Requires-Dist: suite2p>=1.0.0.1
 Requires-Dist: setuptools<81
 Provides-Extra: rastermap

{lbm_suite2p_python-3.0.8 → lbm_suite2p_python-3.1.1}/lbm_suite2p_python/__init__.py

@@ -70,6 +70,7 @@ from lbm_suite2p_python.postprocessing import (
     load_ops,
     load_planar_results,
     dff_rolling_percentile,
+    dff_median_filter,
     zscore_trace,
     baseline_percentile_dff,
     dff_shot_noise,
@@ -133,6 +134,7 @@ __all__ = [
     "load_ops",
     "load_planar_results",
     "dff_rolling_percentile",
+    "dff_median_filter",
     "zscore_trace",
     "baseline_percentile_dff",
     "dff_shot_noise",

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

@@ -208,9 +208,9 @@ Examples:
         help="smoothing window for dF/F"
     )
     dff.add_argument(
-        "--norm-method", choices=["dff", "zscore"], default="dff",
+        "--norm-method", choices=["dff", "zscore"], default="zscore",
         dest="norm_method",
-        help="normalization for norm_traces.npy (default: dff)"
+        help="normalization for norm_traces.npy (default: zscore)"
     )
     dff.add_argument(
         "--correct-neuropil", dest="correct_neuropil",

{lbm_suite2p_python-3.0.8 → lbm_suite2p_python-3.1.1}/lbm_suite2p_python/db_settings.py

@@ -175,20 +175,121 @@ _FORK_TO_UPSTREAM_RENAMES: dict[str, str] = {
     "pretrained_model": "cellpose_model",
 }
 
-# fork's anatomical_only int (1-4) selects which image cellpose runs on.
-# upstream replaced this with a string in cellpose_settings.img. mapping:
-#   1 -> 'max_proj / meanImg'  (log ratio)
-#   2 -> 'meanImg'
-#   3 -> enhanced_mean_img  (REMOVED upstream — no equivalent string;
-#                            falls through to max_proj branch)
-#   4 -> 'max_proj'  (anything not matching the two strings hits else: img=max_proj)
+# fork's anatomical_only int selects which image cellpose runs on;
+# upstream encodes this via cellpose_settings.img. 3 (enhanced mean) was
+# removed from suite2p detection — reconcile_detection_keys maps it to 1.
 _ANATOMICAL_ONLY_TO_IMG: dict[int, str] = {
     1: "max_proj / meanImg",
     2: "meanImg",
     4: "max_proj",
 }
+
+# Values suite2p actually accepts. Mirrors suite2p.parameters:
+# detection.algorithm description -> ['sparsery', 'sourcery', 'cellpose'];
+# cellpose_settings.img description -> ['max_proj / meanImg', 'meanImg',
+# 'max_proj']. Hardcoded (the schema lists these only in a description
+# string) and kept in sync with upstream.
+VALID_DETECTION_ALGORITHMS = ("sparsery", "sourcery", "cellpose")
+VALID_CELLPOSE_IMG = ("max_proj / meanImg", "meanImg", "max_proj")
+
+# legacy / renamed cellpose image spellings -> current suite2p string. the
+# old enhanced-mean image (meanImgE) was removed from suite2p detection, so
+# it maps to suite2p's default; use spatial_hp_cp (highpass_spatial) > 0 to
+# recover the sharpening.
+_LEGACY_IMG_ALIASES = {
+    "meanimge": "max_proj / meanImg",
+    "enhanced_meanimg": "max_proj / meanImg",
+    "enhanced_mean_img": "max_proj / meanImg",
+    "mean_img": "meanImg",
+    "maximg": "max_proj",
+    "max_img": "max_proj",
+    "maxproj": "max_proj",
+}
 _UPSTREAM_TO_FORK_RENAMES = {v: k for k, v in _FORK_TO_UPSTREAM_RENAMES.items()}
 
+
+def reconcile_detection_keys(ops: dict | None) -> dict | None:
+    """Make the flat detection keys consistent and valid for suite2p.
+
+    The fork spells detection as `anatomical_only` (int) / `sparse_mode`
+    (bool); suite2p uses `algorithm` (str). Users mix both. This keeps them
+    mutually consistent and validates them against what suite2p accepts, so
+    either spelling engages identical code paths. Mutates and returns `ops`
+    (no-op for non-dicts); idempotent.
+
+    - `algorithm="cellpose"` with no `anatomical_only` -> `anatomical_only=1`
+      (suite2p's default cellpose image), so the fork's anatomical paths run.
+    - `anatomical_only>0` with no `algorithm` -> `algorithm="cellpose"`.
+    - `algorithm` in {sparsery, sourcery} -> `anatomical_only=0`, `sparse_mode`.
+    - legacy `anatomical_only=3` (enhanced mean, removed upstream) -> 1 + warn.
+    - unknown `algorithm` / `img` -> warn and fall back to a valid value.
+    """
+    import warnings
+
+    if not isinstance(ops, dict):
+        return ops
+
+    algo = ops.get("algorithm")
+    if isinstance(algo, str):
+        algo = algo.strip()
+        if algo in VALID_DETECTION_ALGORITHMS:
+            ops["algorithm"] = algo
+        else:
+            warnings.warn(
+                f"Unknown detection algorithm {ops['algorithm']!r}; suite2p "
+                f"accepts {VALID_DETECTION_ALGORITHMS}. Ignoring it (falling "
+                "back to anatomical_only / suite2p default).",
+                stacklevel=2,
+            )
+            ops.pop("algorithm", None)
+            algo = None
+    else:
+        algo = None
+
+    anat = ops.get("anatomical_only")
+    try:
+        anat_int = int(anat) if anat is not None else None
+    except (TypeError, ValueError):
+        anat_int = None
+
+    if anat_int == 3:
+        warnings.warn(
+            "anatomical_only=3 (enhanced mean image) was removed from suite2p "
+            "detection; using anatomical_only=1 (suite2p default image). Set "
+            "spatial_hp_cp>0 to sharpen the detection image.",
+            stacklevel=2,
+        )
+        anat_int = 1
+        ops["anatomical_only"] = 1
+
+    if algo == "cellpose":
+        if not anat_int or anat_int <= 0:
+            ops["anatomical_only"] = 1  # suite2p's default cellpose image
+    elif algo in ("sparsery", "sourcery"):
+        ops["anatomical_only"] = 0
+        ops.setdefault("sparse_mode", algo == "sparsery")
+    elif algo is None and anat_int and anat_int > 0:
+        ops["algorithm"] = "cellpose"
+
+    img = ops.get("img")
+    if isinstance(img, str) and img not in VALID_CELLPOSE_IMG:
+        mapped = _LEGACY_IMG_ALIASES.get(img.strip().lower())
+        if mapped:
+            warnings.warn(
+                f"cellpose image {img!r} is legacy/renamed; using {mapped!r}.",
+                stacklevel=2,
+            )
+            ops["img"] = mapped
+        else:
+            warnings.warn(
+                f"Unknown cellpose image {img!r}; suite2p accepts "
+                f"{VALID_CELLPOSE_IMG}. Ignoring it (using suite2p default).",
+                stacklevel=2,
+            )
+            ops.pop("img", None)
+
+    return ops
+
 # per-section flat-key disambiguation. Several upstream sections share
 # an upstream key. When flattened to ops, the second iteration overwrites
 # the first; on the reverse derivation, the surviving value gets fanned
@@ -286,8 +387,9 @@ def ops_to_db_settings(ops: dict) -> tuple[dict, dict]:
     settings: dict[str, Any] = {}
 
     # resolve fork→upstream renames into a temporary lookup that
-    # doesn't mutate the caller's ops
-    lookup = dict(ops)
+    # doesn't mutate the caller's ops. reconcile first so algorithm /
+    # anatomical_only / img are consistent and valid before translation.
+    lookup = reconcile_detection_keys(dict(ops))
     for fork_name, upstream_name in _FORK_TO_UPSTREAM_RENAMES.items():
         if fork_name in lookup and upstream_name not in lookup:
             lookup[upstream_name] = lookup[fork_name]
@@ -377,11 +479,9 @@ def ops_to_db_settings(ops: dict) -> tuple[dict, dict]:
         if key in lookup:
             cellpose[key] = lookup[key]
 
-    # fork's anatomical_only int picks which image cellpose runs on.
-    # upstream encodes this via cellpose_settings.img; without this
-    # mapping anatomical_only=4 silently degrades to anatomical_only=1
-    # (the upstream default 'max_proj / meanImg' = log ratio image)
-    # because the translator only sets algorithm='cellpose' otherwise.
+    # fork's anatomical_only int picks which image cellpose runs on;
+    # upstream encodes this via cellpose_settings.img. anatomical_only was
+    # already validated/normalized (incl. legacy 3) by reconcile above.
     anat = lookup.get("anatomical_only")
     if anat and "img" not in cellpose:
         try:
@@ -390,18 +490,6 @@ def ops_to_db_settings(ops: dict) -> tuple[dict, dict]:
             anat_int = None
         if anat_int in _ANATOMICAL_ONLY_TO_IMG:
             cellpose["img"] = _ANATOMICAL_ONLY_TO_IMG[anat_int]
-        elif anat_int == 3:
-            # upstream removed enhanced_mean_img — closest fallback is
-            # 'meanImg' (same source family, no median-ratio enhancement).
-            # warn the caller so they know something changed.
-            import warnings
-            warnings.warn(
-                "anatomical_only=3 (enhanced_mean_img) is no longer supported "
-                "upstream; falling back to cellpose_settings.img='meanImg'. "
-                "Use anatomical_only in {1, 2, 4} to avoid this fallback.",
-                stacklevel=2,
-            )
-            cellpose["img"] = "max_proj"
 
     if cellpose:
         detection["cellpose_settings"] = cellpose

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

@@ -14,7 +14,7 @@ import copy
 import numpy as np
 
 from lbm_suite2p_python.default_ops import default_ops
-from lbm_suite2p_python.db_settings import save_ops_db_settings
+from lbm_suite2p_python.db_settings import save_ops_db_settings, reconcile_detection_keys
 from lbm_suite2p_python.postprocessing import (
     ops_to_json,
     load_ops,
@@ -751,6 +751,7 @@ def _prepare_plane_ops(*, base_ops, plane_idx, num_planes, input_arr,
     """
     plane_num = plane_idx + 1
     current_ops = copy.deepcopy(load_ops(base_ops)) if base_ops else default_ops()
+    reconcile_detection_keys(current_ops)
     current_ops["plane"] = plane_num
     current_ops["num_zplanes"] = num_planes
 
@@ -796,7 +797,7 @@ def pipeline(
     dff_window_size: int = None,
     dff_percentile: int = 20,
     dff_smooth_window: int = None,
-    norm_method: str = "dff",
+    norm_method: str = "zscore",
     correct_neuropil: bool = True,
     cell_filters: list = None,
     accept_all_cells: bool = False,
@@ -827,8 +828,17 @@ def pipeline(
         Output directory for results. If None, saves next to input file.
         Required when input_data is an array without filenames.
     ops : dict, optional
-        Suite2p parameters to override defaults. If None, uses optimized
-        defaults with metadata auto-populated from input.
+        Flat Suite2p parameter overrides (the fork's ops shape). If None,
+        uses suite2p defaults with metadata auto-populated from input.
+        Detection is selectable either way and kept consistent: suite2p's
+        ``"algorithm"`` ("cellpose" / "sparsery" / "sourcery") or the fork's
+        ``"anatomical_only"`` (0=functional, 1=max_proj/mean, 2=mean,
+        4=max_proj). Setting one fills in the other; invalid or legacy
+        values (e.g. ``anatomical_only=3``) are warned and mapped to what
+        suite2p accepts.
+    db, settings : dict, optional
+        suite2p's nested ``db`` / ``settings`` dicts (the new upstream
+        shape). Flattened and merged into ``ops``; explicit ``ops`` keys win.
     planes : int or list, optional
         Which z-planes to process (1-indexed). None processes all planes.
     roi_mode : int, optional
@@ -862,7 +872,7 @@ def pipeline(
     dff_smooth_window : int, optional
         Temporal smoothing window for dF/F traces (frames).
         If None, auto-calculated. Set to 1 to disable.
-    norm_method : str, default "dff"
+    norm_method : str, default "zscore"
         Normalization for the saved norm_traces.npy. "dff" uses the rolling
         percentile ΔF/F (dff_window_size / dff_percentile / dff_smooth_window
         apply); "zscore" uses per-ROI (F - mean) / std. Quality metrics
@@ -1232,7 +1242,7 @@ def run_volume(
     dff_window_size: int = None,
     dff_percentile: int = 20,
     dff_smooth_window: int = None,
-    norm_method: str = "dff",
+    norm_method: str = "zscore",
     correct_neuropil: bool = True,
     accept_all_cells: bool = False,
     cell_filters: list = None,
@@ -1275,7 +1285,7 @@ def run_volume(
         List of frame indices to process.
     dff_window_size, dff_percentile, dff_smooth_window : optional
         dF/F calculation parameters (used when norm_method="dff").
-    norm_method : str, default "dff"
+    norm_method : str, default "zscore"
         Normalization for norm_traces.npy: "dff" or "zscore". See pipeline().
     accept_all_cells : bool, default False
         Mark all ROIs as accepted.
@@ -1381,8 +1391,8 @@ def run_volume(
         else None
     )
     _volume_source_shape = (
-        tuple(input_arr.shape5d)
-        if input_arr is not None and hasattr(input_arr, "shape5d")
+        tuple(input_arr._shape5d())
+        if input_arr is not None and hasattr(input_arr, "_shape5d")
         else None
     )
 
@@ -1530,8 +1540,10 @@ def run_volume(
         )
 
         # Download the cellpose model once before fanning out; concurrent
-        # first-time downloads race on the shared cache file.
-        _prewarm_cellpose_model(ops)
+        # first-time downloads race on the shared cache file. Use a prepared
+        # per-plane ops (already reconciled) so algorithm="cellpose" without
+        # anatomical_only still triggers the warm-up.
+        _prewarm_cellpose_model(prepared[0][1] if prepared else ops)
 
         manager = mp.Manager()
         log_queue = manager.Queue()
@@ -2262,7 +2274,7 @@ def run_plane(
     dff_window_size: int = None,
     dff_percentile: int = 20,
     dff_smooth_window: int = None,
-    norm_method: str = "dff",
+    norm_method: str = "zscore",
     correct_neuropil: bool = True,
     accept_all_cells: bool = False,
     cell_filters: list = None,
@@ -2287,7 +2299,11 @@ def run_plane(
         Root directory to save the results. A subdirectory will be created based on
         the input filename or `plane_name` parameter.
     ops : dict, str or Path, optional
-        Path to or dict of user‐supplied ops.npy.
+        Path to or dict of user‐supplied ops (flat fork shape). Detection
+        accepts suite2p's ``"algorithm"`` or the fork's ``"anatomical_only"``
+        interchangeably (kept consistent; invalid/legacy values warned and
+        mapped to suite2p-valid ones). Pass ``db`` / ``settings`` for the
+        nested upstream shape.
     chan2_file : str, optional
         Path to structural / anatomical data used for registration.
     keep_raw : bool, default False
@@ -2304,7 +2320,7 @@ def run_plane(
         Percentile for baseline F0.
     dff_smooth_window : int, optional
         Smoothing window for dF/F. Default: auto-calculated.
-    norm_method : str, default "dff"
+    norm_method : str, default "zscore"
         Normalization for norm_traces.npy: "dff" (rolling percentile ΔF/F)
         or "zscore" (per-ROI (F - mean) / std). Quality metrics always use
         ΔF/F regardless of this setting.
@@ -2413,6 +2429,9 @@ def run_plane(
     ops_user = load_ops(ops) if ops else {}
     if db is not None or settings is not None:
         ops_user = merge_db_settings_into_ops(ops_user, db, settings)
+    # keep the flat (anatomical_only/sparse_mode) and suite2p (algorithm)
+    # detection spellings consistent + valid before they merge into ops.
+    reconcile_detection_keys(ops_user)
     ops = {**ops_default, **ops_user, "data_path": str(input_path.resolve())}
 
     # normalize kwargs
@@ -2735,7 +2754,7 @@ def run_plane(
             dict(file.metadata) if hasattr(file, "metadata") else None
         )
         _src_shape = (
-            tuple(file.shape5d) if hasattr(file, "shape5d") else None
+            tuple(file._shape5d()) if hasattr(file, "_shape5d") else None
         )
         _apply_reactive_metadata(
             ops=ops,
@@ -2868,13 +2887,11 @@ def run_plane(
                 show_progress=False,
             )
             ops["chan2_file"] = str((plane_dir / "data_chan2.bin").resolve())
-            # Use shape5d (the always-5D contract) so natural-rank arrays
-            # (e.g. a 4D TZYX TiffArray with C=1 squeezed) report the
-            # real T dimension. shape[0] picks Y on a natural 4D array
-            # and crashes/mis-counts on a 2D one — same class of bug
-            # mbo_utilities just fixed in `_imwrite_base`.
-            if hasattr(chan2_data, "shape5d"):
-                ops["nframes_chan2"] = int(chan2_data.shape5d[0])
+            # Use _shape5d() (the always-5D contract) so natural-rank
+            # arrays (BinArray, a 4D TZYX _ChannelView) still report the
+            # real T dimension at index 0.
+            if hasattr(chan2_data, "_shape5d"):
+                ops["nframes_chan2"] = int(chan2_data._shape5d()[0])
             elif hasattr(chan2_data, "shape"):
                 ops["nframes_chan2"] = int(chan2_data.shape[0])
             else:
@@ -2950,6 +2967,10 @@ def run_plane(
                 save_ops_db_settings(ops_file, updated_ops)
 
         except Exception as e:
+            if "no ROIs were found" in str(e):
+                print(f"Warning: no ROIs found for {plane_dir.name}, skipping plane.")
+                _cleanup_bin_files(plane_dir, keep_raw, keep_reg)
+                return ops_file
             print(f"Error in run_plane_bin: {e}")
             traceback.print_exc()
             _cleanup_bin_files(plane_dir, keep_raw, keep_reg)

{lbm_suite2p_python-3.0.8 → lbm_suite2p_python-3.1.1}/lbm_suite2p_python/utils.py

@@ -3,7 +3,14 @@ import numpy as np
 from pathlib import Path
 
 
-# Supported lazy array types from mbo_utilities
+# 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",
@@ -22,6 +29,8 @@ _LAZY_ARRAY_TYPES = (
 
 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
 
 

{lbm_suite2p_python-3.0.8 → lbm_suite2p_python-3.1.1}/lbm_suite2p_python/volume.py

@@ -1891,7 +1891,7 @@ def plot_volume_trace_figures(
     dff_percentile: int = 8,
     dff_window_size: int = None,
     dff_smooth_window: int = None,
-    norm_method: str = "dff",
+    norm_method: str = "zscore",
     correct_neuropil: bool = True,
 ):
     """
@@ -1926,7 +1926,7 @@ def plot_volume_trace_figures(
         model exists, the rastermap heatmap is skipped.
     dff_percentile, dff_window_size, dff_smooth_window
         Forwarded to :func:`dff_rolling_percentile` (when norm_method="dff").
-    norm_method : str, default "dff"
+    norm_method : str, default "zscore"
         Normalization for the norm-trace plots: "dff" or "zscore".
     """
     from types import SimpleNamespace