# LBM-CaImAn-Python
[**Installation**](https://github.com/MillerBrainObservatory/LBM-CaImAn-Python#installation) | [**Notebooks**](https://github.com/MillerBrainObservatory/LBM-CaImAn-Python/tree/master/demos/notebooks)
Python implementation of the Light Beads Microscopy (LBM) computational pipeline.
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
- Template creation
- Piecewise-rigid or non-rigid registration
3. Segmentation
- Iterative CNMF segmentation
- Deconvolution
- Refinement
4. Collation
- Lateral offset correction (between z-planes)
- Collate images and metadata into a single volume
## Requirements
- caiman
- mesmerize-core
- scanreader
- 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
This project is tested on Linux and Windows 10 using `Python 3.9` and `Python 3.10`.
Environment setup is tested using `virtualenv` and `miniforge`.
We suggest using python virtual environments for the best results.
### (Option 1). Python Virtual Environments
Ensure you have a system-wide Python installation.
This project and it's dependencies are tested using `Python 3.9` and `Python 3.10`.
**Note:** Make sure you deactivate `conda` environments before proceeding (`conda deactivate`).
Verify `Python` and `pip` installations:
- **Linux/macOS:**
```bash
python --version
pip --version
```
- **Windows:**
```bash
py --version
py - m pip --version
```
:exclamation: Depending on how Python was installed,
you may need to use `python3` or `python3.x` and `pip3` or `pip3.x` instead of `python` and `pip`.
You should see a Python version output like `3.10.x` and a corresponding `pip` version.
If Python is not installed, or an unsupported version is installed (i.e. 3.7),
download and install [python.org](https://www.python.org/) or refer to this [installation guide](https://docs.python-guide.org/starting/installation/).
You will also need [`git`](https://git-scm.com/):
```bash
git --version
```
#### Create a virtual environment
This is normally in a directory dedicated to virtual environments, but can be anywhere you wish:
```bash
python -m venv ~/venv/lbm_caiman_python
```
Activate the virtual environment:
- **Linux/macOS:**
```bash
source ~/venv/lbm_caiman_python/bin/activate
```
- **Windows:**
```bash
source ~/venv/lbm_caiman_python/Scripts/activate
```
Upgrade core tools in the virtual environment:
```bash
pip install --upgrade setuptools wheel pip
```
#### Clone and install CaImAn
Create a directory to store the cloned repositories.
Again, this can be anywhere you wish:
```bash
cd ~
mkdir repos
cd repos
```
Use git to clone CaImAn:
```bash
git clone https://github.com/flatironinstitute/CaImAn.git
```
Install CaImAn:
1. **CaImAn:**
```bash
cd CaImAn
pip install -r requirements.txt
pip install .
```
:exclamation: **Note:** If you encounter errors during the installation of `CaImAn`, you may need to install Microsoft Visual C++ Build Tools. You can download them from [here](https://visualstudio.microsoft.com/visual-cpp-build-tools/).
2. **Other dependencies:**
```bash
pip install mesmerize-core
pip install lbm_caiman_python
pip install git+https://github.com/atlab/scanreader.git
```
#### Run ipython to make sure everyting works
``` python
import lbm_caiman_python as lcp
import mesmerize_core as mc
import scanreader as sr
scan = sr.read_scan('path/to/data/*.tif', join_contiguous=True)
```
### 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
```
---
### (Option 2). Conda
Miniforge is the supported `conda` distribution. Anaconda and Miniconda require extra steps and is not covered in this guide.
Note: Sometimes conda or mamba will get stuck at a step, such as creating an environment or installing a package.
Pressing Enter on your keyboard can sometimes help it continue when it pauses.
1. Install `mamba` into your *base* environment:
:exclamation: This step may take 10 minutes and display several messages like "Solving environment: failed with..." but it should eventually install mamba.
``` bash
conda activate base
conda install -c conda-forge mamba
```
2. Create a new environment and install [mesmerize-core](https://github.com/nel-lab/mesmerize-core/tree/master)
- Here, we use the `-n` flag to name the environment `lbm` , but you can name it whatever you'd like.
- This step will install Python, mesmerize-core, CaImAn, and all required dependencies for those packages.
``` bash
conda create -n lbm -c conda-forge mesmerize-core
```
If you already have `CaImAn` installed:
``` bash
conda install -n name-of-env-with-caiman mesmerize-core
```
Activate the environment and install `caimanmanager`:
- if you used a name other than `lbm`, be sure to match the name you use here.
``` bash
conda activate lbm
caimanmanager install
```
3. Install [LBM-CaImAn-Python](https://pypi.org/project/lbm-caiman-python/) from pip:
``` bash
pip install lbm_caiman_python
```
4. Install [scanreader](https://github.com/atlab/scanreader):
``` bash
pip install git+https://github.com/atlab/scanreader.git
```
5. (Optional) Install `mesmerize-viz`:
Several notebooks make use of [mesmerize-viz](https://github.com/kushalkolar/mesmerize-viz) for visualizing registration/segmentation results.
``` bash
pip install mesmerize-viz
```
:exclamation: **Harware 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.
https://www.youtube.com/watch?v=GWvaEeqA1hw
## For Developers
To get the newest version of this package:
``` bash
git clone https://github.com/MillerBrainObservatory/LBM-CaImAn-Python.git
cd LBM-CaImAn-Python
pip install ".[docs]"
```
## Troubleshooting
### 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
```
Don't forget to press enter a few times if conda is taking a long time.
### Recommended Conda Distribution
The recommended conda installer is [miniforge](https://github.com/conda-forge/miniforge).
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).
Raw data
{
"_id": null,
"home_page": "https://github.com/millerbrainobservatory/LBM-CaImAn-Python",
"name": "lbm-caiman-python",
"maintainer": null,
"docs_url": null,
"requires_python": null,
"maintainer_email": null,
"keywords": "Pipeline Numpy Microscopy ScanImage multiROI tiff",
"author": "Your Name Here",
"author_email": "your_email@example.com",
"download_url": "https://files.pythonhosted.org/packages/53/61/f87264e2f2b7ef1ef3ad4046d64986dd21813d05770afec8e49d60cebbbd/lbm_caiman_python-1.1.0.tar.gz",
"platform": null,
"description": "# LBM-CaImAn-Python\n\n[**Installation**](https://github.com/MillerBrainObservatory/LBM-CaImAn-Python#installation) | [**Notebooks**](https://github.com/MillerBrainObservatory/LBM-CaImAn-Python/tree/master/demos/notebooks)\n \nPython implementation of the Light Beads Microscopy (LBM) computational pipeline.\n\nFor the `MATLAB` implementation, see [here](https://github.com/MillerBrainObservatory/LBM-CaImAn-MATLAB/)\n\n## Pipeline Steps:\n\n1. Image Assembly\n - Extract raw `tiffs` to planar timeseries\n2. Motion Correction\n - Template creation\n - Piecewise-rigid or non-rigid registration\n3. Segmentation\n - Iterative CNMF segmentation\n - Deconvolution\n - Refinement\n4. Collation\n - Lateral offset correction (between z-planes)\n - Collate images and metadata into a single volume\n\n## Requirements\n\n- caiman\n- mesmerize-core\n- scanreader\n- numpy\n- scipy\n- fastplotlib\n\n:exclamation: **Note:** This package makes heavy use of Fastplotlib for visualizations.\n\nFastplotlib runs on [Jupyter Lab](https://jupyterlab.readthedocs.io/en/stable/getting_started/installation.html),\nbut is not guarenteed to work with Jupyter Notebook or Visual Studio Code notebook environments. \n\n## Installation\n\nThis project is tested on Linux and Windows 10 using `Python 3.9` and `Python 3.10`.\n\nEnvironment setup is tested using `virtualenv` and `miniforge`.\n\nWe suggest using python virtual environments for the best results.\n\n### (Option 1). Python Virtual Environments\n\nEnsure you have a system-wide Python installation.\n\nThis project and it's dependencies are tested using `Python 3.9` and `Python 3.10`.\n\n**Note:** Make sure you deactivate `conda` environments before proceeding (`conda deactivate`).\n\nVerify `Python` and `pip` installations:\n\n- **Linux/macOS:**\n \n```bash\n\npython --version\n\npip --version\n```\n\n- **Windows:**\n\n```bash\npy --version\n\npy - m pip --version \n\n```\n\n:exclamation: Depending on how Python was installed,\nyou may need to use `python3` or `python3.x` and `pip3` or `pip3.x` instead of `python` and `pip`.\n\nYou should see a Python version output like `3.10.x` and a corresponding `pip` version.\n\nIf Python is not installed, or an unsupported version is installed (i.e. 3.7),\n\ndownload and install [python.org](https://www.python.org/) or refer to this [installation guide](https://docs.python-guide.org/starting/installation/).\n\nYou will also need [`git`](https://git-scm.com/):\n\n```bash\ngit --version\n```\n\n#### Create a virtual environment\n\nThis is normally in a directory dedicated to virtual environments, but can be anywhere you wish:\n\n```bash\npython -m venv ~/venv/lbm_caiman_python\n```\n\nActivate the virtual environment:\n\n- **Linux/macOS:**\n\n ```bash\n source ~/venv/lbm_caiman_python/bin/activate\n ```\n\n- **Windows:**\n\n ```bash\n source ~/venv/lbm_caiman_python/Scripts/activate\n ```\n\nUpgrade core tools in the virtual environment:\n\n```bash\npip install --upgrade setuptools wheel pip\n```\n\n#### Clone and install CaImAn\n\nCreate a directory to store the cloned repositories.\n\nAgain, this can be anywhere you wish:\n\n```bash\n\ncd ~\nmkdir repos\ncd repos\n\n```\n\nUse git to clone CaImAn:\n\n```bash\ngit clone https://github.com/flatironinstitute/CaImAn.git\n```\n\nInstall CaImAn:\n\n1. **CaImAn:**\n ```bash\n cd CaImAn\n pip install -r requirements.txt\n pip install .\n ```\n :exclamation: **Note:** If you encounter errors during the installation of `CaImAn`, you may need to install Microsoft Visual C++ Build Tools. You can download them from [here](https://visualstudio.microsoft.com/visual-cpp-build-tools/).\n\n2. **Other dependencies:**\n\n ```bash\n pip install mesmerize-core\n pip install lbm_caiman_python\n pip install git+https://github.com/atlab/scanreader.git\n ```\n\n#### Run ipython to make sure everyting works\n\n``` python\n\nimport lbm_caiman_python as lcp\nimport mesmerize_core as mc\nimport scanreader as sr\n\nscan = sr.read_scan('path/to/data/*.tif', join_contiguous=True)\n\n```\n\n### virtualenv Troubleshooting\n\n#### Error During `pip install .` (CaImAn) on Linux\nIf you encounter errors during the installation of `CaImAn`, install the necessary development tools:\n```bash\nsudo apt-get install python3-dev\n```\n\n---\n\n### (Option 2). Conda\n\nMiniforge is the supported `conda` distribution. Anaconda and Miniconda require extra steps and is not covered in this guide.\n\nNote: Sometimes conda or mamba will get stuck at a step, such as creating an environment or installing a package.\n\nPressing Enter on your keyboard can sometimes help it continue when it pauses.\n\n1. Install `mamba` into your *base* environment:\n\n:exclamation: This step may take 10 minutes and display several messages like \"Solving environment: failed with...\" but it should eventually install mamba.\n\n``` bash\nconda activate base \nconda install -c conda-forge mamba\n```\n\n2. Create a new environment and install [mesmerize-core](https://github.com/nel-lab/mesmerize-core/tree/master)\n\n- Here, we use the `-n` flag to name the environment `lbm` , but you can name it whatever you'd like.\n- This step will install Python, mesmerize-core, CaImAn, and all required dependencies for those packages.\n\n``` bash\nconda create -n lbm -c conda-forge mesmerize-core\n```\n\nIf you already have `CaImAn` installed:\n\n``` bash\nconda install -n name-of-env-with-caiman mesmerize-core\n```\n\nActivate the environment and install `caimanmanager`:\n- if you used a name other than `lbm`, be sure to match the name you use here.\n\n``` bash\nconda activate lbm\ncaimanmanager install\n```\n\n3. Install [LBM-CaImAn-Python](https://pypi.org/project/lbm-caiman-python/) from pip:\n\n``` bash\n\npip install lbm_caiman_python\n\n```\n\n4. Install [scanreader](https://github.com/atlab/scanreader):\n\n``` bash\n\npip install git+https://github.com/atlab/scanreader.git\n\n```\n\n5. (Optional) Install `mesmerize-viz`:\n\nSeveral notebooks make use of [mesmerize-viz](https://github.com/kushalkolar/mesmerize-viz) for visualizing registration/segmentation results.\n\n``` bash\n\npip install mesmerize-viz\n\n```\n\n:exclamation: **Harware 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.\n\nhttps://www.youtube.com/watch?v=GWvaEeqA1hw\n\n## For Developers\n\nTo get the newest version of this package:\n\n``` bash\n\ngit clone https://github.com/MillerBrainObservatory/LBM-CaImAn-Python.git\n\ncd LBM-CaImAn-Python\n\npip install \".[docs]\"\n\n```\n\n## Troubleshooting\n\n### Conda Slow / Stalling\n\nif conda is behaving slow, clean the conda installation and update `conda-forge`:\n\n``` bash\n\nconda clean -a\n\nconda update -c conda-forge --all\n\n```\n\nDon't forget to press enter a few times if conda is taking a long time.\n\n### Recommended Conda Distribution\n\nThe recommended conda installer is [miniforge](https://github.com/conda-forge/miniforge).\n\nThis is a community-driven `conda`/`mamba` installer with pre-configured packages specific to [conda-forge](https://conda-forge.org/).\n\nThis helps avoid `conda-channel` conflicts and avoids any issues with the Anaconda TOS.\n\nYou can install the installer from a unix command line:\n\n``` bash\n\ncurl -L -O \"https://github.com/conda-forge/miniforge/releases/latest/download/Miniforge3-$(uname)-$(uname -m).sh\"\n\nbash Miniforge3-$(uname)-$(uname -m).sh\n\n```\n\nOr download the installer for your operating system [here](https://github.com/conda-forge/miniforge/releases).\n\n### Graphics Driver Issues\n\nIf 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).\n\n\n",
"bugtrack_url": null,
"license": "BSD-3-Clause",
"summary": "Light Beads Microscopy 2P Calcium Imaging Pipeline.",
"version": "1.1.0",
"project_urls": {
"Homepage": "https://github.com/millerbrainobservatory/LBM-CaImAn-Python"
},
"split_keywords": [
"pipeline",
"numpy",
"microscopy",
"scanimage",
"multiroi",
"tiff"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "b86d9a1a88146318f99bd49d8b79b7c031d30e9122dfb50fd384c942405bf494",
"md5": "51343684f393ea2f6a746b30bdd0d7ad",
"sha256": "673a672408457f75463e630b26448ae923dc3c6a25ffc4823e1e5e2de2a05cb6"
},
"downloads": -1,
"filename": "lbm_caiman_python-1.1.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "51343684f393ea2f6a746b30bdd0d7ad",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 51051,
"upload_time": "2025-01-14T18:31:24",
"upload_time_iso_8601": "2025-01-14T18:31:24.376370Z",
"url": "https://files.pythonhosted.org/packages/b8/6d/9a1a88146318f99bd49d8b79b7c031d30e9122dfb50fd384c942405bf494/lbm_caiman_python-1.1.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "5361f87264e2f2b7ef1ef3ad4046d64986dd21813d05770afec8e49d60cebbbd",
"md5": "8835b1c39ea02088250ab798e44e918a",
"sha256": "01a5ffef4e791e7efd0838d0f51c413368d009268e26d7a8eb888ffd69cce5d1"
},
"downloads": -1,
"filename": "lbm_caiman_python-1.1.0.tar.gz",
"has_sig": false,
"md5_digest": "8835b1c39ea02088250ab798e44e918a",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 66784,
"upload_time": "2025-01-14T18:31:26",
"upload_time_iso_8601": "2025-01-14T18:31:26.831767Z",
"url": "https://files.pythonhosted.org/packages/53/61/f87264e2f2b7ef1ef3ad4046d64986dd21813d05770afec8e49d60cebbbd/lbm_caiman_python-1.1.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-01-14 18:31:26",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "millerbrainobservatory",
"github_project": "LBM-CaImAn-Python",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [
{
"name": "av",
"specs": []
},
{
"name": "h5py",
"specs": [
[
">=",
"3.4.0"
]
]
},
{
"name": "holoviews",
"specs": [
[
">=",
"1.16.2"
]
]
},
{
"name": "ipykernel",
"specs": []
},
{
"name": "ipython",
"specs": []
},
{
"name": "ipyparallel",
"specs": []
},
{
"name": "jupyter",
"specs": []
},
{
"name": "jupyter_bokeh",
"specs": []
},
{
"name": "pandas",
"specs": []
},
{
"name": "caiman",
"specs": []
},
{
"name": "matplotlib",
"specs": [
[
"~=",
"3.9.2"
]
]
},
{
"name": "mypy",
"specs": []
},
{
"name": "pytest",
"specs": []
},
{
"name": "numpy",
"specs": [
[
"~=",
"2.0.0"
]
]
},
{
"name": "numpydoc",
"specs": []
},
{
"name": "opencv-python",
"specs": []
},
{
"name": "panel",
"specs": [
[
">=",
"1.0.2"
]
]
},
{
"name": "peakutils",
"specs": [
[
">=",
"1.3.5"
]
]
},
{
"name": "pims",
"specs": []
},
{
"name": "psutil",
"specs": []
},
{
"name": "pynwb",
"specs": []
},
{
"name": "pyqtgraph",
"specs": []
},
{
"name": "scikit-image",
"specs": [
[
">=",
"0.19.0"
]
]
},
{
"name": "scikit-learn",
"specs": [
[
">=",
"1.2"
]
]
},
{
"name": "scipy",
"specs": [
[
">=",
"1.10.1"
]
]
},
{
"name": "tensorflow",
"specs": [
[
">=",
"2.4.0"
],
[
"<",
"2.16"
]
]
},
{
"name": "tifffile",
"specs": []
},
{
"name": "tk",
"specs": []
},
{
"name": "tqdm",
"specs": []
},
{
"name": "yapf",
"specs": []
},
{
"name": "zarr",
"specs": [
[
"~=",
"2.18.3"
]
]
}
],
"lcname": "lbm-caiman-python"
}
JSON
