lbm_suite2p_python 3.0.7__tar.gz → 3.0.8__tar.gz

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

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

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

@@ -70,6 +70,8 @@ from lbm_suite2p_python.postprocessing import (
     load_ops,
     load_planar_results,
     dff_rolling_percentile,
+    zscore_trace,
+    baseline_percentile_dff,
     dff_shot_noise,
     compute_roi_stats,
 )
@@ -131,6 +133,8 @@ __all__ = [
     "load_ops",
     "load_planar_results",
     "dff_rolling_percentile",
+    "zscore_trace",
+    "baseline_percentile_dff",
     "dff_shot_noise",
     "compute_roi_stats",
 

{lbm_suite2p_python-3.0.7 → lbm_suite2p_python-3.0.8}/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="dff",
+        dest="norm_method",
+        help="normalization for norm_traces.npy (default: dff)"
+    )
     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.0.8}/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.0.8}/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)

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

@@ -19,6 +19,7 @@ from lbm_suite2p_python.postprocessing import (
     ops_to_json,
     load_ops,
     dff_rolling_percentile,
+    zscore_trace,
     apply_filters,
 )
 
@@ -163,7 +164,7 @@ def _set_frame_count_aliases(ops: dict, n: int) -> None:
 # user reruns against a different save_path.
 _DETECTION_OUTPUT_FILES = (
     "stat.npy", "iscell.npy", "F.npy", "Fneu.npy",
-    "spks.npy", "dff.npy", "redcell.npy", "zcorr.npy",
+    "spks.npy", "norm_traces.npy", "redcell.npy", "zcorr.npy",
     "reg_outputs.npy", "detect_outputs.npy",
     "F_chan2.npy", "Fneu_chan2.npy",
     "roi_stats.npy",
@@ -496,6 +497,31 @@ def _get_suite2p_version():
         return "not installed"
 
 
+def _resolve_gpu_env() -> None:
+    """Honor MBO_GPU -> CUDA_VISIBLE_DEVICES before torch/cupy/cellpose init.
+
+    Lets ``MBO_GPU=0 lsp ...`` (or programmatic use) force CPU across suite2p
+    and cellpose without per-call device args; ``MBO_GPU=N`` pins a device.
+    No-op when MBO_GPU is unset. Entry points call this first so the env is
+    set before torch initializes CUDA, and before workers are spawned (they
+    inherit it).
+    """
+    raw = os.environ.get("MBO_GPU")
+    if raw is None:
+        return
+    try:
+        from mbo_utilities.gpu import apply_gpu_policy
+        apply_gpu_policy(raw)
+        return
+    except Exception:
+        pass
+    token = raw.strip().lower()
+    if token in ("0", "off", "false", "no", "cpu", "none"):
+        os.environ["CUDA_VISIBLE_DEVICES"] = ""
+    elif token and token.replace(",", "").isdigit():
+        os.environ["CUDA_VISIBLE_DEVICES"] = token
+
+
 def _apply_thread_limits(threads_per_worker: int | None) -> None:
     """Cap BLAS / OMP / numba / torch thread counts per process.
 
@@ -770,6 +796,7 @@ def pipeline(
     dff_window_size: int = None,
     dff_percentile: int = 20,
     dff_smooth_window: int = None,
+    norm_method: str = "dff",
     correct_neuropil: bool = True,
     cell_filters: list = None,
     accept_all_cells: bool = False,
@@ -835,9 +862,15 @@ 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"
+        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
+        (SNR / skew / shot-noise) always use ΔF/F regardless of this setting.
     correct_neuropil : bool, default True
-        If True, dF/F is computed on F - 0.7 * Fneu. If False, on raw F.
-        Affects dff.npy, the dF/F trace plots, and trace-quality scoring.
+        If True, the norm trace is computed on F - 0.7 * Fneu. If False, on
+        raw F. Affects norm_traces.npy, the trace plots, and trace-quality
+        scoring.
     cell_filters : list, optional
         Filters to apply to detected ROIs. Default is no filters (off).
         Currently supports diameter bounds in microns or pixels.
@@ -913,6 +946,7 @@ def pipeline(
 
     _attach_external_loggers()
 
+    _resolve_gpu_env()
     _apply_thread_limits(threads_per_worker)
 
     # 1. Handle Deprecations
@@ -988,6 +1022,7 @@ def pipeline(
             dff_window_size=dff_window_size,
             dff_percentile=dff_percentile,
             dff_smooth_window=dff_smooth_window,
+            norm_method=norm_method,
             correct_neuropil=correct_neuropil,
             accept_all_cells=accept_all_cells,
             cell_filters=cell_filters,
@@ -1026,6 +1061,7 @@ def pipeline(
             dff_window_size=dff_window_size,
             dff_percentile=dff_percentile,
             dff_smooth_window=dff_smooth_window,
+            norm_method=norm_method,
             correct_neuropil=correct_neuropil,
             accept_all_cells=accept_all_cells,
             cell_filters=cell_filters,
@@ -1196,6 +1232,7 @@ def run_volume(
     dff_window_size: int = None,
     dff_percentile: int = 20,
     dff_smooth_window: int = None,
+    norm_method: str = "dff",
     correct_neuropil: bool = True,
     accept_all_cells: bool = False,
     cell_filters: list = None,
@@ -1237,7 +1274,9 @@ def run_volume(
     frame_indices : list, default None
         List of frame indices to process.
     dff_window_size, dff_percentile, dff_smooth_window : optional
-        dF/F calculation parameters.
+        dF/F calculation parameters (used when norm_method="dff").
+    norm_method : str, default "dff"
+        Normalization for norm_traces.npy: "dff" or "zscore". See pipeline().
     accept_all_cells : bool, default False
         Mark all ROIs as accepted.
     cell_filters : list, optional
@@ -1274,6 +1313,7 @@ def run_volume(
     from mbo_utilities import imread
     from lbm_suite2p_python.merging import merge_mrois
 
+    _resolve_gpu_env()
     _apply_thread_limits(threads_per_worker)
 
     # Handle input data
@@ -1372,6 +1412,7 @@ def run_volume(
         dff_window_size=dff_window_size,
         dff_percentile=dff_percentile,
         dff_smooth_window=dff_smooth_window,
+        norm_method=norm_method,
         correct_neuropil=correct_neuropil,
         accept_all_cells=accept_all_cells,
         cell_filters=cell_filters,
@@ -1639,6 +1680,7 @@ def run_volume(
                     save_path,
                     rastermap_kwargs=volumetric_rastermap_kwargs,
                     correct_neuropil=correct_neuropil,
+                    norm_method=norm_method,
                 )
             except Exception as e:
                 print(f"Warning: Volume trace figures failed: {e}")
@@ -2220,6 +2262,7 @@ def run_plane(
     dff_window_size: int = None,
     dff_percentile: int = 20,
     dff_smooth_window: int = None,
+    norm_method: str = "dff",
     correct_neuropil: bool = True,
     accept_all_cells: bool = False,
     cell_filters: list = None,
@@ -2261,6 +2304,10 @@ 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"
+        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.
     accept_all_cells : bool, default False
         If True, mark all detected ROIs as accepted cells.
     cell_filters : list[dict], optional
@@ -2298,6 +2345,8 @@ def run_plane(
     from mbo_utilities import imread, imwrite
     from mbo_utilities.metadata import get_metadata
 
+    _resolve_gpu_env()
+
     progress_callback = kwargs.pop("progress_callback", None)
 
     if "debug" in kwargs:
@@ -3004,12 +3053,12 @@ def run_plane(
         except Exception as e:
             print(f"  Warning: Cell filtering failed: {e}")
 
-    # 3. dF/F Calculation
+    # 3. Normalized-trace calculation (norm_traces.npy)
     F_file = plane_dir / "F.npy"
     Fneu_file = plane_dir / "Fneu.npy"
     if F_file.exists() and Fneu_file.exists():
-        print("  Computing dF/F...")
-        dff_start = time.time()
+        print(f"  Computing norm_traces ({norm_method})...")
+        norm_start = time.time()
         F = np.load(F_file)
         Fneu = np.load(Fneu_file)
         if correct_neuropil:
@@ -3018,21 +3067,29 @@ def run_plane(
             F_corr = F
 
         current_ops = load_ops(ops_file)
-        dff = dff_rolling_percentile(
-            F_corr,
-            window_size=dff_window_size,
-            percentile=dff_percentile,
-            smooth_window=dff_smooth_window,
-            fs=current_ops.get("fs", 30.0),
-            tau=current_ops.get("tau", 1.0),
-        )
-        np.save(plane_dir / "dff.npy", dff)
+        if norm_method == "zscore":
+            norm = zscore_trace(
+                F_corr,
+                smooth_window=dff_smooth_window,
+                fs=current_ops.get("fs", 30.0),
+                tau=current_ops.get("tau", 1.0),
+            )
+        else:
+            norm = dff_rolling_percentile(
+                F_corr,
+                window_size=dff_window_size,
+                percentile=dff_percentile,
+                smooth_window=dff_smooth_window,
+                fs=current_ops.get("fs", 30.0),
+                tau=current_ops.get("tau", 1.0),
+            )
+        np.save(plane_dir / "norm_traces.npy", norm)
 
         _add_processing_step(
             current_ops,
-            "dff_calculation",
-            duration_seconds=time.time() - dff_start,
-            extra={"percentile": dff_percentile},
+            "norm_calculation",
+            duration_seconds=time.time() - norm_start,
+            extra={"method": norm_method, "percentile": dff_percentile},
         )
         save_ops_db_settings(ops_file, current_ops)
 
@@ -3050,6 +3107,7 @@ def run_plane(
             _post_ops["dff_window_size"] = dff_window_size
             _post_ops["dff_percentile"] = dff_percentile
             _post_ops["dff_smooth_window"] = dff_smooth_window
+            _post_ops["norm_method"] = norm_method
             _post_ops["correct_neuropil"] = bool(correct_neuropil)
             _post_ops["accept_all_cells"] = bool(accept_all_cells)
             _post_ops["save_json"] = bool(save_json)
@@ -3080,6 +3138,7 @@ def run_plane(
             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,

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

@@ -7,7 +7,7 @@ import numpy as np
 from matplotlib import pyplot as plt
 
 from lbm_suite2p_python.utils import get_common_path
-from lbm_suite2p_python.postprocessing import load_ops
+from lbm_suite2p_python.postprocessing import load_ops, baseline_percentile_dff
 
 
 def update_ops_paths(ops_files: str | list):
@@ -777,10 +777,9 @@ def plot_volume_diagnostics(
         n_rejected = int(np.sum(~iscell))
 
         # Compute SNR for accepted cells
+        # static-baseline ΔF/F for quality metrics only (see baseline_percentile_dff)
         F_corr = F - 0.7 * Fneu
-        baseline = np.percentile(F_corr, 20, axis=1, keepdims=True)
-        baseline = np.maximum(baseline, 1e-6)
-        dff = (F_corr - baseline) / baseline
+        dff = baseline_percentile_dff(F_corr)
 
         signal = np.std(dff, axis=1)
         noise = np.median(np.abs(np.diff(dff, axis=1)), axis=1) / 0.6745
@@ -1356,10 +1355,9 @@ def plot_3d_roi_map(
             if F_file.exists():
                 F = np.load(F_file, allow_pickle=True)
                 Fneu = np.load(Fneu_file, allow_pickle=True) if Fneu_file.exists() else np.zeros_like(F)
+                # static-baseline ΔF/F for quality metrics only (see baseline_percentile_dff)
                 F_corr = F - 0.7 * Fneu
-                baseline = np.percentile(F_corr, 20, axis=1, keepdims=True)
-                baseline = np.maximum(baseline, 1e-6)
-                dff = (F_corr - baseline) / baseline
+                dff = baseline_percentile_dff(F_corr)
                 signal = np.std(dff, axis=1)
                 noise = np.median(np.abs(np.diff(dff, axis=1)), axis=1) / 0.6745
                 color_vals = signal / (noise + 1e-6)
@@ -1893,6 +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",
     correct_neuropil: bool = True,
 ):
     """
@@ -1905,9 +1904,9 @@ def plot_volume_trace_figures(
 
     - ``volume_trace_analysis.png`` — :func:`plot_trace_analysis` 6-panel
       extremes by SNR / shot noise / skewness, drawn from the volume.
-    - ``volume_traces_raw_{N}.png`` and ``volume_traces_dff_{N}.png`` for
+    - ``volume_traces_raw_{N}.png`` and ``volume_traces_norm_{N}.png`` for
       each ``N`` in ``cell_counts`` — top-N accepted cells by quality
-      score, raw and rolling-percentile dF/F.
+      score, raw and normalized (norm_method) traces.
     - ``rastermap.png`` — sorted-activity heatmap, if either a saved
       ``rastermap_model.npy`` exists in ``save_path`` (written by
       :func:`plot_3d_rastermap_clusters`) or ``rastermap_kwargs`` is
@@ -1926,13 +1925,16 @@ def plot_volume_trace_figures(
         kwargs (merged over count-aware defaults). If None and no cached
         model exists, the rastermap heatmap is skipped.
     dff_percentile, dff_window_size, dff_smooth_window
-        Forwarded to :func:`dff_rolling_percentile`.
+        Forwarded to :func:`dff_rolling_percentile` (when norm_method="dff").
+    norm_method : str, default "dff"
+        Normalization for the norm-trace plots: "dff" or "zscore".
     """
     from types import SimpleNamespace
     from lbm_suite2p_python.postprocessing import (
         load_planar_results,
         compute_trace_quality_score,
         dff_rolling_percentile,
+        zscore_trace,
     )
     from lbm_suite2p_python.zplane import (
         plot_traces,
@@ -2004,15 +2006,24 @@ def plot_volume_trace_figures(
     stat_acc = [s for s, m in zip(stat, iscell_mask) if m]
 
     try:
-        F_for_dff = (F_acc - 0.7 * Fneu_acc) if correct_neuropil else F_acc
-        dffp = dff_rolling_percentile(
-            F_for_dff,
-            percentile=dff_percentile,
-            window_size=dff_window_size,
-            smooth_window=dff_smooth_window,
-            fs=fs,
-            tau=tau,
-        ) * 100
+        F_for_norm = (F_acc - 0.7 * Fneu_acc) if correct_neuropil else F_acc
+        if norm_method == "zscore":
+            norm = zscore_trace(
+                F_for_norm, smooth_window=dff_smooth_window, fs=fs, tau=tau
+            )
+            norm_unit = "z-score"
+            norm_label = "Z-Score"
+        else:
+            norm = dff_rolling_percentile(
+                F_for_norm,
+                percentile=dff_percentile,
+                window_size=dff_window_size,
+                smooth_window=dff_smooth_window,
+                fs=fs,
+                tau=tau,
+            ) * 100
+            norm_unit = r"% $\Delta$F/F$_0$"
+            norm_label = r"$\Delta$F/F"
 
         quality = compute_trace_quality_score(
             F_acc,
@@ -2022,17 +2033,17 @@ def plot_volume_trace_figures(
         )
         sort_idx = quality["sort_idx"]
         F_sorted = F_acc[sort_idx]
-        dffp_sorted = dffp[sort_idx]
+        norm_sorted = norm[sort_idx]
 
         for n_cells in cell_counts:
             n = min(int(n_cells), n_accepted)
             plot_traces(
-                dffp_sorted,
-                save_path=save_path / f"volume_traces_dff_{n_cells}.png",
+                norm_sorted,
+                save_path=save_path / f"volume_traces_norm_{n_cells}.png",
                 num_neurons=n,
                 fps=fs,
-                scale_bar_unit=r"% $\Delta$F/F$_0$",
-                title=rf"Volume Top {n} $\Delta$F/F Traces by Quality (n={n_accepted} total)",
+                scale_bar_unit=norm_unit,
+                title=rf"Volume Top {n} {norm_label} Traces by Quality (n={n_accepted} total)",
             )
             plot_traces(
                 F_sorted,

{lbm_suite2p_python-3.0.7 → lbm_suite2p_python-3.0.8}/lbm_suite2p_python/zplane.py

@@ -21,6 +21,8 @@ from lbm_suite2p_python.postprocessing import (
     load_ops,
     load_planar_results,
     dff_rolling_percentile,
+    zscore_trace,
+    baseline_percentile_dff,
     dff_shot_noise,
     compute_trace_quality_score,
 )
@@ -35,9 +37,10 @@ def infer_units(f: np.ndarray) -> str:
     Infer calcium imaging signal type from array values:
     - 'raw': values in hundreds or thousands
     - 'dff': unitless ΔF/F₀, typically ~0–1
-    - 'dff-percentile': ΔF/F₀ in percent, typically ~10–100
+    - 'dffp': ΔF/F₀ in percent, typically ~10–100
+    - 'zscore': centered on 0 with negatives, unit-scale std
 
-    Returns one of: 'raw', 'dff', 'dff-percentile'
+    Returns one of: 'raw', 'dff', 'dffp', 'zscore', 'unknown'
     """
     f = np.asarray(f)
     if np.issubdtype(f.dtype, np.integer):
@@ -51,6 +54,8 @@ def infer_units(f: np.ndarray) -> str:
         return "dffp"
     elif 0.1 < p1 < 0.2 < p50 < 0.5 < p99 < 1.0:
         return "dff"
+    elif p1 < 0 and abs(p50) < 1 and p99 > 0:
+        return "zscore"
     else:
         return "unknown"
 
@@ -314,7 +319,7 @@ def plot_traces(
     ----------
     f : ndarray or str or Path
         2d array of fluorescence traces (n_neurons x n_timepoints),
-        or path to Suite2p plane directory containing dff.npy/F.npy.
+        or path to Suite2p plane directory containing norm_traces.npy/F.npy.
     save_path : str, optional
         Path to save the output plot.
     fps : float
@@ -345,22 +350,25 @@ def plot_traces(
     if isinstance(f, (str, Path)):
         plane_dir = Path(f)
         if plane_dir.is_dir():
-            # Try to load dff.npy first, fall back to F.npy
-            dff_path = plane_dir / "dff.npy"
+            # Try to load norm_traces.npy first, fall back to F.npy
+            norm_path = plane_dir / "norm_traces.npy"
             f_path = plane_dir / "F.npy"
             iscell_path = plane_dir / "iscell.npy"
             ops_path = plane_dir / "ops.npy"
 
-            if dff_path.exists():
-                f = np.load(dff_path)
+            if norm_path.exists():
+                f = np.load(norm_path)
                 if scale_bar_unit is None:
-                    scale_bar_unit = r"% $\Delta$F/F$_0$"
+                    scale_bar_unit = (
+                        "z-score" if infer_units(f) == "zscore"
+                        else r"% $\Delta$F/F$_0$"
+                    )
             elif f_path.exists():
                 f = np.load(f_path)
                 if scale_bar_unit is None:
                     scale_bar_unit = "a.u."
             else:
-                raise FileNotFoundError(f"No dff.npy or F.npy found in {plane_dir}")
+                raise FileNotFoundError(f"No norm_traces.npy or F.npy found in {plane_dir}")
 
             # Filter to accepted cells if iscell exists and no cell_indices provided
             if cell_indices is None and iscell_path.exists():
@@ -2161,11 +2169,9 @@ def plot_trace_analysis(
     plane_nums = np.array([s.get("iplane", 0) for s in stat_acc])
     fs = ops.get("fs", 30.0)
 
-    # Compute ΔF/F
+    # static-baseline ΔF/F for quality metrics only (see baseline_percentile_dff)
     F_corrected = F_acc - 0.7 * Fneu_acc
-    baseline = np.percentile(F_corrected, 20, axis=1, keepdims=True)
-    baseline = np.maximum(baseline, 1e-6)
-    dff = (F_corrected - baseline) / baseline
+    dff = baseline_percentile_dff(F_corrected)
 
     # Compute metrics
     # SNR: signal / noise
@@ -2356,10 +2362,9 @@ def create_volume_summary_table(
     if F is not None and Fneu is not None:
         F_acc = F[accepted]
         Fneu_acc = Fneu[accepted]
+        # static-baseline ΔF/F for quality metrics only (see baseline_percentile_dff)
         F_corrected = F_acc - 0.7 * Fneu_acc
-        baseline = np.percentile(F_corrected, 20, axis=1, keepdims=True)
-        baseline = np.maximum(baseline, 1e-6)
-        dff = (F_corrected - baseline) / baseline
+        dff = baseline_percentile_dff(F_corrected)
         signal = np.std(dff, axis=1)
         noise = np.median(np.abs(np.diff(dff, axis=1)), axis=1) / 0.6745
         snr = signal / (noise + 1e-6)
@@ -2657,10 +2662,9 @@ def plot_plane_diagnostics(
     n_rejected = int((~accepted).sum())
 
     # Compute metrics for ALL ROIs (not just accepted)
+    # static-baseline ΔF/F for quality metrics only (see baseline_percentile_dff)
     F_corr = F - 0.7 * Fneu
-    baseline = np.percentile(F_corr, 20, axis=1, keepdims=True)
-    baseline = np.maximum(baseline, 1e-6)
-    dff = (F_corr - baseline) / baseline
+    dff = baseline_percentile_dff(F_corr)
 
     # SNR calculation for all ROIs
     signal = np.std(dff, axis=1)
@@ -3052,7 +3056,8 @@ def mask_dead_zones_in_ops(ops, threshold=0.01):
 
 def plot_zplane_figures(
     plane_dir, dff_percentile=20, dff_window_size=None, dff_smooth_window=None,
-    correct_neuropil=True, run_rastermap=False, rastermap_kwargs=None, **kwargs
+    norm_method="dff", correct_neuropil=True, run_rastermap=False,
+    rastermap_kwargs=None, **kwargs
 ):
     """
     Re-generate Suite2p figures for a merged plane.
@@ -3062,7 +3067,7 @@ def plot_zplane_figures(
     plane_dir : Path
         Path to the planeXX output directory (with ops.npy, stat.npy, etc.).
     dff_percentile : int, optional
-        Percentile used for ΔF/F baseline.
+        Percentile used for ΔF/F baseline (when norm_method="dff").
     dff_window_size : int, optional
         Window size for ΔF/F rolling baseline. If None, auto-calculated
         as ~10 × tau × fs based on ops values.
@@ -3070,6 +3075,8 @@ def plot_zplane_figures(
         Temporal smoothing window for dF/F traces (in frames).
         If None, auto-calculated as ~0.5 × tau × fs to emphasize
         transients while reducing noise. Set to 1 to disable.
+    norm_method : str, default "dff"
+        Normalization used for the norm-trace plots: "dff" or "zscore".
     run_rastermap : bool, optional
         If True, compute and plot rastermap sorting of cells.
     rastermap_kwargs : dict, optional
@@ -3106,9 +3113,9 @@ def plot_zplane_figures(
         "traces_raw_20": plane_dir / "07a_traces_raw_20.png",
         "traces_raw_50": plane_dir / "07b_traces_raw_50.png",
         "traces_raw_100": plane_dir / "07c_traces_raw_100.png",
-        "traces_dff_20": plane_dir / "08a_traces_dff_20.png",
-        "traces_dff_50": plane_dir / "08b_traces_dff_50.png",
-        "traces_dff_100": plane_dir / "08c_traces_dff_100.png",
+        "traces_norm_20": plane_dir / "08a_traces_norm_20.png",
+        "traces_norm_50": plane_dir / "08b_traces_norm_50.png",
+        "traces_norm_100": plane_dir / "08c_traces_norm_100.png",
         "traces_rejected": plane_dir / "09_traces_rejected.png",
         # Noise distributions
         "noise_acc": plane_dir / "10_shot_noise_accepted.png",
@@ -3138,9 +3145,9 @@ def plot_zplane_figures(
         "traces_raw_20",
         "traces_raw_50",
         "traces_raw_100",
-        "traces_dff_20",
-        "traces_dff_50",
-        "traces_dff_100",
+        "traces_norm_20",
+        "traces_norm_50",
+        "traces_norm_100",
         "traces_rejected",
         "noise_acc",
         "noise_rej",
@@ -3166,8 +3173,8 @@ def plot_zplane_figures(
 
         # F (raw) feeds the "raw" trace plots and compute_trace_quality_score
         # (which optionally subtracts Fneu internally). F_for_dff is the input
-        # to dff_rolling_percentile — neuropil-corrected only when the toggle
-        # is on, matching dff.npy.
+        # to the norm-trace recompute — neuropil-corrected only when the
+        # toggle is on, matching norm_traces.npy.
         if correct_neuropil and Fneu is not None:
             F_for_dff = F - 0.7 * Fneu
         else:
@@ -3431,9 +3438,8 @@ def plot_zplane_figures(
             fs = output_ops.get("fs", 1.0)
             tau = output_ops.get("tau", 1.0)
 
-            # resolve auto-calculated dF/F window sizes the same way
-            # dff_rolling_percentile does, so the param footer reflects
-            # the values actually used
+            # resolve auto-calculated window sizes the same way the trace
+            # functions do, so the param footer reflects the values used
             _resolved_window = (
                 int(dff_window_size) if dff_window_size is not None
                 else (int(10 * tau * fs) if (fs and tau) else 300)
@@ -3442,56 +3448,62 @@ def plot_zplane_figures(
                 int(dff_smooth_window) if dff_smooth_window is not None
                 else (max(1, int(0.5 * tau * fs)) if (fs and tau) else 1)
             )
-            dff_param_text = (
-                f"dff_percentile={dff_percentile}  "
-                f"window={_resolved_window}f ({_resolved_window / fs:.1f}s)  "
-                f"smooth={_resolved_smooth}f ({_resolved_smooth / fs:.2f}s)  "
-                f"fs={fs:.2f}Hz  tau={tau:.2f}s  "
-                f"neuropil={'on' if correct_neuropil else 'off'}"
-            )
+            # method-aware labels for the norm-trace plots
+            if norm_method == "zscore":
+                norm_unit = "z-score"
+                norm_label = "Z-Score"
+                norm_param_text = (
+                    f"norm=zscore  "
+                    f"smooth={_resolved_smooth}f ({_resolved_smooth / fs:.2f}s)  "
+                    f"fs={fs:.2f}Hz  tau={tau:.2f}s  "
+                    f"neuropil={'on' if correct_neuropil else 'off'}"
+                )
+            else:
+                norm_unit = r"% $\Delta$F/F$_0$"
+                norm_label = r"$\Delta$F/F"
+                norm_param_text = (
+                    f"dff_percentile={dff_percentile}  "
+                    f"window={_resolved_window}f ({_resolved_window / fs:.1f}s)  "
+                    f"smooth={_resolved_smooth}f ({_resolved_smooth / fs:.2f}s)  "
+                    f"fs={fs:.2f}Hz  tau={tau:.2f}s  "
+                    f"neuropil={'on' if correct_neuropil else 'off'}"
+                )
 
-            # unsmoothed dF/F for shot noise
-            if n_accepted > 0:
-                dffp_acc_unsmoothed = dff_rolling_percentile(
-                    F_dff_accepted,
-                    percentile=dff_percentile,
-                    window_size=dff_window_size,
-                    smooth_window=1,
-                    fs=fs,
-                    tau=tau,
-                ) * 100
-                dffp_acc = dff_rolling_percentile(
-                    F_dff_accepted,
+            def _norm_for_display(F_in):
+                # display trace, follows norm_method
+                if F_in.shape[0] == 0:
+                    return np.zeros((0, F.shape[1]))
+                if norm_method == "zscore":
+                    return zscore_trace(
+                        F_in, smooth_window=dff_smooth_window, fs=fs, tau=tau
+                    )
+                return dff_rolling_percentile(
+                    F_in,
                     percentile=dff_percentile,
                     window_size=dff_window_size,
                     smooth_window=dff_smooth_window,
                     fs=fs,
                     tau=tau,
                 ) * 100
-            else:
-                dffp_acc_unsmoothed = np.zeros((0, F.shape[1]))
-                dffp_acc = np.zeros((0, F.shape[1]))
 
-            if n_rejected > 0:
-                dffp_rej_unsmoothed = dff_rolling_percentile(
-                    F_dff_rejected,
+            def _dff_unsmoothed(F_in):
+                # always ΔF/F (%): shot noise is defined on ΔF/F regardless
+                # of the selected norm_method
+                if F_in.shape[0] == 0:
+                    return np.zeros((0, F.shape[1]))
+                return dff_rolling_percentile(
+                    F_in,
                     percentile=dff_percentile,
                     window_size=dff_window_size,
                     smooth_window=1,
                     fs=fs,
                     tau=tau,
                 ) * 100
-                dffp_rej = dff_rolling_percentile(
-                    F_dff_rejected,
-                    percentile=dff_percentile,
-                    window_size=dff_window_size,
-                    smooth_window=dff_smooth_window,
-                    fs=fs,
-                    tau=tau,
-                ) * 100
-            else:
-                dffp_rej_unsmoothed = np.zeros((0, F.shape[1]))
-                dffp_rej = np.zeros((0, F.shape[1]))
+
+            norm_acc = _norm_for_display(F_dff_accepted)
+            norm_rej = _norm_for_display(F_dff_rejected)
+            dff_acc_unsmoothed = _dff_unsmoothed(F_dff_accepted)
+            dff_rej_unsmoothed = _dff_unsmoothed(F_dff_rejected)
 
             if n_accepted > 0:
                 stat_accepted = [s for s, m in zip(res["stat"], iscell_mask) if m]
@@ -3504,19 +3516,19 @@ def plot_zplane_figures(
                     fs=fs,
                 )
                 quality_sort_idx = quality["sort_idx"]
-                dffp_acc_sorted = dffp_acc[quality_sort_idx]
+                norm_acc_sorted = norm_acc[quality_sort_idx]
                 F_accepted_sorted = F_accepted[quality_sort_idx]
 
                 cell_counts = [20, 50, 100]
                 for n_cells in cell_counts:
                     if n_accepted >= n_cells:
                         plot_traces(
-                            dffp_acc_sorted,
-                            save_path=expected_files[f"traces_dff_{n_cells}"],
+                            norm_acc_sorted,
+                            save_path=expected_files[f"traces_norm_{n_cells}"],
                             num_neurons=n_cells,
-                            scale_bar_unit=r"% $\Delta$F/F$_0$",
-                            title=rf"Top {n_cells} $\Delta$F/F Traces by Quality (n={n_accepted} total)",
-                            fig_text=dff_param_text,
+                            scale_bar_unit=norm_unit,
+                            title=rf"Top {n_cells} {norm_label} Traces by Quality (n={n_accepted} total)",
+                            fig_text=norm_param_text,
                         )
                         plot_traces(
                             F_accepted_sorted,
@@ -3527,12 +3539,12 @@ def plot_zplane_figures(
                         )
                     elif n_cells == 20:
                         plot_traces(
-                            dffp_acc_sorted,
-                            save_path=expected_files["traces_dff_20"],
+                            norm_acc_sorted,
+                            save_path=expected_files["traces_norm_20"],
                             num_neurons=min(20, n_accepted),
-                            scale_bar_unit=r"% $\Delta$F/F$_0$",
-                            title=rf"Top {min(20, n_accepted)} $\Delta$F/F Traces by Quality (n={n_accepted} total)",
-                            fig_text=dff_param_text,
+                            scale_bar_unit=norm_unit,
+                            title=rf"Top {min(20, n_accepted)} {norm_label} Traces by Quality (n={n_accepted} total)",
+                            fig_text=norm_param_text,
                         )
                         plot_traces(
                             F_accepted_sorted,
@@ -3546,19 +3558,19 @@ def plot_zplane_figures(
 
             if n_rejected > 0:
                 plot_traces(
-                    dffp_rej,
+                    norm_rej,
                     save_path=expected_files["traces_rejected"],
                     num_neurons=min(20, n_rejected),
-                    scale_bar_unit=r"% $\Delta$F/F$_0$",
-                    title=rf"$\Delta$F/F Traces - Rejected ROIs (n={n_rejected})",
-                    fig_text=dff_param_text,
+                    scale_bar_unit=norm_unit,
+                    title=rf"{norm_label} Traces - Rejected ROIs (n={n_rejected})",
+                    fig_text=norm_param_text,
                 )
             else:
                 print("  No rejected ROIs - skipping rejected trace plots")
 
             # noise distributions
             if n_accepted > 0:
-                dff_noise_acc = dff_shot_noise(dffp_acc_unsmoothed, fs)
+                dff_noise_acc = dff_shot_noise(dff_acc_unsmoothed, fs)
                 plot_noise_distribution(
                     dff_noise_acc,
                     output_filename=expected_files["noise_acc"],
@@ -3566,7 +3578,7 @@ def plot_zplane_figures(
                 )
 
             if n_rejected > 0:
-                dff_noise_rej = dff_shot_noise(dffp_rej_unsmoothed, fs)
+                dff_noise_rej = dff_shot_noise(dff_rej_unsmoothed, fs)
                 plot_noise_distribution(
                     dff_noise_rej,
                     output_filename=expected_files["noise_rej"],

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

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

{lbm_suite2p_python-3.0.7 → lbm_suite2p_python-3.0.8}/lbm_suite2p_python.egg-info/requires.txt

@@ -1,4 +1,4 @@
-mbo_utilities>=3.0.3
+mbo_utilities>=3.0.7
 suite2p>=1.0.0.1
 setuptools<81
 

{lbm_suite2p_python-3.0.7 → lbm_suite2p_python-3.0.8}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "lbm_suite2p_python"
-version = "3.0.7"
+version = "3.0.8"
 description = "Calcium Imaging Pipeline built with Suite2p, Cellpose and Rastermap"
 readme = "README.md"
 license = "BSD-3-Clause"
@@ -18,7 +18,7 @@ classifiers=[
 ]
 
 dependencies = [
-	"mbo_utilities>=3.0.3",
+	"mbo_utilities>=3.0.7",
 	"suite2p>=1.0.0.1",
 	"setuptools<81",
 ]

{lbm_suite2p_python-3.0.7 → lbm_suite2p_python-3.0.8}/tests/test_pipeline_parameters.py

@@ -522,6 +522,35 @@ class TestDFFCalculation:
                          time.time() - start, {"error": str(e)})
             raise
 
+    def test_zscore_trace(self):
+        """Test zscore_trace function."""
+        from lbm_suite2p_python.postprocessing import zscore_trace
+
+        start = time.time()
+
+        try:
+            F = self._get_test_traces()
+
+            z = zscore_trace(F)
+
+            assert z.shape == F.shape, "z-score shape mismatch"
+            assert not np.any(np.isnan(z)), "z-score contains NaN values"
+            assert not np.any(np.isinf(z)), "z-score contains Inf values"
+
+            # per-ROI mean ~ 0 and std ~ 1
+            assert np.allclose(np.mean(z, axis=1), 0, atol=1e-4), "z-score not zero-mean"
+            assert np.allclose(np.std(z, axis=1), 1, atol=1e-2), "z-score not unit-std"
+
+            duration = time.time() - start
+            record_result(self.summary, "test_zscore_trace", "passed", duration, {
+                "shape": list(z.shape),
+            })
+
+        except Exception as e:
+            record_result(self.summary, "test_zscore_trace", "failed",
+                         time.time() - start, {"error": str(e)})
+            raise
+
     def test_dff_window_size_effect(self):
         """Test that different window sizes produce different results."""
         from lbm_suite2p_python.postprocessing import dff_rolling_percentile

{lbm_suite2p_python-3.0.7 → lbm_suite2p_python-3.0.8}/tests/test_refactored_pipeline.py

@@ -65,15 +65,17 @@ def test_pipeline_delegates_to_run_volume_with_planes_arg(mock_imread, mock_run_
 @patch("lbm_suite2p_python.run_lsp.run_volume")
 def test_pipeline_passes_parameters(mock_run_volume, mock_4d_array):
     pipeline(
-        mock_4d_array, 
+        mock_4d_array,
         save_path="test_output",
         dff_percentile=30,
+        norm_method="zscore",
         accept_all_cells=True,
         cell_filters=[{"name": "test"}]
     )
-    
+
     kwargs = mock_run_volume.call_args.kwargs
     assert kwargs['dff_percentile'] == 30
+    assert kwargs['norm_method'] == "zscore"
     assert kwargs['accept_all_cells'] is True
     assert kwargs['cell_filters'] == [{"name": "test"}]