lbm_suite2p_python 2.2.0__tar.gz → 2.3.1__tar.gz

{lbm_suite2p_python-2.2.0 → lbm_suite2p_python-2.3.1}/LICENSE.md

@@ -1,17 +1,17 @@
-This software license is the 3-clause BSD license plus a fourth clause that prohibits redistribution for commercial purposes without further permission.
-
-BSD 3-Clause License
-
-Copyright (c) 2024, Miller Brain Observatory.
-
-Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:
-
-Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
-
-Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
-
-Neither the name of the copyright holder nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission.
-
-Redistributions for commercial purposes are not permitted without the written permission of all code authors. For purposes of this license, commercial purposes is the incorporation of LBM-Suite2p-Python into anything for which you will charge fees or other compensation. Contact mbo@rockefeller.edu for more information.
-
-THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+This software license is the 3-clause BSD license plus a fourth clause that prohibits redistribution for commercial purposes without further permission.
+
+BSD 3-Clause License
+
+Copyright (c) 2024, Miller Brain Observatory.
+
+Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:
+
+Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
+
+Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
+
+Neither the name of the copyright holder nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission.
+
+Redistributions for commercial purposes are not permitted without the written permission of all code authors. For purposes of this license, commercial purposes is the incorporation of LBM-Suite2p-Python into anything for which you will charge fees or other compensation. Contact mbo@rockefeller.edu for more information.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

lbm_suite2p_python-2.3.1/PKG-INFO

@@ -0,0 +1,181 @@
+Metadata-Version: 2.4
+Name: lbm_suite2p_python
+Version: 2.3.1
+Summary: Light Beads Microscopy Pipeline using Suite2p
+License-Expression: BSD-3-Clause
+Project-URL: homepage, https://github.com/MillerBrainObservatory/LBM-Suite2p-Python
+Keywords: Pipeline,Numpy,Microscopy,ScanImage,Suite2p,tiff
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: Programming Language :: Python :: 3 :: Only
+Requires-Python: <3.12.10,>=3.12.7
+Description-Content-Type: text/markdown
+License-File: LICENSE.md
+Requires-Dist: mbo_utilities>=2.3.0
+Requires-Dist: fastplotlib
+Provides-Extra: suite2p
+Requires-Dist: suite2p_mbo>=2.0.0; extra == "suite2p"
+Provides-Extra: rastermap
+Requires-Dist: rastermap; extra == "rastermap"
+Provides-Extra: cellpose
+Requires-Dist: cellpose>=4.0.6; extra == "cellpose"
+Provides-Extra: torch
+Requires-Dist: torch>=2.7.0; extra == "torch"
+Requires-Dist: torchvision>=0.22.0; extra == "torch"
+Provides-Extra: all
+Requires-Dist: lbm_suite2p_python[cellpose,rastermap,suite2p,torch]; extra == "all"
+Dynamic: license-file
+
+# LBM-Suite2p-Python
+
+> **Status:** Late-beta stage of development
+
+[![Documentation](https://img.shields.io/badge/Documentation-blue?style=for-the-badge&logo=readthedocs&logoColor=white)](https://millerbrainobservatory.github.io/LBM-Suite2p-Python/index.html)
+
+[![PyPI - Version](https://img.shields.io/pypi/v/lbm-suite2p-python)](https://pypi.org/project/lbm-suite2p-python/)
+[![DOI](https://zenodo.org/badge/DOI/10.1007/978-3-319-76207-4_15.svg)](https://doi.org/10.1038/s41592-021-01239-8)
+
+A volumetric 2-photon calcium imaging processing pipeline for Light Beads Microscopy (LBM) datasets, built on Suite2p.
+
+A GUI is available via [mbo_utilities](https://millerbrainobservatory.github.io/mbo_utilities/index.html#gui) (GUI functionality will lag behind this pipeline).
+
+## Installation
+
+LBM-Suite2p-Python is a pure `pip` install. You can use `venv`, `uv` (recommended), or `conda`. Just remove the `uv` prefix.
+
+```bash
+# create a new project folder
+mkdir my_project
+cd my_project
+
+# (uv only) create environment and install
+uv venv --python 3.12.9
+uv pip install lbm_suite2p_python
+```
+
+### Optional Dependencies
+
+```bash
+# With rastermap for activity clustering visualization
+uv pip install "lbm_suite2p_python[rastermap]"
+
+# With cellpose for anatomical cell detection (includes PyTorch)
+uv pip install "lbm_suite2p_python[cellpose]"
+
+# All optional dependencies
+uv pip install "lbm_suite2p_python[all]"
+```
+
+### Development Installation
+
+While this pipeline is in active development, you can keep a local copy to quickly pull changes:
+
+```bash
+git clone https://github.com/MillerBrainObservatory/LBM-Suite2p-Python.git
+cd LBM-Suite2p-Python
+uv pip install .
+```
+
+### GUI Dependencies
+
+**Linux / macOS:**
+
+```bash
+sudo apt install libxcursor-dev libgl1-mesa-dev libglu1-mesa-dev freeglut3-dev
+```
+
+**Windows:**
+Install [Microsoft Visual C++ Redistributable](https://learn.microsoft.com/en-us/cpp/windows/latest-supported-vc-redist)
+
+### Troubleshooting
+
+When installing from github, you may get:
+
+**Git LFS Error:** If you see `smudge filter lfs failed`:
+
+```bash
+GIT_LFS_SKIP_SMUDGE=1 uv sync --all-extras --active
+```
+
+## Quick Start
+
+```python
+import lbm_suite2p_python as lsp
+
+results = lsp.pipeline(
+    input_data="D:/data/raw",   # path to file, directory, or list of files
+    save_path=None,             # default: save next to input
+    ops=None,                   # default: use MBO-optimized parameters
+    planes=None,                # default: process all planes
+    roi=None,                   # default: stitch multi-ROI data
+    keep_reg=True,              # default: keep data.bin (registered binary)
+    keep_raw=False,             # default: delete data_raw.bin after processing
+    force_reg=False,            # default: skip if already registered
+    force_detect=False,         # default: skip if stat.npy exists
+    dff_window_size=None,       # default: auto-calculate from tau and framerate
+    dff_percentile=20,          # default: 20th percentile for baseline
+    dff_smooth_window=None,     # default: auto-calculate from tau and framerate
+)
+```
+
+## Planar Results
+
+Each z-plane produces diagnostic images automatically saved during processing.
+
+<p align="center">
+<img src="docs/_images/segmentation_summary.gif" alt="Segmentation Summary" width="500"/>
+<br><em>Segmentation overlays on reference images</em>
+</p>
+
+<p align="center">
+<img src="docs/_images/05_quality_diagnostics.png" alt="Quality Diagnostics" width="550"/>
+<br><em>ROI quality metrics: size, SNR, compactness</em>
+</p>
+
+<p align="center">
+<img src="docs/_images/08_traces_dff.png" alt="ΔF/F Traces" width="500"/>
+<br><em>ΔF/F traces sorted by quality</em>
+</p>
+
+## Volumetric Results
+
+Volume-level visualizations combine data across all z-planes.
+
+<p align="center">
+<img src="docs/_images/all_planes_masks.png" alt="All Planes Masks" width="550"/>
+<br><em>ROI masks across all z-planes</em>
+</p>
+
+<p align="center">
+<img src="docs/_images/roi_map_3d_snr.png" alt="3D ROI Map" width="450"/>
+<br><em>3D ROI centroids colored by SNR</em>
+</p>
+
+<p align="center">
+<img src="docs/_images/rastermap.png" alt="Rastermap" width="550"/>
+<br><em>Activity sorted by similarity (Rastermap)</em>
+</p>
+
+
+## Built With
+
+This pipeline integrates several open-source tools:
+
+- **[Suite2p](https://github.com/MouseLand/suite2p)** - Core registration and segmentation
+- **[Cellpose](https://github.com/MouseLand/cellpose)** - Anatomical segmentation (optional)
+- **[Rastermap](https://github.com/MouseLand/rastermap)** - Activity clustering (optional)
+- **[mbo_utilities](https://github.com/MillerBrainObservatory/mbo_utilities)** - ScanImage I/O and metadata
+- **[scanreader](https://github.com/atlab/scanreader)** - ScanImage metadata parsing
+
+## Issues & Support
+
+- **Bug reports:** [GitHub Issues](https://github.com/MillerBrainObservatory/LBM-Suite2p-Python/issues)
+- **Questions:** See [Suite2p documentation](https://suite2p.readthedocs.io/) for Suite2p-specific questions
+- **Known issues:** Widgets may throw "Invalid Rect" errors ([upstream issue](https://github.com/pygfx/wgpu-py/issues/716#issuecomment-2880853089))
+
+## Contributing
+
+Contributions are welcome! This project follows Suite2p's conventions and uses:
+- **Ruff** for linting and formatting (line length: 88, numpy docstring style)
+- **pytest** for testing
+- **Sphinx** for documentation

lbm_suite2p_python-2.3.1/README.md

@@ -0,0 +1,153 @@
+# LBM-Suite2p-Python
+
+> **Status:** Late-beta stage of development
+
+[![Documentation](https://img.shields.io/badge/Documentation-blue?style=for-the-badge&logo=readthedocs&logoColor=white)](https://millerbrainobservatory.github.io/LBM-Suite2p-Python/index.html)
+
+[![PyPI - Version](https://img.shields.io/pypi/v/lbm-suite2p-python)](https://pypi.org/project/lbm-suite2p-python/)
+[![DOI](https://zenodo.org/badge/DOI/10.1007/978-3-319-76207-4_15.svg)](https://doi.org/10.1038/s41592-021-01239-8)
+
+A volumetric 2-photon calcium imaging processing pipeline for Light Beads Microscopy (LBM) datasets, built on Suite2p.
+
+A GUI is available via [mbo_utilities](https://millerbrainobservatory.github.io/mbo_utilities/index.html#gui) (GUI functionality will lag behind this pipeline).
+
+## Installation
+
+LBM-Suite2p-Python is a pure `pip` install. You can use `venv`, `uv` (recommended), or `conda`. Just remove the `uv` prefix.
+
+```bash
+# create a new project folder
+mkdir my_project
+cd my_project
+
+# (uv only) create environment and install
+uv venv --python 3.12.9
+uv pip install lbm_suite2p_python
+```
+
+### Optional Dependencies
+
+```bash
+# With rastermap for activity clustering visualization
+uv pip install "lbm_suite2p_python[rastermap]"
+
+# With cellpose for anatomical cell detection (includes PyTorch)
+uv pip install "lbm_suite2p_python[cellpose]"
+
+# All optional dependencies
+uv pip install "lbm_suite2p_python[all]"
+```
+
+### Development Installation
+
+While this pipeline is in active development, you can keep a local copy to quickly pull changes:
+
+```bash
+git clone https://github.com/MillerBrainObservatory/LBM-Suite2p-Python.git
+cd LBM-Suite2p-Python
+uv pip install .
+```
+
+### GUI Dependencies
+
+**Linux / macOS:**
+
+```bash
+sudo apt install libxcursor-dev libgl1-mesa-dev libglu1-mesa-dev freeglut3-dev
+```
+
+**Windows:**
+Install [Microsoft Visual C++ Redistributable](https://learn.microsoft.com/en-us/cpp/windows/latest-supported-vc-redist)
+
+### Troubleshooting
+
+When installing from github, you may get:
+
+**Git LFS Error:** If you see `smudge filter lfs failed`:
+
+```bash
+GIT_LFS_SKIP_SMUDGE=1 uv sync --all-extras --active
+```
+
+## Quick Start
+
+```python
+import lbm_suite2p_python as lsp
+
+results = lsp.pipeline(
+    input_data="D:/data/raw",   # path to file, directory, or list of files
+    save_path=None,             # default: save next to input
+    ops=None,                   # default: use MBO-optimized parameters
+    planes=None,                # default: process all planes
+    roi=None,                   # default: stitch multi-ROI data
+    keep_reg=True,              # default: keep data.bin (registered binary)
+    keep_raw=False,             # default: delete data_raw.bin after processing
+    force_reg=False,            # default: skip if already registered
+    force_detect=False,         # default: skip if stat.npy exists
+    dff_window_size=None,       # default: auto-calculate from tau and framerate
+    dff_percentile=20,          # default: 20th percentile for baseline
+    dff_smooth_window=None,     # default: auto-calculate from tau and framerate
+)
+```
+
+## Planar Results
+
+Each z-plane produces diagnostic images automatically saved during processing.
+
+<p align="center">
+<img src="docs/_images/segmentation_summary.gif" alt="Segmentation Summary" width="500"/>
+<br><em>Segmentation overlays on reference images</em>
+</p>
+
+<p align="center">
+<img src="docs/_images/05_quality_diagnostics.png" alt="Quality Diagnostics" width="550"/>
+<br><em>ROI quality metrics: size, SNR, compactness</em>
+</p>
+
+<p align="center">
+<img src="docs/_images/08_traces_dff.png" alt="ΔF/F Traces" width="500"/>
+<br><em>ΔF/F traces sorted by quality</em>
+</p>
+
+## Volumetric Results
+
+Volume-level visualizations combine data across all z-planes.
+
+<p align="center">
+<img src="docs/_images/all_planes_masks.png" alt="All Planes Masks" width="550"/>
+<br><em>ROI masks across all z-planes</em>
+</p>
+
+<p align="center">
+<img src="docs/_images/roi_map_3d_snr.png" alt="3D ROI Map" width="450"/>
+<br><em>3D ROI centroids colored by SNR</em>
+</p>
+
+<p align="center">
+<img src="docs/_images/rastermap.png" alt="Rastermap" width="550"/>
+<br><em>Activity sorted by similarity (Rastermap)</em>
+</p>
+
+
+## Built With
+
+This pipeline integrates several open-source tools:
+
+- **[Suite2p](https://github.com/MouseLand/suite2p)** - Core registration and segmentation
+- **[Cellpose](https://github.com/MouseLand/cellpose)** - Anatomical segmentation (optional)
+- **[Rastermap](https://github.com/MouseLand/rastermap)** - Activity clustering (optional)
+- **[mbo_utilities](https://github.com/MillerBrainObservatory/mbo_utilities)** - ScanImage I/O and metadata
+- **[scanreader](https://github.com/atlab/scanreader)** - ScanImage metadata parsing
+
+## Issues & Support
+
+- **Bug reports:** [GitHub Issues](https://github.com/MillerBrainObservatory/LBM-Suite2p-Python/issues)
+- **Questions:** See [Suite2p documentation](https://suite2p.readthedocs.io/) for Suite2p-specific questions
+- **Known issues:** Widgets may throw "Invalid Rect" errors ([upstream issue](https://github.com/pygfx/wgpu-py/issues/716#issuecomment-2880853089))
+
+## Contributing
+
+Contributions are welcome! This project follows Suite2p's conventions and uses:
+- **Ruff** for linting and formatting (line length: 88, numpy docstring style)
+- **pytest** for testing
+- **Sphinx** for documentation

lbm_suite2p_python-2.3.1/lbm_suite2p_python/__init__.py

@@ -0,0 +1,67 @@
+from importlib.metadata import version, PackageNotFoundError
+
+from lbm_suite2p_python.default_ops import default_ops
+from lbm_suite2p_python.run_lsp import *
+from lbm_suite2p_python.utils import *
+from lbm_suite2p_python.volume import *
+from lbm_suite2p_python.zplane import *
+from lbm_suite2p_python.postprocessing import *
+
+try:
+    __version__ = version("lbm_suite2p_python")
+except PackageNotFoundError:
+    # fallback for editable installs
+    __version__ = "0.0.0"
+
+__all__ = [
+    "pipeline",
+    "run_volume",
+    "run_plane",
+    "grid_search",
+    "consolidate_volume",
+    "add_processing_step",
+    "plot_traces",
+    "plot_masks",
+    "plot_rastermap",
+    "plot_traces_noise",
+    "plot_volume_signal",
+    "plot_volume_neuron_counts",
+    "plot_volume_diagnostics",
+    "plot_orthoslices",
+    "plot_3d_roi_map",
+    "plot_projection",
+    "plot_execution_time",
+    "plot_noise_distribution",
+    "plot_multiplane_masks",
+    "plot_plane_quality_metrics",
+    "plot_plane_diagnostics",
+    "plot_trace_analysis",
+    "plot_zplane_figures",
+    "plot_mask_comparison",
+    "create_volume_summary_table",
+    "dff_rolling_percentile",
+    "dff_median_filter",
+    "dff_shot_noise",
+    "compute_trace_quality_score",
+    "sort_traces_by_quality",
+    "load_ops",
+    "load_planar_results",
+    "default_ops",
+    # Image processing utilities
+    "normalize99",
+    "apply_hp_filter",
+    "random_colors_for_mask",
+    "mask_overlay",
+    "stat_to_mask",
+    # Filtering utilities
+    "filter_by_max_diameter",
+    "filter_by_diameter",
+    "filter_by_area",
+    "filter_by_eccentricity",
+    "plot_regional_zoom",
+    "plot_filtered_cells",
+    "plot_diameter_histogram",
+]
+
+# Re-export with public name
+from lbm_suite2p_python.run_lsp import _add_processing_step as add_processing_step

{lbm_suite2p_python-2.2.0 → lbm_suite2p_python-2.3.1}/lbm_suite2p_python/__main__.py

@@ -1,101 +1,101 @@
-import numpy as np
-import argparse
-from pathlib import Path
-from functools import partial
-import lbm_suite2p_python as lsp
-import mbo_utilities as mbo
-
-print = partial(print, flush=True)
-
-
-def add_args(parser: argparse.ArgumentParser):
-    """
-    Add command-line arguments to the parser, dynamically adding arguments
-    for each key in the `ops` dictionary.
-
-    Parameters
-    ----------
-    parser : argparse.ArgumentParser
-        The argument parser to which arguments are added.
-
-    Returns
-    -------
-    argparse.ArgumentParser
-        The parser with added arguments.
-    """
-
-    parser.add_argument("--version", type=str, help="Print the version of the package.")
-    parser.add_argument("--ops", type=str, help="Path to the ops .npy file.")
-    parser.add_argument("--data", type=str, help="Path to the data.")
-    parser.add_argument("--save", type=str, help="Path to save the results.")
-    parser.add_argument(
-        "--subdir", type=str, help="Additional subdirectory add to save-path."
-    )
-    parser.add_argument(
-        "--max-depth",
-        type=int,
-        help="Number of subdirectories to check for files to process.",
-    )
-    parser.add_argument(
-        "--overwrite", action="store_true", help="Overwrite existing files."
-    )
-    parser.add_argument(
-        "--skip-existing", action="store_true", help="Skip existing files."
-    )
-
-    return parser
-
-
-def main():
-    """
-    The main function that orchestrates the CLI operations.
-    """
-    print("\n----------- LBM-Suite2p-Pipeline -----------\n")
-    from suite2p.default_ops import default_ops
-
-    parser = argparse.ArgumentParser(description="LBM-Suite2p-pipeline parameters")
-    parser = add_args(parser)
-    args = parser.parse_args()
-
-    if args.version:
-        print(f"lbm_suite2p_python v{lsp.__version__}")
-        return
-
-    ops = (
-        np.load(args.ops, allow_pickle=True).item()
-        if args.ops
-        else default_ops()
-    )
-
-    if not args.data:
-        raise ValueError("No input file or directory specified. Use --data")
-
-    input_path = Path(args.data)
-
-    # default to data-path / 'results'
-    save_path = Path(args.save) if args.save else input_path.parent / "results"
-    save_path.mkdir(parents=True, exist_ok=True)
-
-    # Optional user-defined save folder (e.g., plane_01_runA)
-    subdir = Path(args.subdir) if args.subdir else None
-
-    if input_path.is_file():
-        output_ops = lsp.run_plane(
-            input_path=input_path,
-            save_path=save_path,
-            ops=ops,
-        )
-    elif input_path.is_dir():
-        files = mbo.get_files(input_path, "tiff", max_depth=args.max_depth)
-        output_ops = lsp.run_volume(
-            ops=ops, input_files=files, save_path=save_path, save_folder=subdir
-        )
-    else:
-        raise FileNotFoundError(f"Input path does not exist: {input_path}")
-
-    print("Processing complete -----------")
-    return output_ops
-
-
-if __name__ == "__main__":
-    main()
+import numpy as np
+import argparse
+from pathlib import Path
+from functools import partial
+import lbm_suite2p_python as lsp
+import mbo_utilities as mbo
+
+print = partial(print, flush=True)
+
+
+def add_args(parser: argparse.ArgumentParser):
+    """
+    Add command-line arguments to the parser, dynamically adding arguments
+    for each key in the `ops` dictionary.
+
+    Parameters
+    ----------
+    parser : argparse.ArgumentParser
+        The argument parser to which arguments are added.
+
+    Returns
+    -------
+    argparse.ArgumentParser
+        The parser with added arguments.
+    """
+
+    parser.add_argument("--version", type=str, help="Print the version of the package.")
+    parser.add_argument("--ops", type=str, help="Path to the ops .npy file.")
+    parser.add_argument("--data", type=str, help="Path to the data.")
+    parser.add_argument("--save", type=str, help="Path to save the results.")
+    parser.add_argument(
+        "--subdir", type=str, help="Additional subdirectory add to save-path."
+    )
+    parser.add_argument(
+        "--max-depth",
+        type=int,
+        help="Number of subdirectories to check for files to process.",
+    )
+    parser.add_argument(
+        "--overwrite", action="store_true", help="Overwrite existing files."
+    )
+    parser.add_argument(
+        "--skip-existing", action="store_true", help="Skip existing files."
+    )
+
+    return parser
+
+
+def main():
+    """
+    The main function that orchestrates the CLI operations.
+    """
+    print("\n----------- LBM-Suite2p-Pipeline -----------\n")
+    from suite2p.default_ops import default_ops
+
+    parser = argparse.ArgumentParser(description="LBM-Suite2p-pipeline parameters")
+    parser = add_args(parser)
+    args = parser.parse_args()
+
+    if args.version:
+        print(f"lbm_suite2p_python v{lsp.__version__}")
+        return
+
+    ops = (
+        np.load(args.ops, allow_pickle=True).item()
+        if args.ops
+        else default_ops()
+    )
+
+    if not args.data:
+        raise ValueError("No input file or directory specified. Use --data")
+
+    input_path = Path(args.data)
+
+    # default to data-path / 'results'
+    save_path = Path(args.save) if args.save else input_path.parent / "results"
+    save_path.mkdir(parents=True, exist_ok=True)
+
+    # Optional user-defined save folder (e.g., plane_01_runA)
+    subdir = Path(args.subdir) if args.subdir else None
+
+    if input_path.is_file():
+        output_ops = lsp.run_plane(
+            input_path=input_path,
+            save_path=save_path,
+            ops=ops,
+        )
+    elif input_path.is_dir():
+        files = mbo.get_files(input_path, "tiff", max_depth=args.max_depth)
+        output_ops = lsp.run_volume(
+            ops=ops, input_files=files, save_path=save_path, save_folder=subdir
+        )
+    else:
+        raise FileNotFoundError(f"Input path does not exist: {input_path}")
+
+    print("Processing complete -----------")
+    return output_ops
+
+
+if __name__ == "__main__":
+    main()