Usage
API Reference
BaSiC
Main BaSiC class.
- enum basicpy.basicpy.Device(value)
An enumeration.
Valid values are as follows:
- cpu: str = <Device.cpu: 'cpu'>
- gpu: str = <Device.gpu: 'gpu'>
- tpu: str = <Device.tpu: 'tpu'>
- enum basicpy.basicpy.FittingMode(value)
An enumeration.
- Member Type
str
Valid values are as follows:
- ladmap: str = <FittingMode.ladmap: 'ladmap'>
- approximate: str = <FittingMode.approximate: 'approximate'>
- 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" }, "device": { "description": "Must be one of ['cpu','gpu','tpu'].", "default": "cpu", "allOf": [ { "$ref": "#/definitions/Device" } ] }, "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" }, "lambda_flatfield_coef": { "title": "Lambda Flatfield Coef", "description": "Weight of the flatfield term in the Lagrangian.", "default": 0.00125, "type": "number" }, "lambda_darkfield_coef": { "title": "Lambda Darkfield Coef", "description": "Relative weight of the darkfield term in the Lagrangian.", "default": 0.2, "type": "number" }, "lambda_darkfield_sparse_coef": { "title": "Lambda Darkfield Sparse Coef", "description": "Relative weight of the darkfield sparse term in the Lagrangian.", "default": 0.2, "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": 1e-06, "type": "number" }, "optimization_tol_diff": { "title": "Optimization Tol Diff", "description": "Optimization tolerance for update diff.", "default": 0.001, "type": "number" }, "resize_method": { "description": "Resize method to use when downsampling images.", "default": 4, "allOf": [ { "$ref": "#/definitions/ResizeMethod" } ] }, "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": "Wheather 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" } } ] } }, "definitions": { "Device": { "title": "Device", "description": "An enumeration.", "enum": [ "cpu", "gpu", "tpu" ] }, "FittingMode": { "title": "FittingMode", "description": "An enumeration.", "enum": [ "ladmap", "approximate" ], "type": "string" }, "ResizeMethod": { "title": "ResizeMethod", "description": "Image resize method.\n\nPossible values are:\n\nNEAREST:\n Nearest-neighbor interpolation.\n\nLINEAR:\n `Linear interpolation`_.\n\nLANCZOS3:\n `Lanczos resampling`_, using a kernel of radius 3.\n\nLANCZOS3:\n `Lanczos resampling`_, using a kernel of radius 5.\n\nCUBIC:\n `Cubic interpolation`_, using the Keys cubic kernel.\n\n.. _Linear interpolation: https://en.wikipedia.org/wiki/Bilinear_interpolation\n.. _Cubic interpolation: https://en.wikipedia.org/wiki/Bicubic_interpolation\n.. _Lanczos resampling: https://en.wikipedia.org/wiki/Lanczos_resampling", "enum": [ 0, 1, 2, 3, 4 ] } } }
- Config
arbitrary_types_allowed: bool = True
- Fields
- field baseline: Optional[numpy.ndarray] = None
Holds the baseline for the shading model.
- field darkfield: numpy.ndarray [Optional]
Holds the darkfield component for the shading model.
- field device: basicpy.basicpy.Device = Device.cpu
Must be one of [‘cpu’,’gpu’,’tpu’].
- field epsilon: float = 0.1
Weight regularization term.
- field fitting_mode: basicpy.basicpy.FittingMode = FittingMode.ladmap
Must be one of [‘ladmap’, ‘approximate’]
- field flatfield: numpy.ndarray [Optional]
Holds the flatfield component for the shading model.
- field get_darkfield: bool = False
When True, will estimate the darkfield shading component.
- field lambda_darkfield_coef: float = 0.2
Relative weight of the darkfield term in the Lagrangian.
- field lambda_darkfield_sparse_coef: float = 0.2
Relative weight of the darkfield sparse term in the Lagrangian.
- field lambda_flatfield_coef: float = 0.00125
Weight of the flatfield term in the Lagrangian.
- field max_iterations: int = 500
Maximum number of iterations for single optimization.
- field max_mu_coef: float = 10000000.0
Maximum allowed value of mu, divided by the initial value.
- field max_reweight_iterations: int = 10
Maximum number of reweighting iterations.
- field max_reweight_iterations_baseline: int = 5
Maximum number of reweighting iterations for baseline.
- field max_workers: int = 2
Maximum number of threads used for processing.
- field mu_coef: float = 12.5
Coefficient for initial mu value.
- field optimization_tol: float = 1e-06
Optimization tolerance.
- field optimization_tol_diff: float = 0.001
Optimization tolerance for update diff.
- field resize_method: jax._src.image.scale.ResizeMethod = ResizeMethod.CUBIC
Resize method to use when downsampling images.
- field reweighting_tol: float = 0.01
Reweighting tolerance in mean absolute difference of images.
- field rho: float = 1.5
Parameter rho for mu update.
- field sort_intensity: bool = False
Wheather or not to sort the intensities of the image.
- field working_size: Optional[Union[int, Iterable[int]]] = 128
Size for running computations. None means no rescaling.
- __init__(**kwargs)
Initialize BaSiC with the provided settings.
- fit(images, fitting_weight=None)
Generate illumination correction profiles from images.
- Parameters
images – Input images to fit shading model. Must be 3-dimensional array with dimension of (T,Y,X).
fitting_weight – relative fitting weight for each pixel. Higher value means more contribution to fitting. Must has the same shape as images.
Example
>>> from basicpy import BaSiC >>> from basicpy.tools import load_images >>> images = load_images('./images') >>> basic = BaSiC() # use default settings >>> basic.fit(images)
- Return type
None
- fit_transform(images, timelapse=True)
Fit and transform on data.
- Parameters
images – input images to fit and correct
- Returns
profiles and corrected images
Example
>>> profiles, corrected = basic.fit_transform(images)
- Return type
Union[Tuple[ndarray,ndarray],ndarray]
- save_model(model_dir, overwrite=False)
Save current model to folder.
- Parameters
model_dir – path to model directory
- Raises
FileExistsError – if model directory already exists
- Return type
None
- transform(images, timelapse=False)
Apply profile to images.
- Parameters
images – input images to correct
timelapse – calculate timelapse/photobleaching offsets. Currently does nothing.
- Returns
- An array of the same size as images. If timelapse is True, returns
a flat array of baseline corrections used in the calculations.
Example
>>> basic.fit(images) >>> corrected = basic.transform(images) >>> for i, im in enumerate(corrected): ... imsave(f"image_{i}.tif")
- Return type
Union[Tuple[ndarray,ndarray],ndarray]
- property reweight_score
The BaSiC fit final reweighting score
- property score
The BaSiC fit final score
- property settings: Dict
Current settings.
- Returns
current settings
- Return type
Dict
Tools
Utilities to support BaSiC.
- basicpy.tools.load_image(fname)
Loads an image.
- Parameters
fname – path to image file
- Returns
ndarray of image
- Return type
ndarray
- basicpy.tools.load_images(fnames, lazy=False)
Load images from files.
- Parameters
fnames – list of paths to images
lazy – return a generator rather than a list
- Returns
an iterable of images (a generator if
lazy = True, otherwise a list)- Return type
Iterable[ndarray]
- basicpy.tools.resize(image, shape)
Resize an image.
- Parameters
image – input image
shape – desired image output size
- Returns
resized image
- Return type
ndarray