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.intensity_table.IntensityTable, 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

IntensityTable :: IntensityTable containing decoded spots
ConnectedComponentDecodingResult :: Results of connected component labeling

Return type: Tuple[IntensityTable, 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 skimage.feature (default: blob_log)

Notes

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.LocalMaxPeakFinder(min_distance, stringency, min_obj_area, max_obj_area, threshold=None, measurement_type='max', min_num_spots_detected=3, is_volume=False, verbose=True)¶

2-dimensional 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: Not supported. For 3d peak detection please use TrackpyLocalMaxPeakFinder. (default=False)
verbosebool: If True, report the percentage completed during processing (default = False)

Notes

http://scikit-image.org/docs/dev/api/skimage.feature.html#skimage.feature.peak_local_max

Methods

`image_to_spots`(self, data_image)	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 gaussian blob finding algorithm.

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

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

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, **kwargs) → 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.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=False, 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)
is_volumebool: if True, run the algorithm on 3d volumes of the provided stack (default = False)
verbosebool: If True, report the percentage completed (default = False) during processing

Notes

Methods

image_to_spots(self, data_image)

Parameters

run(self, image_stack, reference_image, …)

Find spots.

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.

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¶

NOTE: Starfish is embarking on a SpotFinding data structures refactor see Spot Finding Refactor Plan

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.DecodeSpotsAlgorithm¶

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

Methods

run

class starfish.spots.DecodeSpots.SimpleLookupDecoder(codebook)¶

Decode spots by assiging 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.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.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

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.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 zero.

Return type: DecodedIntensityTable

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