Utilities

General utilities

class celltk.utils.operation_utils.PadHelper(target, axis=None, mode='constant', **kwargs)

Pads images to be even for wavelet reconstruction. In the future, may include more generalizeable padding.

celltk.utils.operation_utils.cast_sitk(image, req_type, cast_up=False)

Casts a SimpleITK image to a different pixel type.

Parameters

  • req_type (str) – Desired SimpleITK pixel type.

  • cast_up (bool, default: False) – If True, pixels can be cast to a type with higher precision (i.e. sitk.sitkInt16 -> sitk.sitkInt32)

  • image (Image) –

Return type

Image

celltk.utils.operation_utils.crop_array(array, crop_vals=None)

Crops an image to the specified dimensions.

Parameters

  • array (ndarray) –

  • crop_vals (Optional[Tuple[int]], default: None) –

Return type

ndarray

celltk.utils.operation_utils.data_from_regionprops_table(regionprops, metric, labels=None, frames=None)

Given a list of regionprops data, return data for specified metrics at specific label, frame indices

Parameters

  • regionprops (Dict[int, dict]) –

  • metric (str) –

  • labels (Optional[List[int]], default: None) –

  • frames (Optional[List[int]], default: None) –

Return type

Union[ndarray, float]

celltk.utils.operation_utils.dilate_sitk(labels, radius)

Grayscale dilation of images.

Parameters

  • labels (ndarray) –

  • radius (int) –

Return type

ndarray

celltk.utils.operation_utils.get_binary_footprint(rank=2, connectivity=1)

Wrapper for ndi.generate_binary_structure

Parameters

  • rank (int, default: 2) –

  • connectivity (int, default: 1) –

Return type

ndarray

celltk.utils.operation_utils.get_cell_index(cell_id, label_array, position_id=None, position_array=None)

Returns the index of the centroid of a specific cell.

Parameters

  • cell_id (int) –

  • label_array (ndarray) –

  • position_id (Optional[int], default: None) –

  • position_array (Optional[ndarray], default: None) –

Return type

int

celltk.utils.operation_utils.get_image_pixel_type(image)

Returns the numpy data type or SimpleITK pixel type of the input image as a string.

Parameters

image (Union[ndarray, Image]) –

Return type

str

celltk.utils.operation_utils.get_split_idxs(arrays, axis=0)
Parameters

  • arrays (Collection[ndarray]) –

  • axis (int, default: 0) –

Return type

List[int]

celltk.utils.operation_utils.gray_fill_holes(labels)

Fills holes in a non-binary image.

Parameters

labels (ndarray) –

Return type

ndarray

celltk.utils.operation_utils.label_by_parent(mask, lineage)

Replaces daughter cell labels with their parent label.

Parameters

  • mask (Mask) –

  • lineage (ndarray) –

Return type

Mask

celltk.utils.operation_utils.lineage_to_track(mask, lineage)

Given a Mask and a cell lineage, marks pixels in the Mask to create the representative Mask.

Parameters

  • mask (Mask) –

  • lineage (ndarray) –

Return type

Mask

celltk.utils.operation_utils.mask_to_seeds(mask, method='sitk', output='mask', binary=True)

Find centroid of all objects and return, either as list of points or labeled mask. If binary, all seeds are 1, otherwise, preserves labels.

Parameters

  • mask (ndarray) –

  • method (str, default: 'sitk') –

  • output (str, default: 'mask') –

  • binary (bool, default: True) –

Return type

Union[ndarray, list]

celltk.utils.operation_utils.match_labels_linear(source, dest)

Transfers labels from source to dest based on area overlap between objects

Parameters

  • source (ndarray) –

  • dest (ndarray) –

Return type

ndarray

celltk.utils.operation_utils.nan_helper_2d(arr)

Linear interpolation of nans along rows in 2D array.

Parameters

arr (ndarray) –

Return type

ndarray

celltk.utils.operation_utils.ndi_binary_fill_holes(labels, fill_border=True, kernel_radius=2, max_length=45, in_place=False)

Fills holes in a binary image. If fill border is true, uses an iterative heuristic strategy to determine if border holes belong to an object and fills them if they do.

Parameters

  • labels (ndarray) –

  • fill_border (bool, default: True) –

  • kernel_radius (int, default: 2) –

  • max_length (int, default: 45) –

  • in_place (bool, default: False) –

Return type

ndarray

celltk.utils.operation_utils.paired_dot_distance(par_xy, dau_xy)

Calculates error for normalized dot distance and error along line. Used by Tracker.detect_cell_division to evaluate possible parent, daughter combinations based on the final position of the cells.

Note

  • x, y are switched in this function relative to the image.

Parameters

  • par_xy (ndarray) –

  • dau_xy (ndarray) –

Return type

Tuple[ndarray]

celltk.utils.operation_utils.parents_from_track(track)

Returns dictionary of {daughter_id: parent_id} from the input Track.

Parameters

track (Mask) –

Return type

Dict[int, int]

celltk.utils.operation_utils.shift_array(array, shift, fill=nan)

Shifts an array and fills in the values or crops to size. See: https://stackoverflow.com/questions/30399534/

Parameters

  • array (ndarray) –

  • shift (tuple) –

  • fill (float, default: nan) –

Return type

ndarray

celltk.utils.operation_utils.sitk_binary_fill_holes(labels, fill_border=True, iterations=False, kernel_radius=4, max_length=45, in_place=True, **kwargs)

Fills holes in a binary image. If fill border is true, uses an iterative heuristic strategy to determine if border holes belong to an object and fills them if they do.

Parameters

  • labels (ndarray) –

  • fill_border (bool, default: True) –

  • iterations (Union[int, bool], default: False) –

  • kernel_radius (int, default: 4) –

  • max_length (int, default: 45) –

  • in_place (bool, default: True) –

Return type

ndarray

celltk.utils.operation_utils.skimage_level_set(shape, levelset='checkerboard', size=None, center=None)

Wrapper for levelset functions in skimage.segmentation

Params size

Refers to square_size for checkerboard or radius for disk

celltk.utils.operation_utils.sliding_window_generator(arr, overlap=0)

Creates a generator for slices from array with an arbitrary amount of overlap for successive slices.

Parameters

overlap (int, default: 0) – Number of slices to overlap in each returned array. e.g. overlap = 1: [0, 1], [1, 2], [2, 3], [3, 4], overlap = 2: [0, 1, 2], [1, 2, 3], [2, 3, 4]

Note

  • Overlaps get passed as a stack, not as separate args. i.e. if overlap = 1, image.shape = (2, h, w)

Note

  • If memory is an issue here, can probably manually count the indices and make a generator that way, but it will be much slower.

Parameters

arr (ndarray) –

Return type

Generator

celltk.utils.operation_utils.split_array(array, split_idxs, axis=0)
Parameters

  • array (ndarray) –

  • split_idxs (List[int]) –

  • axis (int, default: 0) –

Return type

List[ndarray]

celltk.utils.operation_utils.stack_pad(arrays, axis=0, pad_value=nan)

Stacks arrays along axis, padding shorter arrays with pad_value.

Parameters

  • arrays (Collection[ndarray]) –

  • axis (int, default: 0) –

  • pad_value (float, default: nan) –

Return type

ndarray

celltk.utils.operation_utils.track_to_lineage(track)

Given a set of track images, reconstruct all the cell lineages.

Parameters

track (Mask) –

Return type

ndarray

celltk.utils.operation_utils.track_to_mask(track, idx=None)

Gives Track with parent values filled in by closest neighbor.

Parameters

  • track (Mask) –

  • idx (Optional[ndarray], default: None) – locations of parent values to fill in

Return type

Mask

celltk.utils.operation_utils.voronoi_boundaries(seed, thin=False, thick=False)

Calculate voronoi boundaries for the given seed array and return as binary mask.

Parameters

  • seed (ndarray) –

  • thin (bool, default: False) –

  • thick (bool, default: False) –

Return type

ndarray

celltk.utils.operation_utils.wavelet_background_estimate(image, wavelet='db4', mode='smooth', level=None, blur=False, axes=(-2, -1))

Uses wavelet reconstruction of the image to estimate the background.

Parameters

  • image (ndarray) –

  • wavelet (str, default: 'db4') –

  • mode (str, default: 'smooth') –

  • level (Optional[int], default: None) –

  • blur (bool, default: False) –

  • axes (Tuple[int], default: (-2, -1)) –

Return type

ndarray

celltk.utils.operation_utils.wavelet_noise_estimate(image, noise_level=1, wavelet='db1', mode='smooth', level=None, thres=2, axes=(-2, -1))

Uses wavelet reconstruction of the image to estimate noise.

Parameters

  • image (ndarray) –

  • noise_level (int, default: 1) –

  • wavelet (str, default: 'db1') –

  • mode (str, default: 'smooth') –

  • level (Optional[int], default: None) –

  • thres (int, default: 2) –

  • axes (Tuple[int], default: (-2, -1)) –

Return type

ndarray

Peak finding utilities

class celltk.utils.peak_utils.PeakHelper

Helper class for getting data from traces and peak labels

amplitude(traces, labels)

Returns the maximum value in each peak for each trace. Each cell has an empty list if no peaks are labeled.

Parameters

  • traces (ndarray) – Array of shape n_cells x n_features with values to use for calculating amplitude.

  • labels (ndarray) – Array of same shape as traces with peaks labeled with unique integers in each cell trace.

Return type

List[List[float]]

Returns

List of amplitudes for each cell trace.

area_under_curve(traces, labels)
Parameters

  • traces (ndarray) –

  • labels (ndarray) –

Return type

List[List[float]]

detect_peak_tracts(traces, labels, max_gap=8)

Connects peaks that are close together into a single tract.

Parameters

  • traces (ndarray) –

  • labels (ndarray) –

  • max_gap (int, default: 8) –

Return type

ndarray

filter_peaks(traces, labels, metrics, thresholds, kwargs=[{}])
Parameters

  • traces (ndarray) –

  • labels (ndarray) –

  • metrics (Collection[str]) –

  • thresholds (Collection[float]) –

  • kwargs (Collection[dict], default: [{}]) –

Return type

ndarray

first_time(traces, labels)

Returns the first time point belonging to each peak

Parameters

  • traces (ndarray) –

  • labels (ndarray) –

Return type

List[List[float]]

last_time(traces, labels)

Returns the last time point belonging to each peak

Parameters

  • traces (ndarray) –

  • labels (ndarray) –

Return type

List[List[float]]

length(traces, labels)

Returns the length of each peak.

Parameters

  • traces (ndarray) –

  • labels (ndarray) –

Return type

List[List[int]]

Returns

max_time(traces, labels)

Returns the time that a peak reaches it’s maximum amplitude.

Parameters

  • traces (ndarray) –

  • labels (ndarray) –

Return type

List[List[float]]

nonlinearity(traces, labels)

Returns inverse of the absolute value of the Pearson’s correlation coefficient. Higher values mean the peak is less linear.

Parameters

  • traces (ndarray) –

  • labels (ndarray) –

Return type

List[List[float]]

Returns

prominence(traces, labels, tracts=[])

Returns the difference between the maximum value in a peak and the base of the peak. If tracts are provided adjusts the base of each peak in the tract to be the base of the tract.

Parameters

  • traces (ndarray) –

  • labels (ndarray) –

  • tracts (List[List[int]], default: []) –

Return type

List[List[float]]

Returns

width(traces, labels, tracts=[], relative=0.5, absolute=None)

Not yet complete.

Parameters

  • traces (ndarray) –

  • labels (ndarray) –

  • tracts (List[List[int]], default: []) –

  • relative (float, default: 0.5) –

  • absolute (Optional[float], default: None) –

Return type

List[List[float]]

Returns

celltk.utils.peak_utils.segment_peaks_agglomeration(traces, probabilities, steps=15, min_seed_prob=0.6, min_peak_prob=0.5, min_seed_length=2, **kwargs)

Returns an array with peaks incrementally counted in each trace, i.e. the labels will be [0, 0, 1, 1,…0, 2, 2, … 0, 3 ..].

Parameters

  • traces (ndarray) –

  • probabilities (ndarray) –

  • steps (int, default: 15) –

  • min_seed_prob (float, default: 0.6) –

  • min_peak_prob (float, default: 0.5) –

  • min_seed_length (int, default: 2) –

Return type

ndarray

Estimating error utilities

celltk.utils.estimator_utils.bootstrap_estimator(arr, reps=1000, ci=0.95, axis=0, ignore_nans=True, function=<function nanmean>)

Uses bootstrap resampling to estimate a confidence interval.

Parameters

  • arr (ndarray) –

  • reps (int, default: 1000) –

  • ci (float, default: 0.95) –

  • axis (int, default: 0) –

  • ignore_nans (bool, default: True) –

  • function (Callable, default: <function nanmean at 0x7fa5024f1e50>) –

Return type

Tuple[ndarray]

celltk.utils.estimator_utils.confidence_interval(arr, ci=0.95)

Calculates the confidence interval based on a t-distribution.

Note

  • Only works on axis 0 for now

Parameters

  • arr (ndarray) –

  • ci (float, default: 0.95) –

Return type

ndarray

celltk.utils.estimator_utils.fraction_of_total(arr, ignore_nans=True, axis=0)

Returns the fraction of entries that have non-zero values.

Parameters

  • arr (ndarray) –

  • ignore_nans (bool, default: True) –

  • axis (int, default: 0) –

Return type

ndarray

celltk.utils.estimator_utils.get_bootstrap_population(arr, boot_reps=1000, seed=69420, function=<function nanmean>)
Parameters

  • arr (ndarray) – response of cells in one condition, cells x response/times

  • boot_reps (int, default: 1000) – Number of bootstrap replicates

  • seed (int, default: 69420) –

  • function (Callable, default: <function nanmean at 0x7fa5024f1e50>) –

Return type

ndarray

Returns

array boot_reps x response/times

celltk.utils.estimator_utils.normal_approx(arr, ci=0.95, axis=0)

Calculates the normal error for a binomial distribution.

Parameters

  • arr (ndarray) –

  • ci (float, default: 0.95) –

  • axis (int, default: 0) –

Return type

ndarray

celltk.utils.estimator_utils.wilson_score(arr, ci=0.95, axis=0)

Calculates the Wilson score for a binomial distribution.

Parameters

  • arr (ndarray) –

  • ci (float, default: 0.95) –

  • axis (int, default: 0) –

Return type

ndarray

Filtering utilities

celltk.utils.filter_utils.any_nan(values, propagate=True, mask=None)

Masks cells that include any np.nan

Parameters

  • values (ndarray) –

  • propagate (bool, default: True) –

  • mask (Optional[ndarray], default: None) –

Return type

ndarray

celltk.utils.filter_utils.any_negative(values, ignore_nans=False, propagate=True, mask=None)

Masks cells that include any negative values

Parameters

  • values (ndarray) –

  • ignore_nans (bool, default: False) –

  • propagate (bool, default: True) –

  • mask (Optional[ndarray], default: None) –

Return type

ndarray

celltk.utils.filter_utils.inside(values, lo=-inf, hi=inf, allow_equal=True, ignore_nans=False, propagate=True, mask=None)

Masks cells with values that fall inside of the specified range

Parameters

  • values (ndarray) –

  • lo (float, default: -inf) –

  • hi (float, default: inf) –

  • allow_equal (bool, default: True) –

  • ignore_nans (bool, default: False) –

  • propagate (bool, default: True) –

  • mask (Optional[ndarray], default: None) –

Return type

ndarray

celltk.utils.filter_utils.inside_percentile(values, lo=0, hi=100, ignore_nans=False, propagate=True, mask=None)

Masks cells with values that fall inside of the specified percentile range

Parameters

  • values (ndarray) –

  • lo (float, default: 0) –

  • hi (float, default: 100) –

  • ignore_nans (bool, default: False) –

  • propagate (bool, default: True) –

  • mask (Optional[ndarray], default: None) –

Return type

ndarray

celltk.utils.filter_utils.outside(values, lo=-inf, hi=inf, allow_equal=True, ignore_nans=False, propagate=True, mask=None)

Masks cells with values that fall outside of the specified range

Parameters

  • values (ndarray) –

  • lo (float, default: -inf) –

  • hi (float, default: inf) –

  • allow_equal (bool, default: True) –

  • ignore_nans (bool, default: False) –

  • propagate (bool, default: True) –

  • mask (Optional[ndarray], default: None) –

Return type

ndarray

celltk.utils.filter_utils.outside_percentile(values, lo=0, hi=100, ignore_nans=False, propagate=True, mask=None)

Masks cells with values that fall outside of the specified percentile range

Parameters

  • values (ndarray) –

  • lo (float, default: 0) –

  • hi (float, default: 100) –

  • ignore_nans (bool, default: False) –

  • propagate (bool, default: True) –

  • mask (Optional[ndarray], default: None) –

Return type

ndarray

Metric utilities

celltk.utils.metric_utils.intensity_stdev(mask, image)

Returns standard deviation of all intensity values in region of interest.

Parameters

  • mask (ndarray) –

  • image (ndarray) –

Return type

float

celltk.utils.metric_utils.intensity_variance(mask, image)

Returns variance of all intensity values in region of interest.

Parameters

  • mask (ndarray) –

  • image (ndarray) –

Return type

float

celltk.utils.metric_utils.median_intensity(mask, image)

Returns median intensity in region of interest.

Parameters

  • mask (ndarray) –

  • image (ndarray) –

Return type

float

celltk.utils.metric_utils.predict_peaks(array, weight_path='celltk/config/upeak_example_weights.tf', segment=True, roi=(1, 2), save_path=None)

Predicts peaks in arbitrary data using UPeak.

Parameters

  • array (ndarray) – Data of shape n_samples x n_timepoints. Each sample will have peaks predicted.

  • weight_path (str, default: 'celltk/config/upeak_example_weights.tf') – Weights to use for predicting peaks. If not provided, uses default weights.

  • segment (bool, default: True) – If True, segments peaks using a watershed based algorithm and returns segmennted peaks instead of peak probabilities.

  • roi (Union[int, Tuple[int]], default: (1, 2)) – Regions of interest to return. 0 is background, 1 is slope, and 2 is plateau.

  • save_path (Optional[str], default: None) – If provided, saves the output array at the supplied path.

  • save_plot – If a string is provided, saves output figures using the given figure name. Do not provided extension in file name, figures can currently only be saved as png.

  • show_plot – If True, plot will be shown to the user.

Return type

ndarray

celltk.utils.metric_utils.total_intensity(mask, image)

Returns total intensity in region of interest.

Parameters

  • mask (ndarray) –

  • image (ndarray) –

Return type

float