Home

Awesome

BaSiCPy

A python package for background and shading correction of optical microscopy images

PyPI Status Python Version License Tests pre-commit Black Read the Docs

<!-- ALL-CONTRIBUTORS-BADGE:START - Do not remove or modify this section -->

All Contributors

<!-- ALL-CONTRIBUTORS-BADGE:END -->

BaSiCPy is a python package for background and shading correction of optical microscopy images. It is developed based on the Matlab version of BaSiC tool with major improvements in the algorithm.

Reference:

Simple examples

NotebookDescriptionColab Link
timelapse_brightfield100 continuous brightfield frames of a time-lapse movie of differentiating mouse hematopoietic stem cells.Open In Colab
timelapse_nanog189 continuous fluorescence frames of a time-lapse movie of differentiating mouse embryonic stem cells, which move much more slower compared to the fast moving hematopoietic stem cells, resulting in a much larger correlation between frames. Note that in this challenging case, the automatic parameters are no longer optimal, so we use the manual parameter setting (larger smooth regularization on both flat-field and dark-field) to improve BaSiC’s performance.Open In Colab
WSI_brainyou can stitch image tiles together to view the effect of shading correctionOpen In Colab

You can also find examples of running the package at notebooks folder. Data used in the examples and a description can be downloaded from Zenodo.


Usage

See Read the Docs for the detailed usage.

Installation

For Mac (Intel chip), Linux or WSL2 users

Install from PyPI

pip install basicpy

or install the latest development version

git clone https://github.com/peng-lab/BaSiCPy.git
cd BaSiCPy
pip install .

For Mac users with M1 / M2 chip

BaSiCPy requires jax, which has potential build issue with M1 chips. One easiest solution is using Miniforge as explained here. In the Miniforge environment, please try the following:

conda install -c conda-forge jax jaxlib
pip install basicpy

For Windows users

BaSiCPy requires jax which does not support Windows officially. However, thanks to cloudhan/jax-windows-builder, we can install BaSiCPy as follows:

pip install "jax[cpu]==0.4.11" -f https://whls.blob.core.windows.net/unstable/index.html --use-deprecated legacy-resolver
pip install ml-dtypes==0.2.0
pip install basicpy

One may need to add

import jax
jax.config.update('jax_platform_name', 'cpu')

at the top of the script to ensure that JAX uses CPU.

For details and latest updates, see this issue.

Install with dev dependencies

git clone https://github.com/peng-lab/BaSiCPy.git
cd BaSiCPy
python -m venv venv
source venv/bin/activate
pip install -e '.[dev]'

Development

bump2version

This repository uses bump2version to manage dependencies. New releases are pushed to PyPi in the CI pipeline when a new version is committed with a version tag and pushed to the repo.

The development flow should use the following process:

  1. New features and bug fixes should be pushed to dev
  2. When tests have passed a new development version is ready to be release, use bump2version major|minor|patch. This will commit and create a new version tag with the -dev suffix.
  3. Additional fixes/features can be added to the current development release by using bump2version build.
  4. Once the new bugs/features have been tested and a main release is ready, use bump2version release to remove the -dev suffix.

After creating a new tagged version, push to Github and the version will be built and pushed to PyPi.

All-contributors

This repository uses All Contributors to manage the contributor list. Please execute the following to add/update contributors.

yarn
yarn all-contributors add username contribution
yarn all-contributors generate # to reflect the changes to README.md

For the possible contribution types, see the All Contributors documentation.

Contributors

Current version

<!-- ALL-CONTRIBUTORS-LIST:START - Do not remove or modify this section --> <!-- prettier-ignore-start --> <!-- markdownlint-disable --> <table> <tr> <td align="center"><a href="https://github.com/Nicholas-Schaub"><img src="https://avatars.githubusercontent.com/u/15925882?v=4?s=100" width="100px;" alt=""/><br /><sub><b>Nicholas-Schaub</b></sub></a><br /><a href="#projectManagement-Nicholas-Schaub" title="Project Management">πŸ“†</a> <a href="https://github.com/peng-lab/BaSiCPy/pulls?q=is%3Apr+reviewed-by%3ANicholas-Schaub" title="Reviewed Pull Requests">πŸ‘€</a> <a href="#infra-Nicholas-Schaub" title="Infrastructure (Hosting, Build-Tools, etc)">πŸš‡</a> <a href="https://github.com/peng-lab/BaSiCPy/commits?author=Nicholas-Schaub" title="Tests">⚠️</a> <a href="https://github.com/peng-lab/BaSiCPy/commits?author=Nicholas-Schaub" title="Code">πŸ’»</a> <a href="#ideas-Nicholas-Schaub" title="Ideas, Planning, & Feedback">πŸ€”</a></td> <td align="center"><a href="https://github.com/tdmorello"><img src="https://avatars.githubusercontent.com/u/34800427?v=4?s=100" width="100px;" alt=""/><br /><sub><b>Tim Morello</b></sub></a><br /><a href="https://github.com/peng-lab/BaSiCPy/commits?author=tdmorello" title="Code">πŸ’»</a> <a href="https://github.com/peng-lab/BaSiCPy/commits?author=tdmorello" title="Documentation">πŸ“–</a> <a href="https://github.com/peng-lab/BaSiCPy/pulls?q=is%3Apr+reviewed-by%3Atdmorello" title="Reviewed Pull Requests">πŸ‘€</a> <a href="https://github.com/peng-lab/BaSiCPy/commits?author=tdmorello" title="Tests">⚠️</a> <a href="#ideas-tdmorello" title="Ideas, Planning, & Feedback">πŸ€”</a> <a href="#infra-tdmorello" title="Infrastructure (Hosting, Build-Tools, etc)">πŸš‡</a></td> <td align="center"><a href="https://github.com/tying84"><img src="https://avatars.githubusercontent.com/u/11461947?v=4?s=100" width="100px;" alt=""/><br /><sub><b>Tingying Peng</b></sub></a><br /><a href="#data-tying84" title="Data">πŸ”£</a> <a href="#financial-tying84" title="Financial">πŸ’΅</a> <a href="#projectManagement-tying84" title="Project Management">πŸ“†</a> <a href="#talk-tying84" title="Talks">πŸ“’</a> <a href="https://github.com/peng-lab/BaSiCPy/commits?author=tying84" title="Code">πŸ’»</a></td> <td align="center"><a href="https://github.com/yfukai"><img src="https://avatars.githubusercontent.com/u/5919272?v=4?s=100" width="100px;" alt=""/><br /><sub><b>Yohsuke T. Fukai</b></sub></a><br /><a href="#research-yfukai" title="Research">πŸ”¬</a> <a href="https://github.com/peng-lab/BaSiCPy/commits?author=yfukai" title="Code">πŸ’»</a> <a href="#ideas-yfukai" title="Ideas, Planning, & Feedback">πŸ€”</a> <a href="https://github.com/peng-lab/BaSiCPy/pulls?q=is%3Apr+reviewed-by%3Ayfukai" title="Reviewed Pull Requests">πŸ‘€</a> <a href="https://github.com/peng-lab/BaSiCPy/commits?author=yfukai" title="Tests">⚠️</a> <a href="#question-yfukai" title="Answering Questions">πŸ’¬</a> <a href="#infra-yfukai" title="Infrastructure (Hosting, Build-Tools, etc)">πŸš‡</a></td> <td align="center"><a href="https://github.com/YuLiu-web"><img src="https://avatars.githubusercontent.com/u/70626217?v=4?s=100" width="100px;" alt=""/><br /><sub><b>YuLiu-web</b></sub></a><br /><a href="https://github.com/peng-lab/BaSiCPy/commits?author=YuLiu-web" title="Documentation">πŸ“–</a> <a href="#userTesting-YuLiu-web" title="User Testing">πŸ““</a></td> </tr> </table> <!-- markdownlint-restore --> <!-- prettier-ignore-end --> <!-- ALL-CONTRIBUTORS-LIST:END -->

For details on the contribution roles, see the documentation.

Old version (f3fcf19), used as the reference implementation to check the approximate algorithm