Spots

Starfish provides a number of methods for which spots (or other regions of interest) are the main substrate. These include starfish.spots.DetectPixels, which exposes methods that identify which target code best corresponds to each pixel, and merges adjacent pixels into ROIs, starfish.spots.FindSpots, which exposes methods that find bright spots against dark backgrounds, starfish.spots.DecodeSpots, which exposes methods that match patterns of spots detected across rounds and channels in the same spatial positions with target codes, and starfish.spots.AssignTargets, which exposes methods to assign spots to cells.

Detecting Pixels

Pixel Detectors can be imported using starfish.spots.DetectPixels, which registers all classes that subclass DetectPixelsAlgorithm:

from starfish.spots import DetectPixels

class starfish.spots.DetectPixels.PixelSpotDecoder(codebook, metric, distance_threshold, magnitude_threshold, min_area, max_area, norm_order=2)

Decode an image by first coding each pixel, then combining the results into spots

Parameters

codebookCodebook

Codebook object mapping codewords to the targets they are designed to detect

metricstr

the sklearn metric string to pass to NearestNeighbors

distance_thresholdfloat

spots whose codewords are more than this metric distance from an expected code are filtered

magnitude_thresholdint

spots with intensity less than this value are filtered

min_areaint

spots with total area less than this value are filtered

max_areaint

spots with total area greater than this value are filtered

norm_orderint

order of L_p norm to apply to intensities and codes when using metric_decode to pair each intensities to its closest target (default = 2)

Methods

run(self, primary_image, n_processes, …)

decode pixels and combine them into spots using connected component labeling

run(self, primary_image:starfish.core.imagestack.imagestack.ImageStack, n_processes:Union[int, NoneType]=None, *args) → Tuple[starfish.core.intensity_table.decoded_intensity_table.DecodedIntensityTable, starfish.core.spots.DetectPixels.combine_adjacent_features.ConnectedComponentDecodingResult]

decode pixels and combine them into spots using connected component labeling

Parameters

primary_imageImageStack

ImageStack containing spots

n_processesOptional[int]

The number of processes to use for CombineAdjacentFeatures.

If None, uses the output of os.cpu_count() (default = None).

Returns

DecodedIntensityTable :

IntensityTable containing decoded spots

ConnectedComponentDecodingResult :

Results of connected component labeling

Return type

Tuple[DecodedIntensityTable, ConnectedComponentDecodingResult]

Finding Spots

Spot Finders can be imported using starfish.spots.FindSpots, which registers all classes that subclass FindSpotsAlgorithm:

from starfish.spots import FindSpots

class starfish.spots.FindSpots.BlobDetector(min_sigma, max_sigma, num_sigma, threshold, overlap=0.5, measurement_type='max', is_volume=True, detector_method='blob_log', exclude_border=None)

Multi-dimensional gaussian spot detector

This method is a wrapper for skimage.feature.blob_log()

Parameters

min_sigmaNumber

The minimum standard deviation for Gaussian Kernel. Keep this low to detect smaller blobs.

max_sigmaNumber

The maximum standard deviation for Gaussian Kernel. Keep this high to detect larger blobs.

num_sigmaint

The number of intermediate values of standard deviations to consider between min_sigma and max_sigma.

thresholdfloat

The absolute lower bound for scale space maxima. Local maxima smaller than threshold are ignored. Reduce this to detect blobs with less intensities.

is_volume: bool

If True, pass 3d volumes (x, y, z) to func, else pass 2d tiles (x, y) to func. (default: True)

overlapfloat [0, 1]

If two spots have more than this fraction of overlap, the spots are combined (default: 0.5)

measurement_typestr [‘max’, ‘mean’]

name of the function used to calculate the intensity for each identified spot area (default: max)

detector_method: str [‘blob_dog’, ‘blob_doh’, ‘blob_log’]

name of the type of detection method used from feature (default: blob_log)

Notes

See also: Blob Detection

Methods

image_to_spots(self, data_image)	Find spots using a gaussian blob finding algorithm
run(self, image_stack, reference_image, …)	Find spots in the given ImageStack using a gaussian blob finding algorithm.

image_to_spots(self, data_image:numpy.ndarray) → starfish.core.types._spot_finding_results.PerImageSliceSpotResults

Find spots using a gaussian blob finding algorithm

Parameters

data_imagenp.ndarray

image containing spots to be detected

Returns

PerImageSpotResults :

includes a SpotAttributes DataFrame of metadata containing the coordinates, intensity and radius of each spot, as well as any extra information collected during spot finding.

Return type

PerImageSliceSpotResults

run(self, image_stack:starfish.core.imagestack.imagestack.ImageStack, reference_image:Union[starfish.core.imagestack.imagestack.ImageStack, NoneType]=None, n_processes:Union[int, NoneType]=None, *args) → starfish.core.types._spot_finding_results.SpotFindingResults

Find spots in the given ImageStack using a gaussian blob finding algorithm. If a reference image is provided the spots will be detected there then measured across all rounds and channels in the corresponding ImageStack. If a reference_image is not provided spots will be detected _independently_ in each channel. This assumes a non-multiplex imaging experiment, as only one (ch, round) will be measured for each spot.

Parameters

image_stackImageStack

ImageStack where we find the spots in.

reference_imageOptional[ImageStack]

(Optional) a reference image. If provided, spots will be found in this image, and then the locations that correspond to these spots will be measured across each channel.

n_processesOptional[int] = None,

Number of processes to devote to spot finding.

Return type

SpotFindingResults

class starfish.spots.FindSpots.FindSpotsAlgorithm

Starfish spot finders use a variety of means to detect bright spots against dark backgrounds. Starfish’s spot detectors each have different strengths and weaknesses.

Fixed-position spot finders

The following spot finders have two modes of operation.

The first mode is suitable for coded experiments where genes are identified by patterns of spots over all rounds and channels of the experiment. In this mode, the spot finders identify spots in a single reference image, which can be either a dots auxiliary image, or a maximum intensity projection of the primary images. The positions of the maxima are then measured in all other images, and the intensities across the complete experiment are stored in an IntensityTable

The second mode is suitable for assays that detect spots in a single round, such as single molecule FISH and RNAscope. This mode simply finds all the spots and concatenates them into a long-form IntensityTable. In this mode, the spots are not measured in images that correspond to other (round, channel) pairs; those positions of the IntensityTable are filled with np.nan.

1. The BlobDetector allows the user to pre-filter an image using either a Laplacian-of-Gaussians or Difference-of-Gaussians (fast approximation to Laplacian-of-Gaussians). These filters are applied at with a user-specified variety of Gaussian kernel sizes, and the best-fitting size is automatically selected. This allows this filter to detect Gaussian shaped blobs of various sizes.

Methods

run(self, image_stack, reference_image, …)

Find and measure spots across rounds and channels in the provided ImageStack.

abstract run(self, image_stack:starfish.core.imagestack.imagestack.ImageStack, reference_image:Union[starfish.core.imagestack.imagestack.ImageStack, NoneType]=None, *args) → starfish.core.types._spot_finding_results.SpotFindingResults

Find and measure spots across rounds and channels in the provided ImageStack.

Return type

SpotFindingResults

class starfish.spots.FindSpots.TrackpyLocalMaxPeakFinder(spot_diameter, min_mass, max_size, separation, percentile=0, noise_size=(1, 1, 1), smoothing_size=None, threshold=None, preprocess=False, max_iterations=10, measurement_type='max', is_volume=None, verbose=False, radius_is_gyration=False)

Find spots using a local max peak finding algorithm

This is a wrapper for trackpy.locate, which implements a version of the Crocker-Grier algorithm.

Parameters

spot_diameter :

odd integer or tuple of odd integers. This may be a single number or a tuple giving the feature’s extent in each dimension, useful when the dimensions do not have equal resolution (e.g. confocal microscopy). The tuple order is the same as the image shape, conventionally (z, y, x) or (y, x). The number(s) must be odd integers. When in doubt, round up.

min_massOptional[float]

The minimum integrated brightness. This is a crucial parameter for eliminating spurious features. Recommended minimum values are 100 for integer images and 1 for float images. Defaults to 0 (no filtering).

max_sizefloat

maximum radius-of-gyration of brightness, default None

separationUnion[float, tuple]

Minimum separation between features. Default is diameter + 1. May be a tuple, see diameter for details.

percentilefloat

Features must have a peak brighter than pixels in this percentile. This helps eliminate spurious peaks. (default = 0)

noise_sizeUnion[float, tuple]

Width of Gaussian blurring kernel, in pixels Default is 1. May be a tuple, see diameter for details.

smoothing_sizeUnion[float, tuple]

The size of the sides of the square kernel used in boxcar (rolling average) smoothing, in pixels Default is diameter. May be a tuple, making the kernel rectangular.

thresholdfloat

Clip bandpass result below this value. Thresholding is done on the already background-subtracted image. By default, 1 for integer images and 1/255 for float images.

measurement_typestr [‘max’, ‘mean’]

name of the function used to calculate the intensity for each identified spot area (default = max)

preprocessboolean

Set to False to turn off bandpass prepossessing.

max_iterationsinteger

Max number of loops to refine the center of mass, (default = 10)

verbosebool

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

Notes

See also: trackpy.locate

Methods

image_to_spots(self, data_image)	Parameters
run(self, image_stack, reference_image, …)	Find spots in the given ImageStack using a version of the Crocker-Grier algorithm.

image_to_spots(self, data_image:numpy.ndarray) → starfish.core.types._spot_finding_results.PerImageSliceSpotResults

Parameters

data_imagenp.ndarray

three-dimensional image containing spots to be detected

Returns

PerImageSpotResults :

includes a SpotAttributes DataFrame of metadata containing the coordinates, intensity and radius of each spot, as well as any extra information collected during spot finding.

Return type

PerImageSliceSpotResults

run(self, image_stack:starfish.core.imagestack.imagestack.ImageStack, reference_image:Union[starfish.core.imagestack.imagestack.ImageStack, NoneType]=None, n_processes:Union[int, NoneType]=None, *args) → starfish.core.types._spot_finding_results.SpotFindingResults

Find spots in the given ImageStack using a version of the Crocker-Grier algorithm. If a reference image is provided the spots will be detected there then measured across all rounds and channels in the corresponding ImageStack. If a reference_image is not provided spots will be detected _independently_ in each channel. This assumes a non-multiplex imaging experiment, as only one (ch, round) will be measured for each spot.

Parameters

image_stackImageStack

ImageStack where we find the spots in.

reference_imageOptional[ImageStack]

(Optional) a reference image. If provided, spots will be found in this image, and then the locations that correspond to these spots will be measured across each channel.

n_processesOptional[int] = None,

Number of processes to devote to spot finding.

Return type

SpotFindingResults

class starfish.spots.FindSpots.LocalMaxPeakFinder(min_distance, stringency, min_obj_area, max_obj_area, threshold=None, measurement_type='max', min_num_spots_detected=3, is_volume=True, verbose=True, **kwargs)

local-max peak finder that wraps skimage.feature.peak_local_max()

Parameters

min_distanceint

Minimum number of pixels separating peaks in a region of 2 * min_distance + 1 (i.e. peaks are separated by at least min_distance). To find the maximum number of peaks, use min_distance=1.

stringencyint

min_obj_areaint

max_obj_areaint

thresholdOptional[Number]

measurement_typestr, {‘max’, ‘mean’}

default ‘max’ calculates the maximum intensity inside the object

min_num_spots_detectedint

When fewer than this number of spots are detected, spot searching for higher threshold values. (default = 3)

is_volumebool

If True, run the algorithm on 3d volumes of the provided stack. (default = True)

verbosebool

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

kwargs :

Additional keyword arguments to pass to skimage.feature.peak_local_max()

Notes

skimage.feature.peak_local_max()

Methods

image_to_spots(self, data_image, \*\*kwargs)	measure attributes of spots detected by binarizing the image using the selected threshold
run(self, image_stack, reference_image, …)	Find spots in the given ImageStack using a local maxima finding algorithm.

image_to_spots(self, data_image:xarray.core.dataarray.DataArray, **kwargs) → starfish.core.types._spot_finding_results.PerImageSliceSpotResults

measure attributes of spots detected by binarizing the image using the selected threshold

Parameters

data_imagexr.DataArray

image containing spots to be detected

kwargs :

Additional keyword arguments to pass to peak_local_max()

Returns

PerImageSliceSpotResults :

includes a SpotAttributes DataFrame of metadata containing the coordinates, intensity and radius of each spot, as well as any extra information collected during spot finding.

Return type

PerImageSliceSpotResults

run(self, image_stack:starfish.core.imagestack.imagestack.ImageStack, reference_image:Union[starfish.core.imagestack.imagestack.ImageStack, NoneType]=None, n_processes:Union[int, NoneType]=None, *args, **kwargs) → starfish.core.types._spot_finding_results.SpotFindingResults

Find spots in the given ImageStack using a local maxima finding algorithm. If a reference image is provided the spots will be detected there then measured across all rounds and channels in the corresponding ImageStack. If a reference_image is not provided spots will be detected _independently_ in each channel. This assumes a non-multiplex imaging experiment, as only one (ch, round) will be measured for each spot.

Parameters

image_stackImageStack

ImageStack where we find the spots in.

reference_imageOptional[ImageStack]

(Optional) a reference image. If provided, spots will be found in this image, and then the locations that correspond to these spots will be measured across each channel.

n_processesOptional[int] = None,

Number of processes to devote to spot finding.

Return type

SpotFindingResults

Decoding Spots

Spot Decoders can be imported using starfish.spots.DecodeSpots, which registers all classes that subclass DecodeSpotsAlgorithm:

from starfish.spots import DecodeSpots

class starfish.spots.DecodeSpots.PerRoundMaxChannel(codebook, trace_building_strategy=<TraceBuildingStrategies.EXACT_MATCH: 'exact_match'>, anchor_round=1, search_radius=3)

Decode spots by selecting the max-valued channel in each sequencing round.

Note that this assumes that the codebook contains only one “on” channel per sequencing round, a common pattern in experiments that assign one fluorophore to each DNA nucleotide and read DNA sequentially. It is also a characteristic of single-molecule FISH and RNAscope codebooks.

Parameters

codebookCodebook

Contains codes to decode IntensityTable

trace_building_strategy: TraceBuildingStrategies

Defines the strategy for building spot traces to decode across rounds and chs of spot finding results.

search_radiusOptional[int]

Only applicable if trace_building_strategy is TraceBuildingStrategies.NEAREST_NEIGHBORS. Number of pixels over which to search for spots in other rounds and channels.

anchor_roundOptional[int]

Only applicable if trace_building_strategy is TraceBuildingStrategies.NEAREST_NEIGHBORS. The imaging round against which other rounds will be checked for spots in the same approximate pixel location.

Methods

run(self, spots, \*args)

Decode spots by selecting the max-valued channel in each sequencing round

run(self, spots:starfish.core.types._spot_finding_results.SpotFindingResults, *args) → starfish.core.intensity_table.decoded_intensity_table.DecodedIntensityTable

Decode spots by selecting the max-valued channel in each sequencing round

Parameters

spots: SpotFindingResults

A Dict of tile indices and their corresponding measured spots

Returns

DecodedIntensityTable :

IntensityTable decoded and appended with Features.TARGET and Features.QUALITY values.

Return type

DecodedIntensityTable

class starfish.spots.DecodeSpots.MetricDistance(codebook, max_distance, min_intensity, norm_order=2, metric='euclidean', trace_building_strategy=<TraceBuildingStrategies.EXACT_MATCH: 'exact_match'>, anchor_round=1, search_radius=3, return_original_intensities=False)

Normalizes both the magnitudes of the codes and the spot intensities, then decodes spots by assigning each spot to the closest code, measured by the provided metric.

Codes greater than max_distance from the nearest code, or dimmer than min_intensity, are discarded.

Parameters

codebookCodebook

codebook containing targets the experiment was designed to quantify

max_distanceNumber

spots greater than this distance from their nearest target are not decoded

min_intensityNumber

spots dimmer than this intensity are not decoded

metricstr

the metric to use to measure distance. Can be any metric that satisfies the triangle inequality that is implemented by scipy.spatial.distance (default “euclidean”)

norm_orderint

the norm to use to normalize the magnitudes of spots and codes (default 2, L2 norm)

trace_building_strategy: TraceBuildingStrategies

Defines the strategy for building spot traces to decode across rounds and chs of spot finding results.

anchor_roundOptional[int]

Only applicable if trace_building_strategy is TraceBuildingStrategies.NEAREST_NEIGHBORS. The imaging round against which other rounds will be checked for spots in the same approximate pixel location.

search_radiusOptional[int]

Only applicable if trace_building_strategy is TraceBuildingStrategies.NEAREST_NEIGHBORS. Number of pixels over which to search for spots in other rounds and channels.

return_original_intensities: bool

If True returns original intensity values in the DecodedIntensityTable instead of normalized ones (default=False)

Methods

run(self, spots, \*args)

Decode spots by selecting the max-valued channel in each sequencing round

run(self, spots:starfish.core.types._spot_finding_results.SpotFindingResults, *args) → starfish.core.intensity_table.decoded_intensity_table.DecodedIntensityTable

Decode spots by selecting the max-valued channel in each sequencing round

Parameters

spotsSpotFindingResults

A Dict of tile indices and their corresponding measured spots

Returns

DecodedIntensityTable :

IntensityTable decoded and appended with Features.TARGET and Features.QUALITY values.

Return type

DecodedIntensityTable

class starfish.spots.DecodeSpots.SimpleLookupDecoder(codebook)

Decode spots by assigning the target value of a spot to the corresponding target value of the round/ch it was found in. This method only makes sense to use in non mulitplexed sequential assays where each r/ch pair only has one target assigned to it.

Parameters

codebookCodebook

Contains codes to decode IntensityTable

Methods

run(self, spots, \*args)

Decode spots by looking up the associated target value for the round and ch each spot is in.

run(self, spots:starfish.core.types._spot_finding_results.SpotFindingResults, *args) → starfish.core.intensity_table.decoded_intensity_table.DecodedIntensityTable

Decode spots by looking up the associated target value for the round and ch each spot is in.

Parameters

spots: SpotFindingResults

A Dict of tile indices and their corresponding measured spots

Returns

DecodedIntensityTable :

IntensityTable decoded and appended with Features.TARGET and values.

Return type

DecodedIntensityTable

class starfish.spots.DecodeSpots.DecodeSpotsAlgorithm

Performs decoding on the spots found, using the codebook specified.

Methods

run

Target Assignment

Target Assignment can be imported using starfish.spots.AssignTargets, which registers all classes that subclass AssignTargetsAlgorithm:

from starfish.spots import AssignTargets

class starfish.spots.AssignTargets.AssignTargetsAlgorithm

AssignTargets assigns cell IDs to detected spots using an IntensityTable and SegmentationMaskCollection.

Methods

run(self, label_image, …)

Performs target (e.g.

abstract run(self, label_image:numpy.ndarray, decoded_intensity_table:starfish.core.intensity_table.decoded_intensity_table.DecodedIntensityTable, verbose:bool=False, in_place:bool=False) → starfish.core.intensity_table.decoded_intensity_table.DecodedIntensityTable

Performs target (e.g. gene) assignment given the spots and the regions.

Return type

DecodedIntensityTable

class starfish.spots.AssignTargets.Label(**kwargs)

Extract cell ids for features in IntensityTable from a set of segmentation masks.

Methods

run(self, masks, decoded_intensity_table, …)

Extract cell ids for features in IntensityTable from a segmentation label image

run(self, masks:starfish.core.morphology.binary_mask.binary_mask.BinaryMaskCollection, decoded_intensity_table:starfish.core.intensity_table.decoded_intensity_table.DecodedIntensityTable, verbose:bool=False, in_place:bool=False) → starfish.core.intensity_table.decoded_intensity_table.DecodedIntensityTable

Extract cell ids for features in IntensityTable from a segmentation label image

Parameters

masksBinaryMaskCollection

binary masks segmenting each cell

decoded_intensity_tableIntensityTable

spot information

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)

Returns

IntensityTable :

IntensityTable with added features variable containing cell ids. Points outside of cells will be assigned nan.

Return type

DecodedIntensityTable