# 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/8e/50/577212abf662bb7f388448361200c8c7ee8f4715f93a242311c6aeb83ad0/lbm_caiman_python-1.0.11.tar.gz",
"platform": null,
"description": "# LBM-CaImAn-Python\r\n\r\n[**Installation**](https://github.com/MillerBrainObservatory/LBM-CaImAn-Python#installation) | [**Notebooks**](https://github.com/MillerBrainObservatory/LBM-CaImAn-Python/tree/master/demos/notebooks)\r\n \r\nPython implementation of the Light Beads Microscopy (LBM) computational pipeline.\r\n\r\nFor the `MATLAB` implementation, see [here](https://github.com/MillerBrainObservatory/LBM-CaImAn-MATLAB/)\r\n\r\n## Pipeline Steps:\r\n\r\n1. Image Assembly\r\n - Extract raw `tiffs` to planar timeseries\r\n2. Motion Correction\r\n - Template creation\r\n - Piecewise-rigid or non-rigid registration\r\n3. Segmentation\r\n - Iterative CNMF segmentation\r\n - Deconvolution\r\n - Refinement\r\n4. Collation\r\n - Lateral offset correction (between z-planes)\r\n - Collate images and metadata into a single volume\r\n\r\n## Requirements\r\n\r\n- caiman\r\n- mesmerize-core\r\n- scanreader\r\n- numpy\r\n- scipy\r\n- fastplotlib\r\n\r\n:exclamation: **Note:** This package makes heavy use of Fastplotlib for visualizations.\r\n\r\nFastplotlib runs on [Jupyter Lab](https://jupyterlab.readthedocs.io/en/stable/getting_started/installation.html),\r\nbut is not guarenteed to work with Jupyter Notebook or Visual Studio Code notebook environments. \r\n\r\n## Installation\r\n\r\nThis project is tested on Linux and Windows 10 using `Python 3.9` and `Python 3.10`.\r\n\r\nEnvironment setup is tested using `virtualenv` and `miniforge`.\r\n\r\nWe suggest using python virtual environments for the best results.\r\n\r\n### (Option 1). Python Virtual Environments\r\n\r\nEnsure you have a system-wide Python installation.\r\n\r\nThis project and it's dependencies are tested using `Python 3.9` and `Python 3.10`.\r\n\r\n**Note:** Make sure you deactivate `conda` environments before proceeding (`conda deactivate`).\r\n\r\nVerify `Python` and `pip` installations:\r\n\r\n- **Linux/macOS:**\r\n \r\n```bash\r\n\r\npython --version\r\n\r\npip --version\r\n```\r\n\r\n- **Windows:**\r\n\r\n```bash\r\npy --version\r\n\r\npy - m pip --version \r\n\r\n```\r\n\r\n:exclamation: Depending on how Python was installed,\r\nyou may need to use `python3` or `python3.x` and `pip3` or `pip3.x` instead of `python` and `pip`.\r\n\r\nYou should see a Python version output like `3.10.x` and a corresponding `pip` version.\r\n\r\nIf Python is not installed, or an unsupported version is installed (i.e. 3.7),\r\n\r\ndownload and install [python.org](https://www.python.org/) or refer to this [installation guide](https://docs.python-guide.org/starting/installation/).\r\n\r\nYou will also need [`git`](https://git-scm.com/):\r\n\r\n```bash\r\ngit --version\r\n```\r\n\r\n#### Create a virtual environment\r\n\r\nThis is normally in a directory dedicated to virtual environments, but can be anywhere you wish:\r\n\r\n```bash\r\npython -m venv ~/venv/lbm_caiman_python\r\n```\r\n\r\nActivate the virtual environment:\r\n\r\n- **Linux/macOS:**\r\n\r\n ```bash\r\n source ~/venv/lbm_caiman_python/bin/activate\r\n ```\r\n\r\n- **Windows:**\r\n\r\n ```bash\r\n source ~/venv/lbm_caiman_python/Scripts/activate\r\n ```\r\n\r\nUpgrade core tools in the virtual environment:\r\n\r\n```bash\r\npip install --upgrade setuptools wheel pip\r\n```\r\n\r\n#### Clone and install CaImAn\r\n\r\nCreate a directory to store the cloned repositories.\r\n\r\nAgain, this can be anywhere you wish:\r\n\r\n```bash\r\n\r\ncd ~\r\nmkdir repos\r\ncd repos\r\n\r\n```\r\n\r\nUse git to clone CaImAn:\r\n\r\n```bash\r\ngit clone https://github.com/flatironinstitute/CaImAn.git\r\n```\r\n\r\nInstall CaImAn:\r\n\r\n1. **CaImAn:**\r\n ```bash\r\n cd CaImAn\r\n pip install -r requirements.txt\r\n pip install .\r\n ```\r\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/).\r\n\r\n2. **Other dependencies:**\r\n\r\n ```bash\r\n pip install mesmerize-core\r\n pip install lbm_caiman_python\r\n pip install git+https://github.com/atlab/scanreader.git\r\n ```\r\n\r\n#### Run ipython to make sure everyting works\r\n\r\n``` python\r\n\r\nimport lbm_caiman_python as lcp\r\nimport mesmerize_core as mc\r\nimport scanreader as sr\r\n\r\nscan = sr.read_scan('path/to/data/*.tif', join_contiguous=True)\r\n\r\n```\r\n\r\n### virtualenv Troubleshooting\r\n\r\n#### Error During `pip install .` (CaImAn) on Linux\r\nIf you encounter errors during the installation of `CaImAn`, install the necessary development tools:\r\n```bash\r\nsudo apt-get install python3-dev\r\n```\r\n\r\n---\r\n\r\n### (Option 2). Conda\r\n\r\nMiniforge is the supported `conda` distribution. Anaconda and Miniconda require extra steps and is not covered in this guide.\r\n\r\nNote: Sometimes conda or mamba will get stuck at a step, such as creating an environment or installing a package.\r\n\r\nPressing Enter on your keyboard can sometimes help it continue when it pauses.\r\n\r\n1. Install `mamba` into your *base* environment:\r\n\r\n:exclamation: This step may take 10 minutes and display several messages like \"Solving environment: failed with...\" but it should eventually install mamba.\r\n\r\n``` bash\r\nconda activate base \r\nconda install -c conda-forge mamba\r\n```\r\n\r\n2. Create a new environment and install [mesmerize-core](https://github.com/nel-lab/mesmerize-core/tree/master)\r\n\r\n- Here, we use the `-n` flag to name the environment `lbm` , but you can name it whatever you'd like.\r\n- This step will install Python, mesmerize-core, CaImAn, and all required dependencies for those packages.\r\n\r\n``` bash\r\nconda create -n lbm -c conda-forge mesmerize-core\r\n```\r\n\r\nIf you already have `CaImAn` installed:\r\n\r\n``` bash\r\nconda install -n name-of-env-with-caiman mesmerize-core\r\n```\r\n\r\nActivate the environment and install `caimanmanager`:\r\n- if you used a name other than `lbm`, be sure to match the name you use here.\r\n\r\n``` bash\r\nconda activate lbm\r\ncaimanmanager install\r\n```\r\n\r\n3. Install [LBM-CaImAn-Python](https://pypi.org/project/lbm-caiman-python/) from pip:\r\n\r\n``` bash\r\n\r\npip install lbm_caiman_python\r\n\r\n```\r\n\r\n4. Install [scanreader](https://github.com/atlab/scanreader):\r\n\r\n``` bash\r\n\r\npip install git+https://github.com/atlab/scanreader.git\r\n\r\n```\r\n\r\n5. (Optional) Install `mesmerize-viz`:\r\n\r\nSeveral notebooks make use of [mesmerize-viz](https://github.com/kushalkolar/mesmerize-viz) for visualizing registration/segmentation results.\r\n\r\n``` bash\r\n\r\npip install mesmerize-viz\r\n\r\n```\r\n\r\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.\r\n\r\nhttps://www.youtube.com/watch?v=GWvaEeqA1hw\r\n\r\n## For Developers\r\n\r\nTo get the newest version of this package:\r\n\r\n``` bash\r\n\r\ngit clone https://github.com/MillerBrainObservatory/LBM-CaImAn-Python.git\r\n\r\ncd LBM-CaImAn-Python\r\n\r\npip install \".[docs]\"\r\n\r\n```\r\n\r\n## Troubleshooting\r\n\r\n### Conda Slow / Stalling\r\n\r\nif conda is behaving slow, clean the conda installation and update `conda-forge`:\r\n\r\n``` bash\r\n\r\nconda clean -a\r\n\r\nconda update -c conda-forge --all\r\n\r\n```\r\n\r\nDon't forget to press enter a few times if conda is taking a long time.\r\n\r\n### Recommended Conda Distribution\r\n\r\nThe recommended conda installer is [miniforge](https://github.com/conda-forge/miniforge).\r\n\r\nThis is a community-driven `conda`/`mamba` installer with pre-configured packages specific to [conda-forge](https://conda-forge.org/).\r\n\r\nThis helps avoid `conda-channel` conflicts and avoids any issues with the Anaconda TOS.\r\n\r\nYou can install the installer from a unix command line:\r\n\r\n``` bash\r\n\r\ncurl -L -O \"https://github.com/conda-forge/miniforge/releases/latest/download/Miniforge3-$(uname)-$(uname -m).sh\"\r\n\r\nbash Miniforge3-$(uname)-$(uname -m).sh\r\n\r\n```\r\n\r\nOr download the installer for your operating system [here](https://github.com/conda-forge/miniforge/releases).\r\n\r\n### Graphics Driver Issues\r\n\r\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).\r\n\r\n\r\n",
"bugtrack_url": null,
"license": "BSD-3-Clause",
"summary": "Light Beads Microscopy 2P Calcium Imaging Pipeline.",
"version": "1.0.11",
"project_urls": {
"Homepage": "https://github.com/millerbrainobservatory/LBM-CaImAn-Python"
},
"split_keywords": [
"pipeline",
"numpy",
"microscopy",
"scanimage",
"multiroi",
"tiff"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "a296345fa2124f73290f0226a18a09e87e84969bc58cf8e2cd2dafcc7e6f1c5f",
"md5": "b1eceec465bdba0d99da5800a145e994",
"sha256": "4fa8d42561ce00c526246b45acb49614922d13f3985a2dcf5d23103f68ccd764"
},
"downloads": -1,
"filename": "lbm_caiman_python-1.0.11-py3-none-any.whl",
"has_sig": false,
"md5_digest": "b1eceec465bdba0d99da5800a145e994",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 42252,
"upload_time": "2024-12-16T22:41:30",
"upload_time_iso_8601": "2024-12-16T22:41:30.415858Z",
"url": "https://files.pythonhosted.org/packages/a2/96/345fa2124f73290f0226a18a09e87e84969bc58cf8e2cd2dafcc7e6f1c5f/lbm_caiman_python-1.0.11-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "8e50577212abf662bb7f388448361200c8c7ee8f4715f93a242311c6aeb83ad0",
"md5": "2c092f93579696c6208ae6eed73449b3",
"sha256": "6dfdf0cd818a68554340e93f3fac30abb7c0dc4d5df8c0ca53640a178321f11c"
},
"downloads": -1,
"filename": "lbm_caiman_python-1.0.11.tar.gz",
"has_sig": false,
"md5_digest": "2c092f93579696c6208ae6eed73449b3",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 60441,
"upload_time": "2024-12-16T22:41:31",
"upload_time_iso_8601": "2024-12-16T22:41:31.512796Z",
"url": "https://files.pythonhosted.org/packages/8e/50/577212abf662bb7f388448361200c8c7ee8f4715f93a242311c6aeb83ad0/lbm_caiman_python-1.0.11.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-12-16 22:41:31",
"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": "coverage",
"specs": []
},
{
"name": "cython",
"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": "matplotlib",
"specs": [
[
"~=",
"3.9.2"
]
]
},
{
"name": "moviepy",
"specs": []
},
{
"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.16"
],
[
">=",
"2.4.0"
]
]
},
{
"name": "tifffile",
"specs": []
},
{
"name": "tk",
"specs": []
},
{
"name": "tqdm",
"specs": []
},
{
"name": "yapf",
"specs": []
},
{
"name": "zarr",
"specs": [
[
"~=",
"2.18.3"
]
]
}
],
"lcname": "lbm-caiman-python"
}
JSON
