lbm_suite2p_python 3.0.7__tar.gz → 3.1.0__tar.gz

{lbm_suite2p_python-3.0.7/lbm_suite2p_python.egg-info → lbm_suite2p_python-3.1.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: lbm_suite2p_python
-Version: 3.0.7
+Version: 3.1.0
 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.3
+Requires-Dist: mbo_utilities>=3.1.0
 Requires-Dist: suite2p>=1.0.0.1
 Requires-Dist: setuptools<81
 Provides-Extra: rastermap

{lbm_suite2p_python-3.0.7 → lbm_suite2p_python-3.1.0}/lbm_suite2p_python/__init__.py

@@ -70,6 +70,9 @@ 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,
     compute_roi_stats,
 )
@@ -131,6 +134,9 @@ __all__ = [
     "load_ops",
     "load_planar_results",
     "dff_rolling_percentile",
+    "dff_median_filter",
+    "zscore_trace",
+    "baseline_percentile_dff",
     "dff_shot_noise",
     "compute_roi_stats",
 

{lbm_suite2p_python-3.0.7 → lbm_suite2p_python-3.1.0}/lbm_suite2p_python/cli.py

@@ -207,6 +207,11 @@ Examples:
         "--dff-smooth", type=int, dest="dff_smooth_window",
         help="smoothing window for dF/F"
     )
+    dff.add_argument(
+        "--norm-method", choices=["dff", "zscore"], default="zscore",
+        dest="norm_method",
+        help="normalization for norm_traces.npy (default: zscore)"
+    )
     dff.add_argument(
         "--correct-neuropil", dest="correct_neuropil",
         action=argparse.BooleanOptionalAction, default=True,
@@ -570,6 +575,7 @@ def main():
             dff_window_size=args.dff_window_size,
             dff_percentile=args.dff_percentile,
             dff_smooth_window=args.dff_smooth_window,
+            norm_method=args.norm_method,
             correct_neuropil=args.correct_neuropil,
             cell_filters=cell_filters,
             accept_all_cells=args.accept_all_cells,

{lbm_suite2p_python-3.0.7 → lbm_suite2p_python-3.1.0}/lbm_suite2p_python/conversion.py

@@ -871,7 +871,7 @@ def get_results(path, include_traces=True):
         "F": None,
         "Fneu": None,
         "spks": None,
-        "dff": None,
+        "norm_traces": None,
         "ops": None,
         "seg_file": None,
     }
@@ -902,7 +902,7 @@ def get_results(path, include_traces=True):
 
         # Load traces if requested
         if include_traces and fmt == "suite2p":
-            for name in ["F", "Fneu", "spks", "dff"]:
+            for name in ["F", "Fneu", "spks", "norm_traces"]:
                 trace_file = path / f"{name}.npy"
                 if trace_file.exists():
                     result[name] = np.load(trace_file)

{lbm_suite2p_python-3.0.7 → lbm_suite2p_python-3.1.0}/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.7 → lbm_suite2p_python-3.1.0}/lbm_suite2p_python/postprocessing.py

@@ -1162,6 +1162,80 @@ def dff_median_filter(f_trace):
     return (f_trace - f0) / (f0 + 1e-6)  # 1e-6 to avoid division by zero
 
 
+def zscore_trace(f_trace, smooth_window: int = None, fs: float = None, tau: float = None):
+    """
+    Z-score fluorescence traces per ROI: ``(f - mean) / std`` over time.
+
+    One of the ``norm_method`` options for ``norm_traces.npy``. Unlike ΔF/F,
+    output is unitless, centered on 0, and can be negative.
+
+    Parameters
+    ----------
+    f_trace : np.ndarray
+        (N_neurons, N_frames) fluorescence traces.
+    smooth_window : int, optional
+        Temporal smoothing window (frames) applied after z-scoring. If None
+        and both ``tau`` and ``fs`` are given, set to ~0.5 * tau * fs;
+        otherwise no smoothing. Set to 0 or 1 to disable.
+    fs : float, optional
+        Frame rate in Hz. Used with ``tau`` to auto-size ``smooth_window``.
+    tau : float, optional
+        Calcium indicator decay time constant in seconds. Used with ``fs``
+        to auto-size ``smooth_window``.
+
+    Returns
+    -------
+    z : np.ndarray
+        (N_neurons, N_frames) z-scored traces.
+    """
+    from scipy.ndimage import uniform_filter1d
+
+    if not isinstance(f_trace, np.ndarray):
+        raise TypeError("f_trace must be a numpy array")
+    if f_trace.ndim != 2:
+        raise ValueError("f_trace must be a 2D array with shape (N_neurons, N_frames)")
+    if f_trace.shape[0] == 0 or f_trace.shape[1] == 0:
+        raise ValueError("f_trace must not be empty")
+
+    mean = np.mean(f_trace, axis=1, keepdims=True)
+    std = np.std(f_trace, axis=1, keepdims=True)
+    z = (f_trace - mean) / (std + 1e-6)  # 1e-6 to avoid division by zero
+
+    if smooth_window is None and tau is not None and fs is not None:
+        smooth_window = max(1, int(0.5 * tau * fs))
+    if smooth_window is not None and smooth_window > 1:
+        z = uniform_filter1d(z, size=smooth_window, axis=1, mode="nearest")
+
+    return z
+
+
+def baseline_percentile_dff(f_corr, percentile: int = 20):
+    """
+    ΔF/F using a static percentile baseline.
+
+    Used by the SNR, skew, and shot-noise metrics, which always require ΔF/F
+    units regardless of the ``norm_method`` chosen for ``norm_traces.npy``.
+    Kept separate from :func:`dff_rolling_percentile` and :func:`zscore_trace`
+    so the quality metrics never follow the user-selected normalization.
+
+    Parameters
+    ----------
+    f_corr : np.ndarray
+        (N_neurons, N_frames) fluorescence, already neuropil-corrected and
+        rectified as needed by the caller.
+    percentile : int, default 20
+        Percentile for the static baseline F0.
+
+    Returns
+    -------
+    dff : np.ndarray
+        (N_neurons, N_frames) ΔF/F traces.
+    """
+    baseline = np.percentile(f_corr, percentile, axis=1, keepdims=True)
+    baseline = np.maximum(baseline, 1e-6)
+    return (f_corr - baseline) / baseline
+
+
 def dff_shot_noise(dff, fr):
     """
     Estimate the shot noise level of calcium imaging traces.
@@ -1279,10 +1353,8 @@ def compute_trace_quality_score(
         F_corr = F
     F_corr = np.maximum(F_corr, 0)
 
-    # compute baseline and dF/F
-    baseline = np.percentile(F_corr, 20, axis=1, keepdims=True)
-    baseline = np.maximum(baseline, 1e-6)
-    dff = (F_corr - baseline) / baseline
+    # static-baseline ΔF/F for quality metrics only (see baseline_percentile_dff)
+    dff = baseline_percentile_dff(F_corr)
 
     # SNR
     signal = np.std(dff, axis=1)
@@ -1448,9 +1520,8 @@ def compute_roi_stats(plane_dir, fs=None):
     # neuropil correction, rectify negatives, and dF/F
     F_corr = F - 0.7 * Fneu
     F_corr = np.maximum(F_corr, 0)
-    baseline = np.percentile(F_corr, 20, axis=1, keepdims=True)
-    baseline = np.maximum(baseline, 1e-6)
-    dff = (F_corr - baseline) / baseline
+    # static-baseline ΔF/F for quality metrics only (see baseline_percentile_dff)
+    dff = baseline_percentile_dff(F_corr)
 
     # compute metrics
     signal = np.std(dff, axis=1)