PyBaSiC

Python implementation of the BaSiC shading correction method.

• Original paper: T. Peng et al., “A BaSiC tool for background and shading correction of optical microscopy images,” Nat. Commun., vol. 8, p. 14836, Jun. 2017. DOI:10.1038/ncomms14836
• Nature Supplementary Materials: PDF
• Matlab implementation: https://github.com/QSCD/BaSiC
• Fiji plugin: URL
• Demo data examples: Dropbox

Installation

Option 1: pip

pip install pybasic-illumination-correction

Option 2: poetry

• You need Poetry.
• Install with

poetry install

This will create a virtual environment and install all the dependencies. To execute the basic_shading_correction.py script, activate the virtual environment with poetry shell, then execute the script with python <path/to/script.py>

Usage

The main script to perform the retrospective shading estimation and correction is basic_shading_correction. Here is a description of its arguments. Note: You must first activate the pybasic environment to run this script.

>> basic_shading_correction --help
usage: Shading correction algorithm based on the BaSiC method
       [-h] [--extension EXTENSION] [--estimate_darkfield]
       [--apply_correction] [--use_flatfield USE_FLATFIELD]
       [--use_darkfield USE_DARKFIELD] [--epsilon EPSILON] [--l_s L_S]
       [--l_d L_D] [--output_flatfield_filename OUTPUT_FLATFIELD_FILENAME]
       [--output_darkfield_filename OUTPUT_DARKFIELD_FILENAME]
       directory output_directory

positional arguments:
  directory             Full path a directory containing the tiles to process
  output_directory      Full path to a directory where the output will be
                        saved

optional arguments:
  -h, --help            show this help message and exit
  --extension EXTENSION
                        Image tile extension (default=.tif)
  --estimate_darkfield  Estimate the darkfield in addition to the flatfield.
  --apply_correction    Apply the shading correction with the estimated or
                        loaded profiles.
  --use_flatfield USE_FLATFIELD
                        Use existing flatfield (skip estimation)
  --use_darkfield USE_DARKFIELD
                        Use existing darkfield (skip estimation)
  --epsilon EPSILON     Stability coefficient to use for the shading
                        correction. (default=1e-06)
  --l_s L_S             Flat-field regularization parameter (set automatically
                        if None)
  --l_d L_D             Dark-field regularization parameter (set automatically
                        if None)
  --output_flatfield_filename OUTPUT_FLATFIELD_FILENAME
                        Optional output flatfield filename (if none,
                        flatfield.tif will be saved in the output directory).
  --output_darkfield_filename OUTPUT_DARKFIELD_FILENAME
                        Optional output flatfield filename (if none,
                        darkfield.tif will be saved in the output directory).
  --verbose