pystack3d.bkg_removal module

Functions related to the background removal processing

pystack3d.bkg_removal.init_args(params, shape)

Initialize arguments related to the current processing (‘bkg_removal’) and return a specific array to share (coefs)

Parameters:

params (dict) – Dictionary related to the current process. See the related documentation for more details.
shape (tuple of 3 int) – Shape of the stack to process

Returns:

coefs – Coefficients of the polynom to be shared during the (multi)processing

Return type:

numpy.ndarray((shape[0], len(powers)))

pystack3d.bkg_removal.bkg_removal(fnames=None, inds_partition=None, queue_incr=None, powers=None, skip_factors=(10, 10), skip_averaging=False, threshold_min=None, threshold_max=None, weight_func='HuberT', preserve_avg=False, output_dirname=None)

Function dedicated to the background removal processing

Parameters:

fnames (list of pathlib.Path, optional) – List of ‘.tif’ filenames to process
inds_partition (list of ints, optional) – List of indexes to be considered by the global var SHARED_ARRAY when working in multiprocessing
queue_incr (multiprocessing.Queue, optional) – Queue passed to the function to interact with the progress bar
powers (list of q-lists of 2 or 3 ints, optional) – Powers related to each term of the polynomial basis (in invlex order). Example: 1 + y**2 + x + x**2 * y -> [[0, 0], [0, 2], [1, 0], [2, 1]]
skip_factors (tuple of 2 or 3 ints, optional) – Skipping factors in each direction to perform polynomial fitting on a reduced image
threshold_min (floats, optional) – Relative thresholds used to exclude low and high values in the background removal processing
threshold_max (floats, optional) – Relative thresholds used to exclude low and high values in the background removal processing
skip_averaging (bool, optional) – Activation key for averaging when skip_factors is used
weight_func (str, optional) – Weight function (‘HuberT’ or ‘Hampel’) to consider by the M-estimator. For more details see : https://www.statsmodels.org/stable/rlm.html If None, polynomial fitting is calculated according to the classical ‘leastsq’ algorithm when solving : A.X = B
preserve_avg (bool, optional) – Activation key to preserve the average between the input and the output (work only with background evaluated from ‘3D’ coefficients)
output_dirname (str, optional) – Directory pathname for process results saving

pystack3d.bkg_removal.bkg_saving(bkg_dirname, fname, bkg): Save bkg image in .png format with vmin, vmax values displayed

pystack3d.bkg_removal.get_powers_2d(powers): Return the 2D powers related to the ‘powers’ 1rst and 2nd indices

pystack3d.bkg_removal.powers_from_orders(orders, cross_terms)

Return ‘powers’ from polynomial ‘orders’

Parameters:

orders (tuple of 2 or 3 ints) – Polynomial orders in x, y and potentially z directions respectively
cross_terms (bool, optional) – Activation key to take into account cross terms in the polynom

Returns:

powers – Powers related to each term of the polynomial basis (in invlex order). Example: orders=(2, 1), cross_terms=False : basis = 1 + y + x + x**2

-> powers = [[0, 0], [0, 1], [1, 0], [2, 0]]

orders=[2, 1], cross_terms=True1 + y + x + x*y + x**2 + x**2*y: -> powers = [[0, 0], [0, 1], [1, 0], [1, 1], [2, 0], [2, 1]]

Return type:

list of q-lists of 2 or 3 ints

pystack3d.bkg_removal.powers_from_expr(expr, dim=3, vars=None, force_cst_term=False)

Return ‘powers’ from expression (in invlex order)

Examples

>> expr = “y + x + x*y + x**2 + x**2*y” >> print(powers_from_expr(expr)) >> [[0, 1], [1, 0], [1, 1], [2, 0], [2, 1]] >> print(powers_from_expr(expr, force_cst_term=True)) >> [[0, 0], [0, 1], [1, 0], [1, 1], [2, 0], [2, 1]]

pystack3d.bkg_removal.expr_from_powers(powers, variables=['x', 'y', 'z'])

Return expression from ‘powers’

Examples

>> powers = [[0, 1], [1, 0], [1, 1], [2, 0], [2, 1]] >> print(expr_from_powers(powers, variables=[‘x’, ‘y’])) >> “y + x + x*y + x**2 + x**2*y”

pystack3d.bkg_removal.bkg_eval(arr, powers, skip_factors=(10, 10), threshold_min=None, threshold_max=None, skip_averaging=False, weight_func='HuberT', poly_basis_precalc=None, poly_basis_precalc_skip=None, kwargs_3d=None, preserve_avg=False)

Background removal function dedicated to stack3d

Parameters:

arr (np.ndarray((m, n)) or np.ndarray((m, n, p))) – 2D or 3D array
powers (list of q-lists of 2 or 3 ints) – Powers related to each term of the polynomial basis (in invlex order). Example: 1 + y**2 + x + x**2 * y -> [[0, 0], [0, 2], [1, 0], [2, 1]]
skip_factors (tuple of 2 or 3 ints, optional) – Skipping factors in each direction to perform polynomial fitting on a reduced image
threshold_min (floats, optional) –

Thresholds used to exclude low and high values in the background removal
processing
threshold_max (floats, optional) –

Thresholds used to exclude low and high values in the background removal
processing
skip_averaging (bool, optional) – Activation key for averaging when skip_factors is used.
weight_func (str, optional) – Weight function (‘HuberT’ or ‘Hampel’) to consider by the M-estimator. For more details see : https://www.statsmodels.org/stable/rlm.html If None, polynomial fitting is calculated according to the classical ‘leastsq’ algorithm when solving : A.X = B
poly_basis_precalc (np.ndarray((m*n, q), optional) – Pre-calculated polynomial basis to significantly decrease CPU time when dealing with huge and repetitive task
poly_basis_precalc_skip (np.ndarray((m//skip_factors[0]*n//skip_factors[1],) –
q) – Pre-calculated polynomial basis taking into account the ‘skip_factors’
optional – Pre-calculated polynomial basis taking into account the ‘skip_factors’
kwargs_3d (dict, optional) – Dictionary related to 3D background calculation
preserve_avg (bool, optional) – Activation key to preserve the average between the input and the output (work only with background evaluated from ‘3D’ coefficients)

Returns:

arr_bkg (numpy.ndarray((m, n)) or numpy.ndarray((m, n, p))) – Final array with the background removed
bkg (numpy.ndarray((m, n)) or numpy.ndarray((m, n, p))) – array related to the background
coefs (numpy.ndarray(q)) – Polynomial coefficients resulting from the fit

pystack3d.bkg_removal.poly_basis_calculation(shape, powers, skip_factors=None)

Return the polynomial basis related to ‘powers’ and associated to a ND-array

Parameters:

shape (tuple of 2 (m,n) or 3 (m,n,p) ints) – shape of the 2D or 3D array
powers (list of q-lists of 2 or 3 ints) – Powers related to each term of the polynomial basis (in invlex order). Example: 1 + y**2 + x + x**2 * y -> [[0, 0], [0, 2], [1, 0], [2, 1]]
skip_factors (tuple of 2 or 3 ints, optional) – Skipping factors in each direction to perform polynomial fitting on a reduced image

Returns:

poly_basis – The related polynomial basis

Return type:

numpy.ndarray((m*n, q) or numpy.ndarray((m*n*p, q)

pystack3d.bkg_removal.bkg_calculation(arr, powers, skip_factors=None, skip_averaging=False, weight_func='HuberT', poly_basis_precalc=None, poly_basis_precalc_skip=None)

Evaluate background of a ND-array from polynomial fitting.

Parameters:

arr (np.ndarray((m, n)) or np.ndarray((m, n, p))) – 2D or 3D array
powers (list of q-lists of 2 or 3 ints) – Powers related to each term of the polynomial basis (in invlex order). Example: 1 + y**2 + x + x**2 * y -> [[0, 0], [0, 2], [1, 0], [2, 1]]
skip_factors (tuple of 2 or 3 ints, optional) – Skipping factors in each direction to perform polynomial fitting on a reduced image
skip_averaging (bool, optional) – Activation key for averaging when skip_factors is used.
weight_func (str, optional) – Weight function (‘HuberT’, ‘Hampel’,…) to consider by the M-estimator. For more details see : https://www.statsmodels.org/stable/rlm.html If None, polynomial fitting is calculated according to the classical ‘leastsq’ algorithm when solving : A.X = B
poly_basis_precalc (np.ndarray((m*n, q)), optional) – Pre-calculated polynomial basis to significantly decrease CPU time when dealing with huge and repetitive task
poly_basis_precalc_skip (np.ndarray((m//skip_factors[0]*n//skip_factors[1],) –
q) – Pre-calculated polynomial basis taking into account the ‘skip_factors’
optional – Pre-calculated polynomial basis taking into account the ‘skip_factors’

Returns:

bkg (numpy.ndarray((m, n)) or numpy.ndarray((m, n, p))) – array related to the background
coefs (numpy.ndarray(q)) – Polynomial coefficients resulting from the fit where q = len(powers)
poly_basis (numpy.ndarray((m*n, q) or numpy.ndarray((m*n*p, q)) – The related polynomial basis

pystack3d.bkg_removal.bkg_3d_from_slices(k, shape_3d, coefs_3d, powers_3d, poly_basis_precalc=None)

Background calculation on a (2D) slice from 3D coefficients previously calculated

Parameters:

k (int) – Index of the slice to work with (related to shape_3d[2] axis)
shape_3d (tuple of 3 ints (m, n, p)) – Shape associated to the 3D Array on which the 3D-Background coefficients has been previuosly calculated
coefs_3d (List of q-floats) – 3D-Background pre-calculated coefficients where q = len(powers)
powers_3d (iterable of q-iterables of 3 ints) – Powers associated to each term of the polynom (in invlex order). Example: 1 + x*z + x**2 * y -> [[0, 0, 0], [1, 0, 1], [2, 1, 0]]
poly_basis_precalc (np.ndarray((m*n, q), optional) – Pre-calculated polynomial basis taking into account the ‘skip_factors’

Returns:

bkg – 3D background estimated on the slice

Return type:

numpy.ndarray((m, n))

pystack3d.bkg_removal.plot(output_dirname): Plot the specific data related to the current process