Image Manipulation

starfish provides a variety of image manipulation methods that aid in the quantification of image-based transcriptomics experiments. These include Filter, which remove background fluorescence and enhance spots, LearnTransform, which learn transforms to align images across rounds and channels, ApplyTransform, which apply learned transforms to images, and finally, Segmentation, to identify the locations of cells.

Filtering

Filters can be imported using starfish.image.Filter, which registers all classes that subclass FilterAlgorithm:

from starfish.image import Filter
class starfish.image.Filter.MeanHighPass(size, is_volume=False, level_method=<Levels.CLIP: 'clip'>)

The mean high pass filter reduces low spatial frequency features by subtracting a mean filtered image from the original image. The mean filter smooths an image by replacing each pixel’s value with an average of the pixel values of the surrounding neighborhood.

The mean filter is also known as a uniform or box filter. It can also be considered as a fast approximation to a GaussianHighPass filter.

This is a pass through for the scipy.ndimage.filters.uniform_filter: https://docs.scipy.org/doc/scipy-0.19.0/reference/generated/scipy.ndimage.uniform_filter.html

Parameters
sizeUnion[Number, Tuple[Number]]

width of the kernel

is_volumebool

If True, 3d (z, y, x) volumes will be filtered, otherwise, filter 2d tiles independently.

level_methodLevels

Controls the way that data are scaled to retain skimage dtype requirements that float data fall in [0, 1]. In all modes, data below 0 are set to 0.

  • Levels.CLIP (default): data above 1 are set to 1.

  • Levels.SCALE_SATURATED_BY_IMAGE: when any data in the entire ImageStack is greater than 1, the entire ImageStack is scaled by the maximum value in the ImageStack.

  • Levels.SCALE_SATURATED_BY_CHUNK: when any data in any slice is greater than 1, each slice is scaled by the maximum value found in that slice. The slice shapes are determined by the group_by parameters.

  • Levels.SCALE_BY_IMAGE: scale the entire ImageStack by the maximum value in the ImageStack.

  • Levels.SCALE_BY_CHUNK: scale each slice by the maximum value found in that slice. The slice shapes are determined by the group_by parameters.

Methods

run(self, stack, in_place, verbose, …)

Perform filtering of an image stack

run(self, stack:starfish.core.imagestack.imagestack.ImageStack, in_place:bool=False, verbose:bool=False, n_processes:Union[int, NoneType]=None, *args) → Union[starfish.core.imagestack.imagestack.ImageStack, NoneType]

Perform filtering of an image stack

Parameters
stackImageStack

Stack to be filtered.

in_placebool

if True, process ImageStack in-place, otherwise return a new stack

verbosebool

if True, report on filtering progress (default = False)

n_processesOptional[int]

Number of parallel processes to devote to applying the filter. If None, defaults to the result of os.cpu_count(). (default None)

Returns
ImageStack :

If in-place is False, return the results of filter as a new stack. Otherwise return the original stack.

Return type

Optional[ImageStack]

class starfish.image.Filter.ClipPercentileToZero(p_min=0, p_max=100, min_coeff=1.0, max_coeff=1.0, is_volume=False, level_method=<Levels.CLIP: 'clip'>)

Image clipping filter that clips values below a minimum percentile and above a maximum percentile, and follows up by subtracting the minimum percentile value from the image.

By default, these min and max percentiles are set to 0 and 100 respectively, which will result in the filter doing nothing.

This is a wrapper for numpy.clip().

Parameters
p_minint

Values below this percentile are set to p_min, and the p_min value is subtracted from the image (default 0)

p_maxint

Values above this percentile are set to p_max (default 100)

min_coefffloat

Apply a coefficient to the minimum percentile value. (default 1.0)

max_coefffloat

Apply a coefficient to the maximum percentile value. (default 1.0)

is_volumebool

If True, 3D (z, y, x) volumes will be filtered. By default, filter 2D (y, x) tiles

level_methodLevels

Controls the way that data are scaled to retain skimage dtype requirements that float data fall in [0, 1]. In all modes, data below 0 are set to 0.

  • Levels.CLIP (default): data above 1 are set to 1.

  • Levels.SCALE_SATURATED_BY_IMAGE: when any data in the entire ImageStack is greater than 1, the entire ImageStack is scaled by the maximum value in the ImageStack.

  • Levels.SCALE_SATURATED_BY_CHUNK: when any data in any slice is greater than 1, each slice is scaled by the maximum value found in that slice. The slice shapes are determined by the group_by parameters.

  • Levels.SCALE_BY_IMAGE: scale the entire ImageStack by the maximum value in the ImageStack.

  • Levels.SCALE_BY_CHUNK: scale each slice by the maximum value found in that slice. The slice shapes are determined by the group_by parameters.

Methods

run(self, stack, in_place, verbose, …)

Perform filtering of an image stack

run(self, stack:starfish.core.imagestack.imagestack.ImageStack, in_place:bool=False, verbose:bool=False, n_processes:Union[int, NoneType]=None, *args) → Union[starfish.core.imagestack.imagestack.ImageStack, NoneType]

Perform filtering of an image stack

Parameters
stackImageStack

Stack to be filtered.

in_placebool

if True, process ImageStack in-place, otherwise return a new stack

verbosebool

if True, report on filtering progress (default = False)

n_processesOptional[int]

Number of parallel processes to devote to applying the filter. If None, defaults to the result of os.cpu_count(). (default None)

Returns
ImageStack :

If in-place is False, return the results of filter as a new stack. Otherwise return the original stack.

Return type

Optional[ImageStack]

class starfish.image.Filter.Laplace(sigma, mode='reflect', cval=0.0, is_volume=False, level_method=<Levels.CLIP: 'clip'>)

Multi-dimensional Gaussian-Laplacian filter used to enhance dots against background

This filter wraps scipy.ndimage.gaussian_laplace()

Parameters
sigmaUnion[Number, Tuple[Number]]

Standard deviation for Gaussian kernel to enhance dots.

modestr

The mode parameter determines how the input array is extended when the filter overlaps a border. By passing a sequence of modes with length equal to the number of dimensions of the input array, different modes can be specified along each axis. Default value is ‘reflect’. The valid values and their behavior is as follows:

‘reflect’ (d c b a | a b c d | d c b a) The input is extended by reflecting about the edge of the last pixel.

‘constant’ (k k k k | a b c d | k k k k) The input is extended by filling all values beyond the edge with the same constant value, defined by the cval parameter.

‘nearest’ (a a a a | a b c d | d d d d) The input is extended by replicating the last pixel.

‘mirror’ (d c b | a b c d | c b a) The input is extended by reflecting about the center of the last pixel.

‘wrap’ (a b c d | a b c d | a b c d) The input is extended by wrapping around to the opposite edge.

cvalscalar, optional

(Default 0) Value to fill past edges of input if mode is ‘constant’.

is_volume: bool

If True, 3d (z, y, x) volumes will be filtered. By default, filter 2-d (y, x) planes

level_methodLevels

Controls the way that data are scaled to retain skimage dtype requirements that float data fall in [0, 1]. In all modes, data below 0 are set to 0.

  • Levels.CLIP (default): data above 1 are set to 1.

  • Levels.SCALE_SATURATED_BY_IMAGE: when any data in the entire ImageStack is greater than 1, the entire ImageStack is scaled by the maximum value in the ImageStack.

  • Levels.SCALE_SATURATED_BY_CHUNK: when any data in any slice is greater than 1, each slice is scaled by the maximum value found in that slice. The slice shapes are determined by the group_by parameters.

  • Levels.SCALE_BY_IMAGE: scale the entire ImageStack by the maximum value in the ImageStack.

  • Levels.SCALE_BY_CHUNK: scale each slice by the maximum value found in that slice. The slice shapes are determined by the group_by parameters.

Methods

run(self, stack, in_place, verbose, …)

Perform filtering of an image stack

run(self, stack:starfish.core.imagestack.imagestack.ImageStack, in_place:bool=False, verbose:bool=False, n_processes:Union[int, NoneType]=None, *args) → Union[starfish.core.imagestack.imagestack.ImageStack, NoneType]

Perform filtering of an image stack

Parameters
stackImageStack

Stack to be filtered.

in_placebool

if True, process ImageStack in-place, otherwise return a new stack

verbosebool

if True, report on filtering progress (default = False)

n_processesOptional[int]

Number of parallel processes to devote to applying the filter. If None, defaults to the result of os.cpu_count(). (default None)

Returns
ImageStack :

If in-place is False, return the results of filter as a new stack. Otherwise return the original stack.

Return type

Optional[ImageStack]

class starfish.image.Filter.LinearUnmixing(coeff_mat, level_method=<Levels.CLIP: 'clip'>)

LinearUnmixing enables the user to correct fluorescent bleed by subtracting fractions of the intensities of other channels from each channel in the ImageStack.

Parameters
coeff_matnp.ndarray

matrix of the linear unmixing coefficients. Should take the form: B = AX, where B are the unmixed values, A is coeff_mat and X are the observed values. coeff_mat has shape (n_ch, n_ch), and poses each channel (column) as a combination of other columns (rows).

level_methodLevels

Controls the way that data are scaled to retain skimage dtype requirements that float data fall in [0, 1]. In all modes, data below 0 are set to 0.

  • Levels.CLIP (default): data above 1 are set to 1.

  • Levels.SCALE_SATURATED_BY_IMAGE: when any data in the entire ImageStack is greater than 1, the entire ImageStack is scaled by the maximum value in the ImageStack.

  • Levels.SCALE_SATURATED_BY_CHUNK: when any data in any slice is greater than 1, each slice is scaled by the maximum value found in that slice. The slice shapes are determined by the group_by parameters.

  • Levels.SCALE_BY_IMAGE: scale the entire ImageStack by the maximum value in the ImageStack.

  • Levels.SCALE_BY_CHUNK: scale each slice by the maximum value found in that slice. The slice shapes are determined by the group_by parameters.

Examples

The following example provides a coefficient matrix that corrects for spectral mixing in a 3-channel experiment. Channel 0 contains a mixture of itself plus 50% of the intensity of channel 2. Channel 1 has no mixing with other channels. Channel 3 consists of itself plus 10% of the intensity of both channels 0 and 1.

>>> import numpy as np
>>> coeff_mat = np.ndarray([
...     [1,    0,  -0.1]
...     [0,    1,  -0.1]
...     [-0.5, 0,  1   ]
... ])

The end result of this unmixing will be that 50% of channel 2 will be subtracted from channel 0, channel 1 will not be changed, and 10% of channels 0 and 1 will be subtracted from channel 2.

Methods

run(self, stack, in_place, verbose, …)

Perform filtering of an image stack

run(self, stack:starfish.core.imagestack.imagestack.ImageStack, in_place:bool=False, verbose:bool=False, n_processes:Union[int, NoneType]=None, *args) → Union[starfish.core.imagestack.imagestack.ImageStack, NoneType]

Perform filtering of an image stack

Parameters
stackImageStack

Stack to be filtered.

in_placebool

if True, process ImageStack in-place, otherwise return a new stack

verbosebool

if True, report on filtering progress (default = False)

n_processesOptional[int]

Number of parallel processes to devote to applying the filter. If None, defaults to the result of os.cpu_count(). (default None)

Returns
ImageStack :

If in-place is False, return the results of filter as a new stack. Otherwise return the original stack.

Return type

Optional[ImageStack]

class starfish.image.Filter.ElementWiseMultiply(mult_array, level_method=<Levels.CLIP: 'clip'>)

Perform element-wise multiplication on the image tensor. This is useful for performing operations such as field flatness correction

Parameters
mult_arrayxr.DataArray

the image is element-wise multiplied with this array

level_methodLevels

Controls the way that data are scaled to retain skimage dtype requirements that float data fall in [0, 1]. In all modes, data below 0 are set to 0.

  • Levels.CLIP (default): data above 1 are set to 1.

  • Levels.SCALE_SATURATED_BY_IMAGE: when any data in the entire ImageStack is greater than 1, the entire ImageStack is scaled by the maximum value in the ImageStack.

  • Levels.SCALE_BY_IMAGE: scale the entire ImageStack by the maximum value in the ImageStack.

Methods

run(self, stack, in_place, verbose, …)

Perform filtering of an image stack

run(self, stack:starfish.core.imagestack.imagestack.ImageStack, in_place:bool=False, verbose:bool=False, n_processes:Union[int, NoneType]=None, *args) → Union[starfish.core.imagestack.imagestack.ImageStack, NoneType]

Perform filtering of an image stack

Parameters
stackImageStack

Stack to be filtered.

in_placebool

if True, process ImageStack in-place, otherwise return a new stack

verbosebool

if True, report on filtering progress (default = False)

n_processesOptional[int]

Number of parallel processes to devote to applying the filter. If None, defaults to the result of os.cpu_count(). (default None)

Returns
ImageStack :

If in-place is False, return the results of filter as a new stack. Otherwise return the original stack.

Return type

Optional[ImageStack]

class starfish.image.Filter.Bandpass(lshort, llong, threshold=0, truncate=4, is_volume=False, level_method=<Levels.CLIP: 'clip'>)

Convolve with a Gaussian to remove short-wavelength noise and subtract out long-wavelength variations, retaining features of intermediate scale. This implementation relies on scipy.ndimage.filters.gaussian_filter.

This method is a thin wrapper around trackpy.Bandpass:

http://soft-matter.github.io/trackpy/v0.3.0/generated/trackpy.bandpass.html

Parameters
lshortfloat

filter frequencies below this value

llongint

filter frequencies above this odd integer value

thresholdfloat

zero any spots below this intensity value after background subtraction (default 0)

truncatefloat

truncate the gaussian kernel, used by the gaussian filter, at this many standard deviations (default 4)

is_volumebool

If True, 3d (z, y, x) volumes will be filtered. By default, filter 2-d (y, x) planes

level_methodLevels

Controls the way that data are scaled to retain skimage dtype requirements that float data fall in [0, 1]. In all modes, data below 0 are set to 0.

  • Levels.CLIP (default): data above 1 are set to 1.

  • Levels.SCALE_SATURATED_BY_IMAGE: when any data in the entire ImageStack is greater than 1, the entire ImageStack is scaled by the maximum value in the ImageStack.

  • Levels.SCALE_SATURATED_BY_CHUNK: when any data in any slice is greater than 1, each slice is scaled by the maximum value found in that slice. The slice shapes are determined by the group_by parameters.

  • Levels.SCALE_BY_IMAGE: scale the entire ImageStack by the maximum value in the ImageStack.

  • Levels.SCALE_BY_CHUNK: scale each slice by the maximum value found in that slice. The slice shapes are determined by the group_by parameters.

Methods

run(self, stack, in_place, verbose, …)

Perform filtering of an image stack

run(self, stack:starfish.core.imagestack.imagestack.ImageStack, in_place:bool=False, verbose:bool=False, n_processes:Union[int, NoneType]=None, *args) → Union[starfish.core.imagestack.imagestack.ImageStack, NoneType]

Perform filtering of an image stack

Parameters
stackImageStack

Stack to be filtered.

in_placebool

if True, process ImageStack in-place, otherwise return a new stack

verbosebool

if True, report on filtering progress (default = False)

n_processesOptional[int]

Number of parallel processes to devote to applying the filter. If None, defaults to the result of os.cpu_count(). (default None)

Returns
ImageStack :

If in-place is False, return the results of filter as a new stack. Otherwise return the original stack.

Return type

Optional[ImageStack]

class starfish.image.Filter.WhiteTophat(masking_radius, is_volume=False, level_method=<Levels.CLIP: 'clip'>)

Performs “white top hat” filtering of an image to enhance spots. White top hat filtering finds spots that are both smaller and brighter than their surroundings by subtracting an estimate of the background produced by a binary opening of the image using a disk-shaped structuring element.

Parameters
masking_radiusint

radius of the morphological masking structure in pixels

is_volumeint

If True, 3d (z, y, x) volumes will be filtered, otherwise, filter 2d tiles independently.

clip_methodOptional[Union[str, Clip]]

Deprecated method to control the way that data are scaled to retain skimage dtype requirements that float data fall in [0, 1]. In all modes, data below 0 are set to 0.

  • Clip.CLIP: data above 1 are set to 1. This has been replaced with level_method=Levels.CLIP.

  • Clip.SCALE_BY_IMAGE: when any data in the entire ImageStack is greater than 1, the entire ImageStack is scaled by the maximum value in the ImageStack. This has been replaced with level_method=Levels.SCALE_SATURATED_BY_IMAGE.

  • Clip.SCALE_BY_CHUNK: when any data in any slice is greater than 1, each slice is scaled by the maximum value found in that slice. The slice shapes are determined by the group_by parameters. This has been replaced with level_method=Levels.SCALE_SATURATED_BY_CHUNK.

level_methodLevels

Controls the way that data are scaled to retain skimage dtype requirements that float data fall in [0, 1]. In all modes, data below 0 are set to 0.

  • Levels.CLIP (default): data above 1 are set to 1.

  • Levels.SCALE_SATURATED_BY_IMAGE: when any data in the entire ImageStack is greater than 1, the entire ImageStack is scaled by the maximum value in the ImageStack.

  • Levels.SCALE_SATURATED_BY_CHUNK: when any data in any slice is greater than 1, each slice is scaled by the maximum value found in that slice. The slice shapes are determined by the group_by parameters.

  • Levels.SCALE_BY_IMAGE: scale the entire ImageStack by the maximum value in the ImageStack.

  • Levels.SCALE_BY_CHUNK: scale each slice by the maximum value found in that slice. The slice shapes are determined by the group_by parameters.

Notes

See https://en.wikipedia.org/wiki/Top-hat_transform for more information

Methods

run(self, stack, in_place, verbose, …)

Perform filtering of an image stack

run(self, stack:starfish.core.imagestack.imagestack.ImageStack, in_place:bool=False, verbose:bool=False, n_processes:Union[int, NoneType]=None, *args) → Union[starfish.core.imagestack.imagestack.ImageStack, NoneType]

Perform filtering of an image stack

Parameters
stackImageStack

Stack to be filtered.

in_placebool

if True, process ImageStack in-place, otherwise return a new stack

verbosebool

If True, report on the percentage completed (default = False) during processing

n_processesOptional[int]

Number of parallel processes to devote to applying the filter. If None, defaults to the result of os.cpu_count(). (default None)

Returns
ImageStack :

If in-place is False, return the results of filter as a new stack. Otherwise return the original stack.

Return type

Optional[ImageStack]

class starfish.image.Filter.ClipValueToZero(v_min=0.0, v_max=None, is_volume=False, level_method=<Levels.CLIP: 'clip'>)

Image clipping filter that clips values below a minimum value and above a maximum value. The filter then subtracts the minimum value from the clipped image.

By default, the min and max values are set to 0.0 and None respectively, which will result in the filter doing nothing.

This is a wrapper for numpy.clip().

Parameters
v_minfloat

Values below v_min are set to v_min. v_min is then subtracted from the entire image (default 0)

v_maxOptional[Number]

Values above v_max are set to v_max (default None)

is_volumebool

If True, 3d (z, y, x) volumes will be filtered. By default, filter 2D (y, x) tiles

level_methodLevels

Controls the way that data are scaled to retain skimage dtype requirements that float data fall in [0, 1]. In all modes, data below 0 are set to 0.

  • Levels.CLIP (default): data above 1 are set to 1.

  • Levels.SCALE_SATURATED_BY_IMAGE: when any data in the entire ImageStack is greater than 1, the entire ImageStack is scaled by the maximum value in the ImageStack.

  • Levels.SCALE_SATURATED_BY_CHUNK: when any data in any slice is greater than 1, each slice is scaled by the maximum value found in that slice. The slice shapes are determined by the group_by parameters.

  • Levels.SCALE_BY_IMAGE: scale the entire ImageStack by the maximum value in the ImageStack.

  • Levels.SCALE_BY_CHUNK: scale each slice by the maximum value found in that slice. The slice shapes are determined by the group_by parameters.

Methods

run(self, stack, in_place, verbose, …)

Perform filtering of an image stack

run(self, stack:starfish.core.imagestack.imagestack.ImageStack, in_place:bool=False, verbose:bool=False, n_processes:Union[int, NoneType]=None, *args) → Union[starfish.core.imagestack.imagestack.ImageStack, NoneType]

Perform filtering of an image stack

Parameters
stackImageStack

Stack to be filtered.

in_placebool

if True, process ImageStack in-place, otherwise return a new stack

verbosebool

if True, report on filtering progress (default = False)

n_processesOptional[int]

Number of parallel processes to devote to applying the filter. If None, defaults to the result of os.cpu_count(). (default None)

Returns
ImageStack :

If in-place is False, return the results of filter as a new stack. Otherwise return the original stack.

Return type

Optional[ImageStack]

class starfish.image.Filter.GaussianLowPass(sigma, is_volume=False, level_method=<Levels.CLIP: 'clip'>)

Multi-dimensional low-pass gaussian filter. This filter blurs image data, and can be useful to apply prior to pixel decoding or watershed segmentation to spread intensity across neighboring pixels, accounting for noise that the algorithms are sensitive to.

This is a thin wrapper around skimage.filters.Gaussian()

Parameters
sigmaUnion[Number, Tuple[Number]]

Standard deviation for Gaussian kernel.

is_volumebool

If True, 3d (z, y, x) volumes will be filtered, otherwise, filter 2d tiles independently.

level_methodLevels

Controls the way that data are scaled to retain skimage dtype requirements that float data fall in [0, 1]. In all modes, data below 0 are set to 0.

  • Levels.CLIP (default): data above 1 are set to 1.

  • Levels.SCALE_SATURATED_BY_IMAGE: when any data in the entire ImageStack is greater than 1, the entire ImageStack is scaled by the maximum value in the ImageStack.

  • Levels.SCALE_SATURATED_BY_CHUNK: when any data in any slice is greater than 1, each slice is scaled by the maximum value found in that slice. The slice shapes are determined by the group_by parameters.

  • Levels.SCALE_BY_IMAGE: scale the entire ImageStack by the maximum value in the ImageStack.

  • Levels.SCALE_BY_CHUNK: scale each slice by the maximum value found in that slice. The slice shapes are determined by the group_by parameters.

Methods

run(self, stack, in_place, verbose, …)

Perform filtering of an image stack

run(self, stack:starfish.core.imagestack.imagestack.ImageStack, in_place:bool=False, verbose:bool=False, n_processes:Union[int, NoneType]=None, *args) → Union[starfish.core.imagestack.imagestack.ImageStack, NoneType]

Perform filtering of an image stack

Parameters
stackImageStack

Stack to be filtered.

in_placebool

if True, process ImageStack in-place, otherwise return a new stack (default False)

verbosebool

if True, report on filtering progress (default False)

n_processesOptional[int]

Number of parallel processes to devote to applying the filter. If None, defaults to the result of os.cpu_count(). (default None)

Returns
ImageStack :

If in-place is False, return the results of filter as a new stack. Otherwise return the original stack.

Return type

Optional[ImageStack]

class starfish.image.Filter.IlastikPretrainedProbability(ilastik_executable, ilastik_project)

Use an existing ilastik pixel classifier to generate a probability image for a dapi image. NOTE: This api may not be used without a downloaded and installed version of Ilastik. Visit https://www.ilastik.org/download.html to download.

Parameters
ilastik_executable: Union[Path, str]

Path to run_ilastik.sh needed for running ilastik in headless mode. Typically the script is located: “/Applications/{ILASTIK_VERSION}/Contents/ilastik-release/run_ilastik.sh”

ilastik_project: Union[Path, str]

path to ilastik project .ilp file

Methods

import_ilastik_probabilities(…)

Import cell probabilities provided by ilastik as an ImageStack.

run(self, stack, in_place, verbose, …)

Use a pre trained probability pixel classification model to generate probabilites for a dapi image

classmethod import_ilastik_probabilities(path_to_h5_file:Union[str, pathlib.Path]) → starfish.core.imagestack.imagestack.ImageStack

Import cell probabilities provided by ilastik as an ImageStack.

Parameters
path_to_h5_fileUnion[str, Path]

Path to the .h5 file outputted by ilastik

Returns
ImageStack :

A new ImageStack created from the cell probabilities provided by ilastik.

Return type

ImageStack

run(self, stack:starfish.core.imagestack.imagestack.ImageStack, in_place:bool=False, verbose:bool=False, n_processes:Union[int, NoneType]=None, *args) → Union[starfish.core.imagestack.imagestack.ImageStack, NoneType]

Use a pre trained probability pixel classification model to generate probabilites for a dapi image

Parameters
stackImageStack

Dapi image to be run through ilastik.

in_placebool

This parameter is ignored for this filter.

verbosebool

This parameter is ignored for this filter.

n_processesOptional[int]

This parameter is ignored for this filter.

Returns
ImageStack :

A new ImageStack created from the cell probabilities provided by ilastik.

Return type

Optional[ImageStack]

class starfish.image.Filter.Map(func, *func_args, module=None, in_place=False, group_by=None, level_method=<Levels.CLIP: 'clip'>, **func_kwargs)

Map from input to output by applying a specified function to the input. The output must have the same shape as the input.

Parameters
funcUnion[str, FunctionSourceBundle]

Function to apply across the dimension(s) specified by dims.

If this value is a string, then the module parameter is consulted to determine which python package is used to find the function. If module is not specified, then the default is FunctionSource.np.

If this value is a FunctionSourceBundle, then the python package and module name is obtained from the bundle.

moduleOptional[FunctionSource]

Python module that serves as the source of the function. It must be listed as one of the members of FunctionSource.

Currently, the supported FunctionSources are: - np: the top-level package of numpy - scipy: the top-level package of scipy

This is being deprecated in favor of specifying the function as a FunctionSourceBundle.

in_placebool

Execute the operation in-place. (default: False)

group_bySet[Axes]

Axes to split the data along. For example, splitting a 2D array (axes: X, Y; size: 3, 4) by X results in 3 calls to the method, each with arrays of size 4. (default {Axes.ROUND, Axes.CH, Axes.ZPLANE})

level_methodLevels

Controls the way that data are scaled to retain skimage dtype requirements that float data fall in [0, 1]. In all modes, data below 0 are set to 0.

  • Levels.CLIP (default): data above 1 are set to 1.

  • Levels.SCALE_SATURATED_BY_IMAGE: when any data in the entire ImageStack is greater than 1, the entire ImageStack is scaled by the maximum value in the ImageStack.

  • Levels.SCALE_SATURATED_BY_CHUNK: when any data in any slice is greater than 1, each slice is scaled by the maximum value found in that slice. The slice shapes are determined by the group_by parameters.

  • Levels.SCALE_BY_IMAGE: scale the entire ImageStack by the maximum value in the ImageStack.

  • Levels.SCALE_BY_CHUNK: scale each slice by the maximum value found in that slice. The slice shapes are determined by the group_by parameters.

Examples

Applying a divide function.
>>> from starfish.core.imagestack.test.factories.synthetic_stack import synthetic_stack
>>> from starfish.image import Filter
>>> from starfish.types import Axes
>>> stack = synthetic_stack()
>>> divider = Filter.Map("divide", 4)
>>> by_four = divider.run(stack)

Methods

run(self, stack, \*args)

Map from input to output by applying a specified function to the input.

run(self, stack:starfish.core.imagestack.imagestack.ImageStack, *args) → Union[starfish.core.imagestack.imagestack.ImageStack, NoneType]

Map from input to output by applying a specified function to the input.

Parameters
stackImageStack

Stack to be filtered.

Returns
Optional[ImageStack] :

If in-place is False, return the results of filter as a new stack. Otherwise return None

Return type

Optional[ImageStack]

class starfish.image.Filter.Clip(p_min=0, p_max=100, is_volume=False, expand_dynamic_range=None, level_method=None)

Image clipping filter that clips values below a minimum percentile and above a maximum percentile.

By default, these min and max percentiles are set to 0 and 100 respectively, which will result in the filter doing nothing.

This is a wrapper for numpy.clip() that can optionally linearly expand the dynamic range of the data to extend from [0, 1]

Parameters
p_minint

values below this percentile are set to p_min (default 0)

p_maxint

values above this percentile are set to p_max (default 100)

is_volumebool

If True, 3d (z, y, x) volumes will be filtered. By default, filter 2-d (y, x) tiles

expand_dynamic_rangebool

If True, linearly expand intensity values to fill [0, 1] after clipping. This has been deprecated in favor of the level_method argument. If expand_dynamic_range is True and level_method is provided, an error is raised. If expand_dynamic_range is True and level_method is not provided, it is interpreted as level_method=Levels.SCALE_BY_CHUNK. If expand_dynamic_range is False or not provided and level_method is provided, level_method is used. If neither is provided, it is interpreted as level_method=Levels.CLIP. (default False)

level_methodLevels

Controls the way that data are scaled to retain skimage dtype requirements that float data fall in [0, 1]. In all modes, data below 0 are set to 0.

  • Levels.CLIP (default): data above 1 are set to 1.

  • Levels.SCALE_SATURATED_BY_IMAGE: when any data in the entire ImageStack is greater than 1, the entire ImageStack is scaled by the maximum value in the ImageStack.

  • Levels.SCALE_SATURATED_BY_CHUNK: when any data in any slice is greater than 1, each slice is scaled by the maximum value found in that slice. The slice shapes are determined by the group_by parameters.

  • Levels.SCALE_BY_IMAGE: scale the entire ImageStack by the maximum value in the ImageStack.

  • Levels.SCALE_BY_CHUNK: scale each slice by the maximum value found in that slice. The slice shapes are determined by the group_by parameters.

Methods

run(self, stack, in_place, verbose, …)

Perform filtering of an image stack

run(self, stack:starfish.core.imagestack.imagestack.ImageStack, in_place:bool=False, verbose:bool=False, n_processes:Union[int, NoneType]=None, *args) → Union[starfish.core.imagestack.imagestack.ImageStack, NoneType]

Perform filtering of an image stack

Parameters
stackImageStack

Stack to be filtered.

in_placebool

if True, process ImageStack in-place, otherwise return a new stack

verbosebool

if True, report on filtering progress (default = False)

n_processesOptional[int]

Number of parallel processes to devote to applying the filter. If None, defaults to the result of os.cpu_count(). (default None)

Returns
ImageStack :

If in-place is False, return the results of filter as a new stack. Otherwise return the original stack.

Return type

Optional[ImageStack]

class starfish.image.Filter.Reduce(dims, func='max', module=None, level_method=<Levels.CLIP: 'clip'>, **kwargs)

Reduces the cardinality of one or more axes to 1 by applying a function across those axes.

Parameters
dimsIterable[Union[Axes, str]]

one or more Axes to reduce over

funcUnion[str, FunctionSourceBundle]

Function to apply across the dimension(s) specified by dims.

If this value is a string, then the module parameter is consulted to determine which python package is used to find the function. If module is not specified, then the default is FunctionSource.np.

If this value is a FunctionSourceBundle, then the python package and module name is obtained from the bundle.

Some common examples for the np FunctionSource:

  • amax: maximum intensity projection (applies np.amax)

  • max: maximum intensity projection (this is an alias for amax and applies np.amax)

  • mean: take the mean across the dim(s) (applies np.mean)

  • sum: sum across the dim(s) (applies np.sum)

moduleOptional[FunctionSource]

Python module that serves as the source of the function. It must be listed as one of the members of FunctionSource.

Currently, the supported FunctionSources are: - np: the top-level package of numpy - scipy: the top-level package of scipy

This is being deprecated in favor of specifying the function as a FunctionSourceBundle.

clip_methodOptional[Union[str, Clip]]

Deprecated method to control the way that data are scaled to retain skimage dtype requirements that float data fall in [0, 1]. In all modes, data below 0 are set to 0.

  • Clip.CLIP: data above 1 are set to 1. This has been replaced with level_method=Levels.CLIP.

  • Clip.SCALE_BY_IMAGE: when any data in the entire ImageStack is greater than 1, the entire ImageStack is scaled by the maximum value in the ImageStack. This has been replaced with level_method=Levels.SCALE_SATURATED_BY_IMAGE.

  • Clip.SCALE_BY_CHUNK: when any data in any slice is greater than 1, each slice is scaled by the maximum value found in that slice. The slice shapes are determined by the group_by parameters. This has been replaced with level_method=Levels.SCALE_SATURATED_BY_CHUNK.

level_methodLevels

Controls the way that data are scaled to retain skimage dtype requirements that float data fall in [0, 1]. In all modes, data below 0 are set to 0.

  • Levels.CLIP (default): data above 1 are set to 1.

  • Levels.SCALE_SATURATED_BY_IMAGE: when any data in the entire ImageStack is greater than 1, the entire ImageStack is scaled by the maximum value in the ImageStack.

  • Levels.SCALE_SATURATED_BY_CHUNK: when any data in any slice is greater than 1, each slice is scaled by the maximum value found in that slice. The slice shapes are determined by the group_by parameters.

  • Levels.SCALE_BY_IMAGE: scale the entire ImageStack by the maximum value in the ImageStack.

  • Levels.SCALE_BY_CHUNK: scale each slice by the maximum value found in that slice. The slice shapes are determined by the group_by parameters.

Examples

Reducing via max projection.
>>> from starfish.core.imagestack.test.factories.synthetic_stack import synthetic_stack
>>> from starfish.image import Filter
>>> from starfish.types import Axes
>>> stack = synthetic_stack()
>>> reducer = Filter.Reduce({Axes.ROUND}, func="max")
>>> max_proj = reducer.run(stack)
Reducing via linalg.norm
>>> from starfish.core.imagestack.test.factories.synthetic_stack import synthetic_stack
>>> from starfish.image import Filter
>>> from starfish.types import Axes, FunctionSource
>>> stack = synthetic_stack()
>>> reducer = Filter.Reduce(
        {Axes.ROUND},
        func=FunctionSource.scipy("linalg.norm"),
        ord=2,
    )
>>> norm = reducer.run(stack)

Methods

run(self, stack, \*args)

Performs the dimension reduction with the specifed function

run(self, stack:starfish.core.imagestack.imagestack.ImageStack, *args) → starfish.core.imagestack.imagestack.ImageStack

Performs the dimension reduction with the specifed function

Parameters
stackImageStack

Stack to be filtered.

Returns
ImageStack :

Return the results of filter as a new stack.

Return type

ImageStack

class starfish.image.Filter.GaussianHighPass(sigma, is_volume=False, level_method=<Levels.CLIP: 'clip'>)

Applies a Gaussian high pass filter to the ImageStack. This is useful to remove cellular autofluorescence, which is typically low frequency.

This filter works by subtracting a Gaussian low pass filter filtered version of the input image from the input image itself. The Gaussian low pass filter is defined in scipy.ndimage() and used by skimage.filters.gaussian().

Parameters
sigmaUnion[Number, Tuple[Number]]

standard deviation of gaussian kernel

is_volumebool

If True, 3d (z, y, x) volumes will be filtered, otherwise, filter 2d tiles independently.

level_methodLevels

Controls the way that data are scaled to retain skimage dtype requirements that float data fall in [0, 1]. In all modes, data below 0 are set to 0.

  • Levels.CLIP (default): data above 1 are set to 1.

  • Levels.SCALE_SATURATED_BY_IMAGE: when any data in the entire ImageStack is greater than 1, the entire ImageStack is scaled by the maximum value in the ImageStack.

  • Levels.SCALE_SATURATED_BY_CHUNK: when any data in any slice is greater than 1, each slice is scaled by the maximum value found in that slice. The slice shapes are determined by the group_by parameters.

  • Levels.SCALE_BY_IMAGE: scale the entire ImageStack by the maximum value in the ImageStack.

  • Levels.SCALE_BY_CHUNK: scale each slice by the maximum value found in that slice. The slice shapes are determined by the group_by parameters.

Methods

run(self, stack, in_place, verbose, …)

Perform filtering of an image stack

run(self, stack:starfish.core.imagestack.imagestack.ImageStack, in_place:bool=False, verbose:bool=False, n_processes:Union[int, NoneType]=None, *args) → Union[starfish.core.imagestack.imagestack.ImageStack, NoneType]

Perform filtering of an image stack

Parameters
stackImageStack

Stack to be filtered.

in_placebool

if True, process ImageStack in-place, otherwise return a new stack

verbosebool

if True, report on filtering progress (default = False)

n_processesOptional[int]

Number of parallel processes to devote to applying the filter. If None, defaults to the result of os.cpu_count(). (default None)

Returns
ImageStack :

If in-place is False, return the results of filter as a new stack. Otherwise return the original stack.

Return type

Optional[ImageStack]

class starfish.image.Filter.DeconvolvePSF(num_iter, sigma, is_volume=False, level_method=<Levels.CLIP: 'clip'>)

Deconvolve a point spread function from the image. The point spread function is assumed to be an isotropic Gaussian, with a user specified standard deviation, sigma.

There are currently several issues with this function. See https://github.com/spacetx/starfish/issues/731

Parameters
num_iterint

number of iterations to run. Note that this is a very important parameter that requires careful optimization

sigmaNumber

standard deviation of the gaussian kernel used to construct the point spread function

is_volume: bool

If True, 3d (z, y, x) volumes will be filtered, otherwise, filter 2d tiles independently.

clip_methodOptional[Union[str, Clip]]

Deprecated method to control the way that data are scaled to retain skimage dtype requirements that float data fall in [0, 1]. In all modes, data below 0 are set to 0.

  • Clip.CLIP: data above 1 are set to 1. This has been replaced with level_method=Levels.CLIP.

  • Clip.SCALE_BY_IMAGE: when any data in the entire ImageStack is greater than 1, the entire ImageStack is scaled by the maximum value in the ImageStack. This has been replaced with level_method=Levels.SCALE_SATURATED_BY_IMAGE.

  • Clip.SCALE_BY_CHUNK: when any data in any slice is greater than 1, each slice is scaled by the maximum value found in that slice. The slice shapes are determined by the group_by parameters. This has been replaced with level_method=Levels.SCALE_SATURATED_BY_CHUNK.

level_methodLevels

Controls the way that data are scaled to retain skimage dtype requirements that float data fall in [0, 1]. In all modes, data below 0 are set to 0.

  • Levels.CLIP (default): data above 1 are set to 1.

  • Levels.SCALE_SATURATED_BY_IMAGE: when any data in the entire ImageStack is greater than 1, the entire ImageStack is scaled by the maximum value in the ImageStack.

  • Levels.SCALE_SATURATED_BY_CHUNK: when any data in any slice is greater than 1, each slice is scaled by the maximum value found in that slice. The slice shapes are determined by the group_by parameters.

  • Levels.SCALE_BY_IMAGE: scale the entire ImageStack by the maximum value in the ImageStack.

  • Levels.SCALE_BY_CHUNK: scale each slice by the maximum value found in that slice. The slice shapes are determined by the group_by parameters.

Notes

This code is based on code from skimage.restoration. We modified it to implement a bugfix wherein zeros in the input image or zeros produced during an intermediate would induce divide by zero -> Nan. These Nans would then propagate throughout the image, invalidating the results. Longer term, we will make a PR to skimage to introduce the fix. There is some existing work linked here: https://github.com/scikit-image/scikit-image/issues/2551

References

Rbe0d1efded04-1

http://en.wikipedia.org/wiki/Richardson%E2%80%93Lucy_deconvolution

Examples

>>> from skimage import color, data, restoration
>>> camera = color.rgb2gray(data.camera())
>>> from scipy.signal import convolve2d
>>> psf = np.ones((5, 5)) / 25
>>> camera = convolve2d(camera, psf, 'same')
>>> camera += 0.1 * camera.std() * np.random.standard_normal(camera.shape)
>>> deconvolved = restoration.richardson_lucy(camera, psf, 5)

Methods

run(self, stack, in_place[, verbose])

Perform filtering of an image stack

run(self, stack:starfish.core.imagestack.imagestack.ImageStack, in_place:bool=False, verbose=False, n_processes:Union[int, NoneType]=None, *args) → Union[starfish.core.imagestack.imagestack.ImageStack, NoneType]

Perform filtering of an image stack

Parameters
stackImageStack

Stack to be filtered.

in_placebool

if True, process ImageStack in-place, otherwise return a new stack

verbosebool

if True, report on the percentage completed during processing (default = False)

n_processesOptional[int]

Number of parallel processes to devote to applying the filter. If None, defaults to the result of os.cpu_count(). (default None)

Returns
ImageStack :

If in-place is False, return the results of filter as a new stack. Otherwise return the original stack.

Return type

Optional[ImageStack]

class starfish.image.Filter.MatchHistograms(group_by)

Normalize data by matching distributions of each tile or volume to a reference volume

Chunks sharing the same values for axes specified by group_by will be quantile normalized such that their intensity values are identically distributed. The reference distribution is calculated by sorting the intensities in each chunk and averaging across chunks.

For example, if group_by={Axes.CH, Axes.ROUND} each (z, y, x) volume will be linearized, the intensities will be sorted, and averaged across {Axes.CH, Axes.ROUND}, normalizing the intensity distribution of each (round, channel) volume.

Setting group_by={Axes.CH} would carry out the same approach, but the result would equalize distribution across channels only and would retain variability across rounds.

Parameters
group_bySet[Axes]

The Axes to group by.

Methods

run(self, stack, in_place, verbose, …)

Perform filtering of an image stack

run(self, stack:starfish.core.imagestack.imagestack.ImageStack, in_place:bool=False, verbose:bool=False, n_processes:Union[int, NoneType]=None, *args) → Union[starfish.core.imagestack.imagestack.ImageStack, NoneType]

Perform filtering of an image stack

Parameters
stackImageStack

Stack to be filtered.

in_placebool

if True, process ImageStack in-place, otherwise return a new stack

verbosebool

if True, report on filtering progress (default = False)

n_processesOptional[int]

Number of parallel processes to devote to applying the filter. If None, defaults to the result of os.cpu_count(). (default None)

Returns
ImageStack :

If in-place is False, return the results of filter as a new stack. Otherwise return the original stack.

Return type

Optional[ImageStack]

class starfish.image.Filter.ZeroByChannelMagnitude(thresh, normalize)

For assays in which we expect codewords to have explicit zero values, e.g., DARTFISH, this filter allows for the explicit zeroing out of pixels, for each round, where there is insufficient signal magnitude across channels.

Parameters
threshint

pixels in each round that have a L2 norm across channels below this threshold are set to 0

normalizebool

if True, this scales all rounds to have unit L2 norm across channels

Methods

run(self, stack, in_place[, verbose])

Perform filtering of an image stack

run(self, stack:starfish.core.imagestack.imagestack.ImageStack, in_place:bool=False, verbose=False, n_processes:Union[int, NoneType]=None, *args) → Union[starfish.core.imagestack.imagestack.ImageStack, NoneType]

Perform filtering of an image stack

Parameters
stackImageStack

Stack to be filtered.

in_placebool

if True, process ImageStack in-place, otherwise return a new stack

verbosebool

if True, report on the percentage completed during processing (default = False)

n_processesOptional[int]: None

Not implemented. Number of processes to use when applying filter.

Returns
ImageStack :

If in-place is False, return the results of filter as a new stack. Otherwise return the original stack.

Return type

Optional[ImageStack]

Learn Transform

LearnTransform can be imported using starfish.image.LearnTransform, the subclasses of LearnTransformAlgorithm are available for transform learning.

from starfish.image import LearnTransform
class starfish.image.LearnTransform.Translation(reference_stack, axes, upsampling=1)

Iterate over the given axes of an ImageStack and learn the translation transform based off the reference_stack passed into Translation’s constructor. Only supports 2d data.

Parameters
axesAxes

The axes {r, ch, zplane} to iterate over

reference_stackImageStack

The target image used in skimage.feature.register_translation()

upsamplingint

upsampling factor (default=1). See http://scikit-image.org/docs/dev/api/skimage.feature.html#skimage.feature.register_translation for an explanation of this parameter. in brief, this parameter determines the resolution of the registration. A value of 1 represents pixel resolution, a value of 10 is 1/10th of a pixel, a value of 300 is 1/300th of a pixel, and so on.

Methods

run(self, stack, verbose, \*args)

Iterate over the given axes of an ImageStack and learn the translation transform based off the reference_stack passed into Translation’s constructor.

run(self, stack:starfish.core.imagestack.imagestack.ImageStack, verbose:bool=False, *args) → starfish.core.image._registration.transforms_list.TransformsList

Iterate over the given axes of an ImageStack and learn the translation transform based off the reference_stack passed into Translation’s constructor. Only supports 2d data.

Parameters
stackImageStack

Stack to calculate the transforms on.

verbosebool

if True, report on transformation progress (default = False)

Returns
List[Tuple[Mapping[Axes, int], SimilarityTransform]] :

A list of tuples containing axes of the Imagestack and associated transform to apply.

Return type

TransformsList

Apply Transform

ApplyTransform can be imported using starfish.image.ApplyTransform, the subclasses of ApplyTransformAlgorithm are available for transform learning.

from starfish.image import ApplyTransform
class starfish.image.ApplyTransform.Warp

Applies a list of geometric transformations to an ImageStack using :py:func:skimage.transform.warp

Parameters
stackImageStack

Stack to be transformed.

transforms_listTransformsList

The list of skimage transform objects to apply to the ImageStack. See a list of valid transform objects at https://scikit-image.org/docs/dev/api/skimage.transform.html

in_placebool

if True, process ImageStack in-place and return None, otherwise return a new stack

verbosebool

if True, report on transformation progress (default = False)

Returns
ImageStack :

If in_place is False, return the results of the transforms as a new stack. Otherwise return the original stack.

Methods

run(self, stack, transforms_list, in_place, …)

Performs registration on the stack provided.

run(self, stack:starfish.core.imagestack.imagestack.ImageStack, transforms_list:starfish.core.image._registration.transforms_list.TransformsList, in_place:bool=False, verbose:bool=False, *args, **kwargs) → Union[starfish.core.imagestack.imagestack.ImageStack, NoneType]

Performs registration on the stack provided.

Return type

Optional[ImageStack]

Segmentation

Segmentation can be imported using starfish.image.Segment, which registers all classes that subclass SegmentAlgorithm:

from starfish.image import Segment
class starfish.image.Segment.Watershed(nuclei_threshold, input_threshold, min_distance)

Implements watershed segmentation of cells.

Algorithm is seeded by nuclei image. Binary segmentation mask is computed from a maximum projection of spots across C and R, which is subsequently thresholded.

This function wraps skimage.morphology.watershed()

Parameters
nuclei_thresholdNumber

threshold to apply to nuclei image

input_thresholdNumber

threshold to apply to stain image

min_distanceint

minimum distance before object centers in a provided nuclei image are considered single nuclei

Notes

Watershed: http://scikit-image.org/docs/dev/auto_examples/segmentation/plot_watershed.html

Methods

run(self, primary_images, nuclei, \*args)

Segments nuclei in 2-d using a nuclei ImageStack

show

run(self, primary_images:starfish.core.imagestack.imagestack.ImageStack, nuclei:starfish.core.imagestack.imagestack.ImageStack, *args) → starfish.core.morphology.binary_mask.binary_mask.BinaryMaskCollection

Segments nuclei in 2-d using a nuclei ImageStack

Primary images are used to expand the nuclear mask, but only in cases where there are densely detected points surrounding the nuclei.

Parameters
primary_imagesImageStack

contains primary image data

nucleiImageStack

contains nuclei image data

Returns
masksBinaryMaskCollection

binary masks segmenting each cell

Return type

BinaryMaskCollection