API Reference

BaSiC

Main BaSiC class.

enum basicpy.basicpy.FittingMode(value)

Fit method enum.

Member Type: str

Valid values are as follows:

ladmap: str = <FittingMode.ladmap: 'ladmap'>

approximate: str = <FittingMode.approximate: 'approximate'>

enum basicpy.basicpy.ResizeMode(value)

Resize method enum.

Member Type: str

Valid values are as follows:

jax: str = <ResizeMode.jax: 'jax'>

skimage: str = <ResizeMode.skimage: 'skimage'>

skimage_dask: str = <ResizeMode.skimage_dask: 'skimage_dask'>

enum basicpy.basicpy.TimelapseTransformMode(value)

Timelapse transformation enum.

Member Type: str

Valid values are as follows:

additive: str = <TimelapseTransformMode.additive: 'additive'>

multiplicative: str = <TimelapseTransformMode.multiplicative: 'multiplicative'>

pydantic model basicpy.basicpy.BaSiC

A class for fitting and applying BaSiC illumination correction profiles.

Show JSON schema

{
   "title": "BaSiC",
   "description": "A class for fitting and applying BaSiC illumination correction profiles.",
   "type": "object",
   "properties": {
      "baseline": {
         "title": "Baseline"
      },
      "darkfield": {
         "title": "Darkfield"
      },
      "fitting_mode": {
         "description": "Must be one of ['ladmap', 'approximate']",
         "default": "ladmap",
         "allOf": [
            {
               "$ref": "#/definitions/FittingMode"
            }
         ]
      },
      "epsilon": {
         "title": "Epsilon",
         "description": "Weight regularization term.",
         "default": 0.1,
         "type": "number"
      },
      "flatfield": {
         "title": "Flatfield"
      },
      "get_darkfield": {
         "title": "Get Darkfield",
         "description": "When True, will estimate the darkfield shading component.",
         "default": false,
         "type": "boolean"
      },
      "smoothness_flatfield": {
         "title": "Smoothness Flatfield",
         "description": "Weight of the flatfield term in the Lagrangian.",
         "default": 1.0,
         "type": "number"
      },
      "smoothness_darkfield": {
         "title": "Smoothness Darkfield",
         "description": "Weight of the darkfield term in the Lagrangian.",
         "default": 1.0,
         "type": "number"
      },
      "sparse_cost_darkfield": {
         "title": "Sparse Cost Darkfield",
         "description": "Weight of the darkfield sparse term in the Lagrangian.",
         "default": 0.01,
         "type": "number"
      },
      "max_iterations": {
         "title": "Max Iterations",
         "description": "Maximum number of iterations for single optimization.",
         "default": 500,
         "type": "integer"
      },
      "max_reweight_iterations": {
         "title": "Max Reweight Iterations",
         "description": "Maximum number of reweighting iterations.",
         "default": 10,
         "type": "integer"
      },
      "max_reweight_iterations_baseline": {
         "title": "Max Reweight Iterations Baseline",
         "description": "Maximum number of reweighting iterations for baseline.",
         "default": 5,
         "type": "integer"
      },
      "max_workers": {
         "title": "Max Workers",
         "description": "Maximum number of threads used for processing.",
         "default": 2,
         "type": "integer"
      },
      "rho": {
         "title": "Rho",
         "description": "Parameter rho for mu update.",
         "default": 1.5,
         "type": "number"
      },
      "mu_coef": {
         "title": "Mu Coef",
         "description": "Coefficient for initial mu value.",
         "default": 12.5,
         "type": "number"
      },
      "max_mu_coef": {
         "title": "Max Mu Coef",
         "description": "Maximum allowed value of mu, divided by the initial value.",
         "default": 10000000.0,
         "type": "number"
      },
      "optimization_tol": {
         "title": "Optimization Tol",
         "description": "Optimization tolerance.",
         "default": 0.001,
         "type": "number"
      },
      "optimization_tol_diff": {
         "title": "Optimization Tol Diff",
         "description": "Optimization tolerance for update diff.",
         "default": 0.01,
         "type": "number"
      },
      "resize_mode": {
         "description": "Resize mode to use when downsampling images. Must be one of 'jax', 'skimage', and 'skimage_dask'",
         "default": "jax",
         "allOf": [
            {
               "$ref": "#/definitions/ResizeMode"
            }
         ]
      },
      "resize_params": {
         "title": "Resize Params",
         "description": "Parameters for the resize function when downsampling images.",
         "default": {},
         "type": "object"
      },
      "reweighting_tol": {
         "title": "Reweighting Tol",
         "description": "Reweighting tolerance in mean absolute difference of images.",
         "default": 0.01,
         "type": "number"
      },
      "sort_intensity": {
         "title": "Sort Intensity",
         "description": "Whether or not to sort the intensities of the image.",
         "default": false,
         "type": "boolean"
      },
      "working_size": {
         "title": "Working Size",
         "description": "Size for running computations. None means no rescaling.",
         "default": 128,
         "anyOf": [
            {
               "type": "integer"
            },
            {
               "type": "array",
               "items": {
                  "type": "integer"
               }
            }
         ]
      }
   },
   "additionalProperties": false,
   "definitions": {
      "FittingMode": {
         "title": "FittingMode",
         "description": "Fit method enum.",
         "enum": [
            "ladmap",
            "approximate"
         ],
         "type": "string"
      },
      "ResizeMode": {
         "title": "ResizeMode",
         "description": "Resize method enum.",
         "enum": [
            "jax",
            "skimage",
            "skimage_dask"
         ],
         "type": "string"
      }
   }
}

field baseline: Optional[ndarray] = None

Holds the baseline for the shading model.

Validated by

debug_log_values

field darkfield: ndarray [Optional]

Holds the darkfield component for the shading model.

Validated by

debug_log_values

field epsilon: float = 0.1

Weight regularization term.

Validated by

debug_log_values

field fitting_mode: FittingMode = FittingMode.ladmap

Must be one of [‘ladmap’, ‘approximate’]

Validated by

debug_log_values

field flatfield: ndarray [Optional]

Holds the flatfield component for the shading model.

Validated by

debug_log_values

field get_darkfield: bool = False

When True, will estimate the darkfield shading component.

Validated by

debug_log_values

field max_iterations: int = 500

Maximum number of iterations for single optimization.

Validated by

debug_log_values

field max_mu_coef: float = 10000000.0

Maximum allowed value of mu, divided by the initial value.

Validated by

debug_log_values

field max_reweight_iterations: int = 10

Maximum number of reweighting iterations.

Validated by

debug_log_values

field max_reweight_iterations_baseline: int = 5

Maximum number of reweighting iterations for baseline.

Validated by

debug_log_values

field max_workers: int = 2

Maximum number of threads used for processing.

Validated by

debug_log_values

field mu_coef: float = 12.5

Coefficient for initial mu value.

Validated by

debug_log_values

field optimization_tol: float = 0.001

Optimization tolerance.

Validated by

debug_log_values

field optimization_tol_diff: float = 0.01

Optimization tolerance for update diff.

Validated by

debug_log_values

field resize_mode: ResizeMode = ResizeMode.jax

Resize mode to use when downsampling images. Must be one of ‘jax’, ‘skimage’, and ‘skimage_dask’

Validated by

debug_log_values

field resize_params: Dict = {}

Parameters for the resize function when downsampling images.

Validated by

debug_log_values

field reweighting_tol: float = 0.01

Reweighting tolerance in mean absolute difference of images.

Validated by

debug_log_values

field rho: float = 1.5

Parameter rho for mu update.

Validated by

debug_log_values

field smoothness_darkfield: float = 1.0

Weight of the darkfield term in the Lagrangian.

Validated by

debug_log_values

field smoothness_flatfield: float = 1.0

Weight of the flatfield term in the Lagrangian.

Validated by

debug_log_values

field sort_intensity: bool = False

Whether or not to sort the intensities of the image.

Validated by

debug_log_values

field sparse_cost_darkfield: float = 0.01

Weight of the darkfield sparse term in the Lagrangian.

Validated by

debug_log_values

field working_size: Union[int, List[int], None] = 128

Size for running computations. None means no rescaling.

Validated by

debug_log_values

autotune(images, fitting_weight=None, skip_shape_warning=False, *, optmizer=None, n_iter=100, search_space=None, init_params=None, timelapse=False, histogram_qmin=0.01, histogram_qmax=0.99, histogram_bins=100, histogram_use_fitting_weight=True, early_stop=True, early_stop_n_iter_no_change=10, early_stop_torelance=1e-06, random_state=None)

Automatically tune the parameters of the model.

Return type

None

Parameters

images – input images to fit and correct. See fit.
fitting_weight – Relative fitting weight for each pixel. See fit.
skip_shape_warning – if True, warning for last dimension less than 10 is suppressed.
optimizer – optimizer to use. Defaults to hyperactive.optimizers.HillClimbingOptimizer.
n_iter – number of iterations for the optimizer. Defaults to 100.
search_space – search space for the optimizer. Defaults to a reasonable range for each parameter.
init_params – initial parameters for the optimizer. Defaults to a reasonable initial value for each parameter.
timelapse – if True, corrects the timelapse/photobleaching offsets.
histogram_qmin – the minimum quantile to use for the histogram. Defaults to 0.01.
histogram_qmax – the maximum quantile to use for the histogram. Defaults to 0.99.
histogram_bins – the number of bins to use for the histogram. Defaults to 100.
early_stop – if True, stops the optimization when the change in entropy is less than early_stop_torelance. Defaults to True.
early_stop_n_iter_no_change – the number of iterations for early stopping. Defaults to 10.
early_stop_torelance – the absolute value torelance for early stopping.
random_state – random state for the optimizer.

validator debug_log_values » all fields: Use a validator to echo input values.

fit(images, fitting_weight=None, skip_shape_warning=False)

Generate illumination correction profiles from images.

Return type

None

Parameters

images – Input images to fit shading model. Must be 3-dimensional or 4-dimensional array with dimension of (T,Y,X) or (T,Z,Y,X). T can be either of time or mosaic position. Multichannel images should be independently corrected for each channel.
fitting_weight – Relative fitting weight for each pixel. Higher value means more contribution to fitting. Must has the same shape as images.
skip_shape_warning – if True, warning for last dimension less than 10 is suppressed.

Example

>>> from basicpy import BaSiC
>>> from basicpy import datasets as bdata
>>> images = bdata.wsi_brain()
>>> basic = BaSiC()  # use default settings
>>> basic.fit(images)

fit_transform(images, timelapse=False)

Fit and transform on data.

Return type: Union[Tuple[ndarray, ndarray], ndarray]
Parameters: images – input images to fit and correct. See fit.
Returns: corrected images

Example

>>> corrected = basic.fit_transform(images)

classmethod load_model(model_dir)

Create a new instance from a model folder.

Return type: BaSiC

save_model(model_dir, overwrite=False)

Save current model to folder.

Return type: None
Parameters: model_dir – path to model directory
Raises: FileExistsError – if model directory already exists

transform(images, timelapse=False)

Apply profile to images.

Return type

Union[Tuple[ndarray, ndarray], ndarray]

Parameters

images – input images to correct. See fit.
timelapse – If True, corrects the timelapse/photobleaching offsets, assuming that the residual is the product of flatfield and the object fluorescence. Also accepts “multiplicative” (the same as True) or “additive” (residual is the object fluorescence).

Returns

corrected images

Example

>>> basic.fit(images)
>>> corrected = basic.transform(images)

property reweight_score: The BaSiC fit final reweighting score.

property score: The BaSiC fit final score.

property settings: Dict

Current settings.

Returns: current settings

Tools

Utilities to support BaSiC.