Module `scm_confocal.util`

Functions

def align_stack(images, startim=0, threshold=0, binning=1, smooth=0, upsample=1, startoffset=None, cval=0, trim='valid', blocksize=None, show_process_im=False, apply_shift=True)

Cross correlation alignment of image stack. Based around skimage.feature.phase_cross_correlation with enables sub-pixel precise determination of the image shift via efficient FFT cross correlation.

When preprocessing (smoothing and/or binning and/or thresholding) is used, a copy of the data is created and used for determining the image shift, but the original (unprocessed) data is corrected for image shift and returned.

order of preprocessing is first thresholding, then binning, then smoothing

Parameters

images : Nd numpy array: the dataset which will be aligned along the first dimension (e.g. z)
startim : int: starting index that acts as reference for rest of stack
threshold : float: any pixel value below threshold is set to 0 before alignment
binning : int: factor to bin pixels in (x,y)
smooth : float: size of gaussian kernal for smoothing prior to calculating the translation
upsample : int: precision of translation in units of 1/pixel
startoffset : tuple of floats: shift to apply to the starting image before alignment
cval : float, optional: fill value for unknown values outside of images when shifting. The default is 0
trim : one of ['valid','full','same']: if/how to trim the stack after shifting images. In case of 'valid' the stack is trimmed down to the volume where all pixels were part of the input data, for 'full' the stack is padded with cval such that all pixels in the input are present in the output data and the shifting is done in a separate step after calculating all image shifts, and for 'same' the shape and position of the data is kept the same except for the shift imposed by startoffset. Note that in case of trim='full' the origin for shift and trim values is shifted to the top left corner of the padded stack. The default is 'valid'.
blocksize : int or tuple of ints, optional: see bin_stack()
show_process_im : bool, optional: whether the preprocessed input data is shown in a figure. The default is False.
apply_shift : bool, optional: if True, the shifted input data is returned. If False, the unchanged input data is returned. This saves computation time if the image shifts are to be used separately (e.g. to align a different detector channel). The default is True

Returns

images : numpy.array: the image data with optionally translation and trimming applied
shifts : list of ([z],y,x) tuples: image shift values for each image in the dataset
slices : list of slice: parameters for trimming

def average_nearest_neighbour_distance(features, pos_cols=['x (um)', 'y (um)', 'z (um)'])

finds average distance of nearest neighbours from pandas array of coordinates.

Parameters

features : pandas DataFrame: dataframe containing the particle coordinates
pos_cols : list of strings, optional: Names of columns to use for coordinates. The default is ['x (um)','y (um)','z (um)'].

Returns

float: average distance to the closest particle for all the pairs in the set

def bin_stack(images, n=1, blocksize=None, quiet=False, dtype=None)

bins numpy ndarrays in arbitrary dimensions by a factor n. Prior to binning, elements from the end are deleted until the length is a multiple of the bin factor. Executes averaging of bins in floating point precision, which is memory intensive for large stacks. Using smaller blocks reduces memory usage, but is less efficient.

Parameters

images : numpy.ndarray: ndarray containing the data
n : int or tuple of int, optional: factor to bin with for all dimensions (int) or each dimension individually (tuple with one int per dimension). The default is 1.
blocksize : int, optional: number of (binned) slices to process at a time to conserve memory. The default is entire stack.
quiet : bool, optional: suppresses printed output when True. The default is False.
dtype : (numpy) datatype, optional: datatype to use for output. Averaging of the binned pixels always occurs in floating point precision. The default is np.uint8.

Returns

images : numpy.ndarray: binned stack

def fit_powerlaw(x, y, weights=None, **kwargs)

Linear regression in log space of the MSD to get diffusion constant, which is a powerlaw in linear space of the form Ax*n

Parameters

x : list or numpy.array: x coordinates of data points to fit
y : list or numpy.array: y coordinates of data points to fit
weights : list or numpy.array, optional: list of weights to use for each (x,y) coordinate. The default is None.

**kwargs : arguments passed to scipy.optimize.curve_fit

Returns

A : float: constant A
n : float: power n
sigmaA : float: standard deviation in A
sigmaN : float: standard deviation in n

def flatfield_correction_apply(images, corrim, dtype=None, check_overflow=True)

Apply a correction to all images in a dataset based on a mask / correction image such as provided by util.flatfield_correction_init. Pixel values are divided by the correction image, accounting for integer overflow by clipping to the max value of the (integer) dtype.

Note that overflow checking is currently implemented using numpy masked arrays, which are extremely slow (up to 10x) when compared to normal numpy arrays. It can be bypassed using check_overflow for a memory and performance improvement.

Parameters

images : (sequence of) numpy.array: the images to correct. he last two dimensions are taken as the 2D images, other dimensions are preserved. Must have 2 or more dims.
corrim : numpy.array: The correction image to apply. Must have 2 or more dimensions, if there are more than 2 it must match images according to numpy broadcasting rules.
dtype : data type, optional: data type used for the output. The default is images.dtype.
check_overflow : bool, optional: Whether to check and avoid integer overflow. The default is True.

Returns

numpy.array: the corrected image array

Parameters

images : (sequence of) numpy array with >= 2 dimensions: image(s) to calculate a correction image for. The last two dimensions are taken as the 2D images.
kernelsize : int: cutoff size in fourier-space pixels (i.e. cycles per image-size) of cone-shaped low-pass fourier filter.
average : bool, optional: whether to average correction images along the first dimension of the supplied data. Requires >2 dimensions in the input data. The default is True.

Returns

numpy array: (array of) normalized correction images where the maximum is scaled to 1.

Parameters

features : pandas.DataFrame: output from trackpy.link containing tracking data
pos_cols : list of str, optional: names of columns to use for coordinates. The default is ['x','y','z'].
t_col : str, optional: name of column containing timestamps. The default is 't (s)'.
nparticles : int, optional: number of particles to use for calculation (useful for large datasets). The default is all particles.
pickrandom : bool, optional: whether to pick nparticles randomly or not, if False it takes the n longest tracked particles from data. The default is False.
bins : int or sequence of floats, optional: number of bins or bin edges for output. The default is 20.
tmin : float, optional: left edge of first bin. The default is min(t_col).
tmax : float, optional
right edge of last bin, The default is max(t_col).
itmin : int, optional: minimum (integer) step size in timesteps. The default is 1.
itmax : int, optional: maximum (integer) step size in timesteps. The default is no limit.
parallel : bool, optional: whether to use the parallelized implementation. Requires rest of the code to be protected in a if name == 'main' block. The default is False.
cores : int, optional: the number of cores to use when using the parallelized implementation. When parallel=False this option is ignored

Returns

binedges : numpy.array: edges of time bins
bincounts : numpy.array: number of sampling points for each bin
binmeans : numpy.array: mean square displacement values

def mean_square_displacement_legacy(features, pos_cols=['x', 'y', 'z'], t_col='t (s)', nparticles=None, pickrandom=False, nbins=20, tmin=None, tmax=None, itmin=1, itmax=None, parallel=False, cores=None)

calculate the mean square displacement vs time for linked particles

Parameters

features : pandas.DataFrame: output from trackpy.link containing tracking data
pos_cols : list of str, optional: names of columns to use for coordinates. The default is ['x','y','z'].
t_col : str, optional: name of column containing timestamps. The default is 't (s)'.
nparticles : int, optional: number of particles to use for calculation (useful for large datasets). The default is all particles.
pickrandom : bool, optional: whether to pick nparticles randomly or not, if False it takes the n longest tracked particles from data. The default is False.
nbins : int, optional: number of bins for output. The default is 20.
tmin : float, optional: left edge of first bin. The default is min(t_col).
tmax : float, optional
right edge of last bin, The default is max(t_col).
itmin : int, optional: minimum (integer) step size in timesteps. The default is 1.
itmax : int, optional: maximum (integer) step size in timesteps. The default is no limit.
parallel : bool, optional: whether to use the parallelized implementation. Requires rest of the code to be protected in a if name == 'main' block. The default is False.
cores : int, optional: the number of cores to use when using the parallelized implementation. When parallel=False this option is ignored

Returns

binedges : numpy.array: edges of time bins
bincounts : numpy.array: number of sampling points for each bin
binmeans : numpy.array: mean square displacement values

def mean_square_displacement_per_frame(features, pos_cols=['x', 'y'], feat_col='particle')

Calculate the mean square movement of all tracked features between subsequent frames using efficient pandas linear algebra

Parameters

features : pandas.Dataframe: dataframe containing the tracking data over timesteps indexed by frame number and containing coordinates of features.
pos_cols : list of str, optional: names of the columns containing coordinates. The default is ['x','y'].
feat_col : str: name of column containing feature identifyers. The default is 'particle'.

Returns

msd : numpy.array: averages of the squared displacements between each two steps

def multiply_intensity(data, factor, dtype=None)

For multiplying the values of a numpy array while accounting for integer overflow issues in integer datatypes. Corrected values larger than the datatype max are set to the max value.

Parameters

data : numpy.ndarray: array containing the data values
factor : float: factor to multiply data with
dtype : (numpy) datatype, optional: Datatype to scale data to. The default is the same type as the input data.

Returns

data : numpy.ndarray: data with new intensity values.

def pair_correlation_2d(features, rmin=0, rmax=10, dr=None, ndensity=None, boundary=None, column_headers=['y', 'x'], periodic_boundary=False, handle_edge=True)

calculates g(r) via a 'conventional' distance histogram method for a set of 2D coordinate sets. Edge correction is fully analytic.

Parameters

features : pandas DataFrame or numpy.ndarray: contains coordinates in (y,x)
rmin : float, optional: lower bound for the pairwise distance, left edge of 0th bin. The default is 0.
rmax : float, optional: upper bound for the pairwise distance, right edge of last bin. The default is 10.
dr : float, optional: bin width for the pairwise distance bins. The default is (rmax-rmin)/20.
ndensity : float, optional: number density of particles in sample. The default is None which computes the number density from the input data.
boundary : array-like, optional: positions of the walls that define the bounding box of the coordinates, given as (ymin,ymax,xmin,xmax). The default is the min and max values in the dataset along each dimension.
column_headers : list of string, optional: column labels which contain the coordinates to use in case features is given as a pandas.DataFrame. The default is [y','x'].
periodic_boundary : bool, optional: whether periodic boundary conditions are used. The default is False.
handle_edge : bool, optional: whether to correct for edge effects in non-periodic boundary conditions. The default is True.

Returns

edges : numpy.array: edges of the bins in r
counts : numpy.array: normalized count values in each bin of the g(r)

def pair_correlation_3d(features, rmin=0, rmax=10, dr=None, ndensity=None, boundary=None, column_headers=['z', 'y', 'x'], periodic_boundary=False, handle_edge=True)

calculates g(r) via a 'conventional' distance histogram method for a set of 3D coordinate sets. Edge correction is fully analytic and based on refs [1] and [2].

Parameters

features : pandas DataFrame or numpy.ndarray: contains coordinates in (z,y,x)
rmin : float, optional: lower bound for the pairwise distance, left edge of 0th bin. The default is 0.
rmax : float, optional: upper bound for the pairwise distance, right edge of last bin. The default is 10.
dr : float, optional: bin width for the pairwise distance bins. The default is (rmax-rmin)/20.
ndensity : float, optional: number density of particles in sample. The default is None which computes the number density from the input data.
boundary : array-like, optional: positions of the walls that define the bounding box of the coordinates, given as (zmin,zmax,ymin,ymax,xmin,xmax). The default is the min and max values in the dataset along each dimension.
column_headers : list of string, optional: column labels which contain the coordinates to use in case features is given as a pandas.DataFrame. The default is ['z','y','x'].
periodic_boundary : bool, optional: whether periodic boundary conditions are used. The default is False.
handle_edge : bool, optional: whether to correct for edge effects in non-periodic boundary conditions. The default is True.

Returns

edges : numpy.array: edges of the bins in r
counts : numpy.array: normalized count values in each bin of the g(r)

References

[1] Markus Seserno (2014). How to calculate a three-dimensional g(r) under periodic boundary conditions. https://www.cmu.edu/biolphys/deserno/pdf/gr_periodic.pdf

[2] Kopera, B. A. F., & Retsch, M. (2018). Computing the 3D Radial Distribution Function from Particle Positions: An Advanced Analytic Approach. Analytical Chemistry, 90(23), 13909–13914. https://doi.org/10.1021/acs.analchem.8b03157

def plot_stack_histogram(images, bin_edges=range(0, 256), newfig=True, legendname=None, title='intensity histogram', **kwargs)

manually flattens list of images to list of pixel values and plots histogram. Can combine multiple calls with newfig and legendname options

Parameters

images : numpy ndarray: array containing pixel values
bin_edges : list or range, optional: edges of bins to use. The default is range(0,256).
newfig : bool, optional: Whether to open a new figure or to add to currently active figure. The default is True.
legendname : string, optional: label to use for the legend. The default is None.
title : string, optional: text to use as plot title. The default is 'intensity histogram'.

Returns

pyplot figure handle

def saveprompt(question='Save/overwrite? 1=YES, 0=NO. ')

Asks user a question (whether to save). If 1 is entered, it returns True, for any other answer it returns False

Parameters

question : string: The question to prompt the user for

Returns

save : bool: whether to save

def subtract_background(images, val=0, percentile=False)

subtract a constant value from a numpy array without going below 0

Parameters

images : numpy ndarray: images to correct.
percentile : bool, optional: Whether to give the value as a percentile of the stack rather than an absolute value to subtrackt. The default is False.
val : int or float, optional: Value or percentile to subtract. The default is 0.

Returns

images : numpy ndarray: the corrected stack.

def write_textfile(params, filename='parameters.txt')

stores parameter names and values in text file

Parameters

params : dictionary of name:value: the data to store
filename : str, optional: file name to us for saving. The default is "parameters.txt".

Returns

None.

Module `scm_confocal.util`

Functions

Parameters

Returns

Parameters

Returns

Parameters

Returns

Parameters

Returns

Parameters

Returns

See Also

Parameters

Returns

See Also

Parameters

Returns

Parameters

Returns

Parameters

Returns

Parameters

Returns

Parameters

Returns

Parameters

Returns

References

Parameters

Returns

Parameters

Returns

Parameters

Returns

Parameters

Returns