lbm_caiman_python 0.2.0__tar.gz

lbm_caiman_python-0.2.0/LICENSE.md

@@ -0,0 +1,38 @@
+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:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. 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.
+
+3. 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.
+   
+4. 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-CaImAn-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_caiman_python-0.2.0/PKG-INFO

@@ -0,0 +1,161 @@
+Metadata-Version: 2.4
+Name: lbm_caiman_python
+Version: 0.2.0
+Summary: Light Beads Microscopy Pipeline using CaImAn
+License-Expression: BSD-3-Clause
+Project-URL: Homepage, https://github.com/MillerBrainObservatory/LBM-CaImAn-Python
+Project-URL: Documentation, https://millerbrainobservatory.github.io/LBM-CaImAn-Python
+Project-URL: Repository, https://github.com/MillerBrainObservatory/LBM-CaImAn-Python
+Project-URL: Issues, https://github.com/MillerBrainObservatory/LBM-CaImAn-Python/issues
+Keywords: Pipeline,Numpy,Microscopy,ScanImage,CaImAn,tiff,calcium imaging
+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: numpy
+Requires-Dist: scipy>=1.10
+Requires-Dist: scikit-learn
+Requires-Dist: scikit-image
+Requires-Dist: joblib
+Requires-Dist: tqdm
+Requires-Dist: matplotlib
+Requires-Dist: tifffile
+Requires-Dist: h5py
+Requires-Dist: zarr
+Requires-Dist: dask
+Requires-Dist: pandas
+Requires-Dist: mbo_utilities>=3.1.0
+Requires-Dist: lbm_suite2p_python
+Dynamic: license-file
+
+# LBM-CaImAn-Python
+
+[**Installation**](https://github.com/MillerBrainObservatory/LBM-CaImAn-Python#installation) | [**Notebooks**](https://github.com/MillerBrainObservatory/LBM-CaImAn-Python/tree/master/demos/notebooks)
+
+[![Documentation](https://img.shields.io/badge/Documentation-black?style=for-the-badge&logo=readthedocs&logoColor=white)](https://millerbrainobservatory.github.io/LBM-CaImAn-Python/)
+ 
+Python implementation of the Light Beads Microscopy (LBM) computational pipeline. The documentation has examples of the rendered notebooks.
+
+For the `MATLAB` implementation, see [here](https://github.com/MillerBrainObservatory/LBM-CaImAn-MATLAB/)
+
+## Pipeline Steps:
+
+1. Image Assembly
+    - Extract raw `tiffs` to planar timeseries
+2. Motion Correction
+    - Rigid/Non-rigid registration
+3. Segmentation
+    - Iterative CNMF segmentation
+    - Deconvolution
+    - Refine neuron selection
+4. Collation
+    - Collate images and metadata into a single volume
+    - Lateral offset correction (between z-planes. WIP)
+
+## Requirements
+
+- caiman
+- numpy
+- scipy
+- fastplotlib
+
+:exclamation: **Note:** This package makes heavy use of fastplotlib for visualizations.
+
+fastplotlib runs on [Jupyter Lab](https://jupyterlab.readthedocs.io/en/stable/getting_started/installation.html),
+but is not guarenteed to work with Jupyter Notebook or Visual Studio Code notebook environments. 
+
+## Installation
+
+Install [pixi](https://pixi.sh) (`pip install pixi` or see https://pixi.sh for other methods), then:
+
+```bash
+git clone https://github.com/MillerBrainObservatory/LBM-CaImAn-Python.git
+cd LBM-CaImAn-Python
+pixi install
+pixi run setup-caiman
+```
+
+This installs CaImAn from conda-forge along with all dependencies and the project itself in editable mode.
+
+To verify:
+
+```bash
+pixi run python -c "import lbm_caiman_python as lcp; print(lcp.__version__)"
+```
+
+:exclamation: **Hardware requirements** The large CNMF visualizations with contours etc. usually require either a dedicated GPU or integrated GPU with access to at least 1GB of VRAM.
+
+---
+
+## Troubleshooting
+
+### Error during pip install: OSError: [Errno 2] No such file or directory
+
+If you recieve an error during pip installation with the hint:
+
+```bash
+
+HINT: This error might have occurred since this system does not have Windows Long Path support enabled. You can find
+ information on how to enable this at https://pip.pypa.io/warnings/enable-long-paths
+
+```
+
+In Windows Powershell, as Administrator:
+
+`New-ItemProperty -Path "HKLM:\SYSTEM\CurrentControlSet\Control\FileSystem" -Name "LongPathsEnabled" -Value 1 -PropertyType DWORD -Force`
+
+Or:
+
+- Open Group Policy Editor (Press Windows Key and type gpedit.msc and hit Enter key.
+
+- Navigate to the following directory:  
+
+`Local Computer Policy > Computer Configuration > Administrative Templates > System > Filesystem > NTFS.`
+
+- Click Enable NTFS long paths option and enable it.
+
+### Conda Slow / Stalling
+
+if conda is behaving slow, clean the conda installation and update `conda-forge`:
+
+``` bash
+
+conda clean -a
+
+conda update -c conda-forge --all
+
+```
+
+### virtualenv Troubleshooting
+
+#### Error During `pip install .` (CaImAn) on Linux
+If you encounter errors during the installation of `CaImAn`, install the necessary development tools:
+```bash
+sudo apt-get install python3-dev
+```
+
+Don't forget to press enter a few times if conda is taking a long time.
+
+### Recommended Conda Distribution
+
+The recommended conda installer is 
+
+This is a community-driven `conda`/`mamba` installer with pre-configured packages specific to [conda-forge](https://conda-forge.org/).
+
+This helps avoid `conda-channel` conflicts and avoids any issues with the Anaconda TOS.
+
+You can install the installer from a unix command line:
+
+``` bash
+curl -L -O "https://github.com/conda-forge/miniforge/releases/latest/download/Miniforge3-$(uname)-$(uname -m).sh"
+bash Miniforge3-$(uname)-$(uname -m).sh
+```
+
+Or download the installer for your operating system [here](https://github.com/conda-forge/miniforge/releases).
+
+### Graphics Driver Issues
+
+If you are attempting to use fastplotlib and receive errors about graphics drivers, see the [fastplotlib driver documentation](https://github.com/fastplotlib/fastplotlib?tab=readme-ov-file#gpu-drivers-and-requirements).
+

lbm_caiman_python-0.2.0/README.md

@@ -0,0 +1,129 @@
+# LBM-CaImAn-Python
+
+[**Installation**](https://github.com/MillerBrainObservatory/LBM-CaImAn-Python#installation) | [**Notebooks**](https://github.com/MillerBrainObservatory/LBM-CaImAn-Python/tree/master/demos/notebooks)
+
+[![Documentation](https://img.shields.io/badge/Documentation-black?style=for-the-badge&logo=readthedocs&logoColor=white)](https://millerbrainobservatory.github.io/LBM-CaImAn-Python/)
+ 
+Python implementation of the Light Beads Microscopy (LBM) computational pipeline. The documentation has examples of the rendered notebooks.
+
+For the `MATLAB` implementation, see [here](https://github.com/MillerBrainObservatory/LBM-CaImAn-MATLAB/)
+
+## Pipeline Steps:
+
+1. Image Assembly
+    - Extract raw `tiffs` to planar timeseries
+2. Motion Correction
+    - Rigid/Non-rigid registration
+3. Segmentation
+    - Iterative CNMF segmentation
+    - Deconvolution
+    - Refine neuron selection
+4. Collation
+    - Collate images and metadata into a single volume
+    - Lateral offset correction (between z-planes. WIP)
+
+## Requirements
+
+- caiman
+- numpy
+- scipy
+- fastplotlib
+
+:exclamation: **Note:** This package makes heavy use of fastplotlib for visualizations.
+
+fastplotlib runs on [Jupyter Lab](https://jupyterlab.readthedocs.io/en/stable/getting_started/installation.html),
+but is not guarenteed to work with Jupyter Notebook or Visual Studio Code notebook environments. 
+
+## Installation
+
+Install [pixi](https://pixi.sh) (`pip install pixi` or see https://pixi.sh for other methods), then:
+
+```bash
+git clone https://github.com/MillerBrainObservatory/LBM-CaImAn-Python.git
+cd LBM-CaImAn-Python
+pixi install
+pixi run setup-caiman
+```
+
+This installs CaImAn from conda-forge along with all dependencies and the project itself in editable mode.
+
+To verify:
+
+```bash
+pixi run python -c "import lbm_caiman_python as lcp; print(lcp.__version__)"
+```
+
+:exclamation: **Hardware requirements** The large CNMF visualizations with contours etc. usually require either a dedicated GPU or integrated GPU with access to at least 1GB of VRAM.
+
+---
+
+## Troubleshooting
+
+### Error during pip install: OSError: [Errno 2] No such file or directory
+
+If you recieve an error during pip installation with the hint:
+
+```bash
+
+HINT: This error might have occurred since this system does not have Windows Long Path support enabled. You can find
+ information on how to enable this at https://pip.pypa.io/warnings/enable-long-paths
+
+```
+
+In Windows Powershell, as Administrator:
+
+`New-ItemProperty -Path "HKLM:\SYSTEM\CurrentControlSet\Control\FileSystem" -Name "LongPathsEnabled" -Value 1 -PropertyType DWORD -Force`
+
+Or:
+
+- Open Group Policy Editor (Press Windows Key and type gpedit.msc and hit Enter key.
+
+- Navigate to the following directory:  
+
+`Local Computer Policy > Computer Configuration > Administrative Templates > System > Filesystem > NTFS.`
+
+- Click Enable NTFS long paths option and enable it.
+
+### Conda Slow / Stalling
+
+if conda is behaving slow, clean the conda installation and update `conda-forge`:
+
+``` bash
+
+conda clean -a
+
+conda update -c conda-forge --all
+
+```
+
+### virtualenv Troubleshooting
+
+#### Error During `pip install .` (CaImAn) on Linux
+If you encounter errors during the installation of `CaImAn`, install the necessary development tools:
+```bash
+sudo apt-get install python3-dev
+```
+
+Don't forget to press enter a few times if conda is taking a long time.
+
+### Recommended Conda Distribution
+
+The recommended conda installer is 
+
+This is a community-driven `conda`/`mamba` installer with pre-configured packages specific to [conda-forge](https://conda-forge.org/).
+
+This helps avoid `conda-channel` conflicts and avoids any issues with the Anaconda TOS.
+
+You can install the installer from a unix command line:
+
+``` bash
+curl -L -O "https://github.com/conda-forge/miniforge/releases/latest/download/Miniforge3-$(uname)-$(uname -m).sh"
+bash Miniforge3-$(uname)-$(uname -m).sh
+```
+
+Or download the installer for your operating system [here](https://github.com/conda-forge/miniforge/releases).
+
+### Graphics Driver Issues
+
+If you are attempting to use fastplotlib and receive errors about graphics drivers, see the [fastplotlib driver documentation](https://github.com/fastplotlib/fastplotlib?tab=readme-ov-file#gpu-drivers-and-requirements).
+

lbm_caiman_python-0.2.0/lbm_caiman_python/__init__.py

@@ -0,0 +1,63 @@
+from . import _version
+
+# core pipeline api
+from .default_ops import default_ops, mcorr_ops, cnmf_ops
+from .run_lcp import (
+    pipeline,
+    run_volume,
+    run_plane,
+    add_processing_step,
+    generate_plane_dirname,
+)
+from .postprocessing import (
+    load_ops,
+    load_planar_results,
+    dff_rolling_percentile,
+    compute_roi_stats,
+    get_accepted_cells,
+    get_contours,
+)
+
+# existing utilities
+from .collation import combine_z_planes
+from .util.transform import vectorize, unvectorize, calculate_centers
+from .util.quality import get_noise_fft, greedyROI
+from .util.signal import smooth_data, norm_minmax
+from .helpers import (
+    generate_patch_view,
+    get_single_patch_coords,
+    extract_center_square,
+)
+
+__version__ = _version.get_versions()['version']
+
+__all__ = [
+    # core pipeline
+    "pipeline",
+    "run_volume",
+    "run_plane",
+    "default_ops",
+    "mcorr_ops",
+    "cnmf_ops",
+    "add_processing_step",
+    "generate_plane_dirname",
+
+    # postprocessing
+    "load_ops",
+    "load_planar_results",
+    "dff_rolling_percentile",
+    "compute_roi_stats",
+    "get_accepted_cells",
+    "get_contours",
+
+    # existing utilities
+    "combine_z_planes",
+    "generate_patch_view",
+    "get_noise_fft",
+    "calculate_centers",
+    "greedyROI",
+    "get_single_patch_coords",
+    "extract_center_square",
+    "smooth_data",
+    "norm_minmax",
+]

lbm_caiman_python-0.2.0/lbm_caiman_python/__main__.py

@@ -0,0 +1,302 @@
+"""
+cli entry point for lbm-caiman-python.
+
+usage:
+    lcp <input> <output> [options]
+    python -m lbm_caiman_python <input> <output> [options]
+"""
+
+import argparse
+import sys
+from functools import partial
+from pathlib import Path
+
+print = partial(print, flush=True)
+
+
+def add_args(parser: argparse.ArgumentParser):
+    """add command-line arguments to the parser."""
+    from lbm_caiman_python.default_ops import default_ops
+
+    defaults = default_ops()
+
+    # positional arguments
+    parser.add_argument(
+        "input",
+        type=str,
+        nargs="?",
+        default=None,
+        help="Input file or directory",
+    )
+    parser.add_argument(
+        "output",
+        type=str,
+        nargs="?",
+        default=None,
+        help="Output directory",
+    )
+
+    # processing flags
+    parser.add_argument(
+        "--planes",
+        type=int,
+        nargs="+",
+        default=None,
+        help="Planes to process (1-based)",
+    )
+    parser.add_argument(
+        "--no-mcorr",
+        action="store_true",
+        help="Skip motion correction",
+    )
+    parser.add_argument(
+        "--no-cnmf",
+        action="store_true",
+        help="Skip CNMF",
+    )
+    parser.add_argument(
+        "--force-mcorr",
+        action="store_true",
+        help="Force re-run motion correction",
+    )
+    parser.add_argument(
+        "--force-cnmf",
+        action="store_true",
+        help="Force re-run CNMF",
+    )
+    parser.add_argument(
+        "--num-frames",
+        type=int,
+        default=None,
+        help="Limit number of frames to process",
+    )
+
+    # motion correction parameters
+    parser.add_argument(
+        "--max-shifts",
+        type=int,
+        nargs=2,
+        default=None,
+        help=f"Maximum rigid shifts (default: {defaults['max_shifts']})",
+    )
+    parser.add_argument(
+        "--strides",
+        type=int,
+        nargs=2,
+        default=None,
+        help=f"Patch strides for piecewise-rigid (default: {defaults['strides']})",
+    )
+    parser.add_argument(
+        "--overlaps",
+        type=int,
+        nargs=2,
+        default=None,
+        help=f"Patch overlaps (default: {defaults['overlaps']})",
+    )
+    parser.add_argument(
+        "--gSig-filt",
+        type=int,
+        nargs=2,
+        default=None,
+        help=f"Gaussian filter size (default: {defaults['gSig_filt']})",
+    )
+    parser.add_argument(
+        "--no-pw-rigid",
+        action="store_true",
+        help="Disable piecewise-rigid correction (use rigid only)",
+    )
+
+    # cnmf parameters
+    parser.add_argument(
+        "--K",
+        type=int,
+        default=None,
+        help=f"Expected number of neurons (default: {defaults['K']})",
+    )
+    parser.add_argument(
+        "--gSig",
+        type=int,
+        nargs=2,
+        default=None,
+        help=f"Expected neuron half-width (default: {defaults['gSig']})",
+    )
+    parser.add_argument(
+        "--min-SNR",
+        type=float,
+        default=None,
+        help=f"Minimum SNR threshold (default: {defaults['min_SNR']})",
+    )
+    parser.add_argument(
+        "--rval-thr",
+        type=float,
+        default=None,
+        help=f"Correlation threshold (default: {defaults['rval_thr']})",
+    )
+    parser.add_argument(
+        "--merge-thresh",
+        type=float,
+        default=None,
+        help=f"Merging threshold (default: {defaults['merge_thresh']})",
+    )
+
+    # general parameters
+    parser.add_argument(
+        "--fr",
+        type=float,
+        default=None,
+        help=f"Frame rate in Hz (default: {defaults['fr']})",
+    )
+    parser.add_argument(
+        "--n-processes",
+        type=int,
+        default=None,
+        help="Number of parallel processes (default: auto)",
+    )
+
+    # utility flags
+    parser.add_argument(
+        "--version",
+        action="store_true",
+        help="Show version information",
+    )
+    parser.add_argument(
+        "--debug",
+        action="store_true",
+        help="Enable debug mode",
+    )
+
+    return parser
+
+
+def build_ops_from_args(args) -> dict:
+    """build ops dictionary from command-line arguments."""
+    from lbm_caiman_python.default_ops import default_ops
+
+    ops = default_ops()
+
+    # map cli args to ops keys
+    arg_to_ops = {
+        "max_shifts": "max_shifts",
+        "strides": "strides",
+        "overlaps": "overlaps",
+        "gSig_filt": "gSig_filt",
+        "K": "K",
+        "gSig": "gSig",
+        "min_SNR": "min_SNR",
+        "rval_thr": "rval_thr",
+        "merge_thresh": "merge_thresh",
+        "fr": "fr",
+        "n_processes": "n_processes",
+    }
+
+    for arg_name, ops_key in arg_to_ops.items():
+        value = getattr(args, arg_name.replace("-", "_"), None)
+        if value is not None:
+            if isinstance(value, list) and len(value) == 2:
+                ops[ops_key] = tuple(value)
+            else:
+                ops[ops_key] = value
+
+    # handle boolean flags
+    if args.no_mcorr:
+        ops["do_motion_correction"] = False
+    if args.no_cnmf:
+        ops["do_cnmf"] = False
+    if args.no_pw_rigid:
+        ops["pw_rigid"] = False
+
+    return ops
+
+
+def main():
+    """main cli entry point."""
+    print("\n")
+    print("--- LBM-CaImAn Pipeline ---")
+    print("\n")
+
+    parser = argparse.ArgumentParser(
+        description="LBM-CaImAn processing pipeline",
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        epilog="""
+examples:
+  lcp data.tiff output/
+  lcp data/ results/ --planes 1 2 3
+  lcp movie.tif results/ --K 100 --gSig 5 5
+  lcp data.tiff output/ --no-mcorr  # skip motion correction
+        """,
+    )
+    parser = add_args(parser)
+    args = parser.parse_args()
+
+    # handle version
+    if args.version:
+        import lbm_caiman_python
+        print(f"lbm_caiman_python v{lbm_caiman_python.__version__}")
+        return
+
+    # check required arguments
+    if args.input is None:
+        parser.print_help()
+        return
+
+    # setup logging
+    if args.debug:
+        import logging
+        logging.basicConfig(level=logging.DEBUG)
+        print("Debug mode enabled.")
+
+    # validate input
+    input_path = Path(args.input).expanduser().resolve()
+    if not input_path.exists():
+        print(f"Error: Input path does not exist: {input_path}")
+        sys.exit(1)
+
+    # setup output
+    if args.output is None:
+        output_path = input_path.parent / (input_path.stem + "_caiman_results")
+    else:
+        output_path = Path(args.output).expanduser().resolve()
+
+    print(f"Input: {input_path}")
+    print(f"Output: {output_path}")
+
+    # build ops from arguments
+    ops = build_ops_from_args(args)
+
+    # run pipeline
+    from lbm_caiman_python.run_lcp import pipeline
+
+    try:
+        results = pipeline(
+            input_data=input_path,
+            save_path=str(output_path),
+            ops=ops,
+            planes=args.planes,
+            force_mcorr=args.force_mcorr,
+            force_cnmf=args.force_cnmf,
+            num_timepoints=args.num_frames,
+        )
+
+        print("\n")
+        print("--- Processing Complete ---")
+        print(f"Results saved to: {output_path}")
+        print(f"Processed {len(results)} plane(s)")
+
+        # print summary
+        for ops_path in results:
+            from lbm_caiman_python.postprocessing import load_ops
+            ops_result = load_ops(ops_path)
+            plane = ops_result.get("plane", "?")
+            n_cells = ops_result.get("n_cells", 0)
+            print(f"  Plane {plane}: {n_cells} cells")
+
+    except Exception as e:
+        print(f"\nError: {e}")
+        if args.debug:
+            import traceback
+            traceback.print_exc()
+        sys.exit(1)
+
+
+if __name__ == "__main__":
+    main()

lbm_caiman_python-0.2.0/lbm_caiman_python/_version.py

@@ -0,0 +1,8 @@
+"""version information for lbm_caiman_python."""
+
+__version__ = "0.1.0"
+
+
+def get_versions():
+    """return version dict for backwards compatibility."""
+    return {"version": __version__}