Morphology Transformations

starfish provides a variety of methods to perform transformations on morphological data. These include:

  • Binarize, which transforms image data into morphological data.

  • Filter, which performs filtering operations on morphological data.

  • Merge, which combines different sets of morphological data.

  • Segment, which performs segmentation operations to yield morphological data.

Binarize

Binarizing operations can be imported using starfish.morphology.Binarize, which registers all classes that subclass BinarizeAlgorithm:

from starfish.morphology import Binarize

Algorithms in this module binarize an ImageStack into a BinaryMaskCollection.

class starfish.morphology.Binarize.ThresholdBinarize(threshold)

Binarizes an image using a threshold. Pixels that exceed the threshold are considered True and all remaining pixels are considered False.

The image being binarized must be an ImageStack with num_rounds == 1 and num_chs == 1.

Methods

run(self, image, \*args, \*\*kwargs)

Performs binarization on the stack provided.

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

Performs binarization on the stack provided.

Return type

BinaryMaskCollection

Filter

Filtering operations can be imported using starfish.morphology.Filter, which registers all classes that subclass FilterAlgorithm:

from starfish.morphology import Filter

Algorithms in this module filter a BinaryMaskCollection, producing another BinaryMaskCollection.

class starfish.morphology.Filter.Map(func, *func_args, module=<FunctionSource.np: ('numpy', {'max': 'amax'})>, **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 to each of the tiles in the input.

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.

Examples
——–
Applying a binary opening function.
>>> from starfish.core.morphology.binary_mask.test import factories
>>> from starfish.morphology import Filter
>>> from starfish.types import FunctionSource
>>> from skimage.morphology import disk
>>> binary_mask_collection = factories.binary_mask_collection_2d()
>>> opener = Filter.Map(FunctionSource.scipy("morphology.binary_opening"), disk(4))
>>> opened = opener.run(binary_mask_collection)

Methods

run(self, binary_mask_collection, …)

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

run(self, binary_mask_collection:starfish.core.morphology.binary_mask.binary_mask.BinaryMaskCollection, n_processes:Union[int, NoneType]=None, *args, **kwargs) → starfish.core.morphology.binary_mask.binary_mask.BinaryMaskCollection

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

Parameters
binary_mask_collectionBinaryMaskCollection

BinaryMaskCollection to be filtered.

n_processesOptional[int]

The number of processes to use for apply. If None, uses the output of os.cpu_count() (default = None).

Returns
BinaryMaskCollection

Return the results of filter as a new BinaryMaskCollection.

Return type

BinaryMaskCollection

class starfish.morphology.Filter.AreaFilter(min_area_DEPRECATED=None, max_area_DEPRECATED=None, *, min_area=None, max_area=None)

Create a BinaryMaskCollection using only the masks that meet the minimum and maximum area criteria.

Parameters
min_areaOptional[int]

Only masks that have area larger or equal to this will be included in the output mask collection.

max_areaOptional[int]

Only masks that have area smaller or equal to this will be included in the output mask collection.

Methods

run(self, binary_mask_collection, \*args, …)

Performs a filter on the binary mask collection provided.

run(self, binary_mask_collection:starfish.core.morphology.binary_mask.binary_mask.BinaryMaskCollection, *args, **kwargs) → starfish.core.morphology.binary_mask.binary_mask.BinaryMaskCollection

Performs a filter on the binary mask collection provided.

Return type

BinaryMaskCollection

class starfish.morphology.Filter.MinDistanceLabel(minimum_distance_xy=1, minimum_distance_z=1, exclude_border=False)

Using a BinaryMaskCollection with a single mask, produce a new BinaryMaskCollection with a mask representing each feature. Features are determined by obtaining the peak local maximum of a matrix consisting of the distance from each position to background. Watershed is applied to the distance matrix to obtain the features.

Note that due to bugs in skimage, exclude_border should generally be set to False.

Parameters
minimum_distance_xyint

The minimum distance between the peaks along the x or y axis. (default: 1)

minimum_distance_zint

The minimum distance between the peaks along the z axis. (default: 1)

exclude_borderbool

Exclude the borders for consideration for peaks. (default: False)

Methods

run(self, binary_mask_collection, \*args, …)

Performs a filter on the binary mask collection provided.

run(self, binary_mask_collection:starfish.core.morphology.binary_mask.binary_mask.BinaryMaskCollection, *args, **kwargs) → starfish.core.morphology.binary_mask.binary_mask.BinaryMaskCollection

Performs a filter on the binary mask collection provided.

Return type

BinaryMaskCollection

class starfish.morphology.Filter.Reduce(func, initial, *func_args, **func_kwargs)

Reduce takes masks from one BinaryMaskCollection and reduces it down to a single mask by applying a specified function. That mask is then returned as a new BinaryMaskCollection.

An initial value is used to start the reduction process. The first call to the function will be called with initial and M0 and produce R0. The second call to the function will be called with R0 and M1 and produce R1.

Parameters
funcUnion[str, FunctionSourceBundle]

Function to reduce the tiles in the input.

If this value is a string, then the python package is FunctionSource.np.

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

initialUnion[np.ndarray, Callable[[Tuple[int, …]], np.ndarray]]

An initial array that is the same shape as an uncropped mask, or a callable that accepts the shape of an uncropped mask as its parameter and produces an initial array.

Examples

Applying a logical ‘AND’ across all the masks in a collection.
>>> from starfish.core.morphology.binary_mask.test import factories
>>> from starfish.morphology import Filter
>>> from starfish.types import FunctionSource
>>> import numpy as np
>>> from skimage.morphology import disk
>>> binary_mask_collection = factories.binary_mask_collection_2d()
>>> initial_mask_producer = lambda shape: np.ones(shape=shape)
>>> ander = Filter.Reduce(FunctionSource.np("logical_and"), initial_mask_producer)
>>> anded = anded.run(binary_mask_collection)

Methods

run(self, binary_mask_collection, …)

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

run(self, binary_mask_collection:starfish.core.morphology.binary_mask.binary_mask.BinaryMaskCollection, n_processes:Union[int, NoneType]=None, *args, **kwargs) → starfish.core.morphology.binary_mask.binary_mask.BinaryMaskCollection

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

Parameters
binary_mask_collectionBinaryMaskCollection

BinaryMaskCollection to be filtered.

n_processesOptional[int]

The number of processes to use for apply. If None, uses the output of os.cpu_count() (default = None).

Returns
BinaryMaskCollection

Return the results of filter as a new BinaryMaskCollection.

Return type

BinaryMaskCollection

Merge

Filtering operations can be imported using starfish.morphology.Merge, which registers all classes that subclass MergeAlgorithm:

from starfish.morphology import Merge

Algorithms in this module merge multiple BinaryMaskCollections together.

class starfish.morphology.Merge.MergeAlgorithm

Merge multiple binary mask collections together.

Methods

run

class starfish.morphology.Merge.SimpleMerge

Merge multiple binary mask collections together. This implementation requires that all the binary mask collections have the same pixel and physical ticks.

Methods

run(self, binary_mask_collections, \*args, …)

Parameters

run(self, binary_mask_collections:Sequence[starfish.core.morphology.binary_mask.binary_mask.BinaryMaskCollection], *args, **kwargs) → starfish.core.morphology.binary_mask.binary_mask.BinaryMaskCollection
Parameters
binary_mask_collectionsSequence[BinaryMaskCollection]

A sequence of binary mask collections with identical pixel and physical ticks.

Returns
BinaryMaskCollection

A binary mask collection with the input mask collections merged together.

Return type

BinaryMaskCollection

Segment

Filtering operations can be imported using starfish.morphology.Segment, which registers all classes that subclass SegmentAlgorithm:

from starfish.morphology import Segment

Algorithms in this module segment cells and store the results in a BinaryMaskCollection.

class starfish.morphology.Segment.WatershedSegment(**watershed_kwargs)

Segments an image using a watershed algorithm. This wraps scikit-image’s watershed algorithm.

The image being segmented must be an ImageStack with num_rounds == 1 and num_chs == 1.

Any parameters besides image, markers, and mask should be set in the constructor and will be passed to scikit-image’s watershed.

Methods

run(self, image, markers, NoneType]=None, …)

Runs scikit-image’s watershed

run(self, image:starfish.core.imagestack.imagestack.ImageStack, markers:Union[starfish.core.morphology.binary_mask.binary_mask.BinaryMaskCollection, NoneType]=None, mask:Union[starfish.core.morphology.binary_mask.binary_mask.BinaryMaskCollection, NoneType]=None, *args, **kwargs) → starfish.core.morphology.binary_mask.binary_mask.BinaryMaskCollection

Runs scikit-image’s watershed

Return type

BinaryMaskCollection