This is a fork

basicpy-uncapped is a fork of peng-lab/BaSiCPy at tag v2.0.0, published because upstream's scipy<1.13 constraint transitively forbids numpy 2: the newest scipy under that bound is 1.12, which requires numpy<1.29. That pulls an entire environment back about two years.

The only changes are to packaging. No algorithm code is touched.

change	why
scipy<1.13 -> scipy	The whole of basicpy's scipy use is from scipy.fft import dctn in metrics_numpy.py, and dctn has been stable API since scipy 1.4. Reported upstream as issue #173, where another user reports testing successfully against scipy 1.18.0.
hyperactive moved to an autotune extra	It is already imported inside a try: in basicpy.py, with the except ImportError setting it to None, so it is optional at runtime. Requiring it caps pandas<3 for no benefit unless you autotune. Install basicpy-uncapped[autotune] if you need it.
version 2.0.0 -> 2.0.0.post1	Says "upstream 2.0.0, packaged once", and sorts after it.

The import name is unchanged, so from basicpy import BaSiC works as before - which also means this must not be installed alongside basicpy itself, as both provide a basicpy module and a basicpy console script.

Upstream is MIT and remains so; LICENSE is unmodified. All credit for BaSiC and BaSiCPy belongs to the original authors. If upstream relaxes the constraint, this fork should be abandoned in favour of it.

Original README follows.

BaSiCPy

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

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:

• BaSiCPy: A robust and scalable shadow correction tool for optical microscopy images (in prep.)
• A BaSiC Tool for Background and Shading Correction of Optical Microscopy Images by Tingying Peng, Kurt Thorn, Timm Schroeder, Lichao Wang, Fabian J Theis, Carsten Marr*, Nassir Navab*, Nature Communication 8:14836 (2017). doi: 10.1038/ncomms14836.

Backend note

Starting from version 2.0, BaSiCPy uses a PyTorch backend as the primary implementation.

The earlier JAX-based implementation is still available through older releases of the package.

Simple examples

Notebook	Description	Colab Link
timelapse_brightfield	100 continuous brightfield frames of a time-lapse movie of differentiating mouse hematopoietic stem cells.
timelapse_nanog	189 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.
WSI_brain	you can stitch image tiles together to view the effect of shading correction

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 CPU version

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 GPU version

To use BaSiCPy with GPU acceleration:

• 🧩 Install PyTorch according to your system configuration by following the official PyTorch installation guide.
• 💡 Install BaSiCPy (PyTorch backend only):

  pip install basicpy
  

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

Nicholas-Schaub 📆 👀 🚇 ⚠️ 💻 🤔

Tim Morello 💻 📖 👀 ⚠️ 🤔 🚇

Tingying Peng 🔣 💵 📆 📢 💻

Yohsuke T. Fukai 🔬 💻 🤔 👀 ⚠️ 💬 🚇

YuLiu-web 📖 📓

For details on the contribution roles, see the documentation.

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

• Lorenz Lamm (@LorenzLamm)
• Mohammad Mirkazemi (@Mirkazemi)