IntensityTable

class starfish.core.intensity_table.intensity_table.IntensityTable(data: ~typing.Any = <NA>, coords: ~typing.Optional[~typing.Union[~collections.abc.Sequence[collections.abc.Sequence[Any] | pandas.core.indexes.base.Index | xarray.core.dataarray.DataArray], ~collections.abc.Mapping[~typing.Any, ~typing.Any]]] = None, dims: ~typing.Optional[~typing.Union[~collections.abc.Hashable, ~collections.abc.Sequence[~collections.abc.Hashable]]] = None, name: ~typing.Optional[~collections.abc.Hashable] = None, attrs: ~typing.Optional[~collections.abc.Mapping] = None, indexes: ~typing.Optional[~collections.abc.Mapping[~typing.Any, ~xarray.core.indexes.Index]] = None, fastpath: bool = False)[source]

IntensityTable is a container for spot or pixel features extracted from image data. It is the primary output from starfish SpotFinder methods.

An IntensityTable records the numeric intensity of a set of features in each (round, channel) tile in which the feature is identified. The IntensityTable has shape (n_feature, n_round, n_channel).

Some SpotFinder methods identify a position and search for Gaussian blobs in a small radius, only recording intensities if they are found in a given tile. Other :py:class:SpotFinder: approaches find blobs in a max-projection and measure them everywhere. As a result, some IntensityTables will be dense, and others will contain np.nan entries where no feature was detected.

Examples

Create an IntensityTable using the SyntheticData factory:

>>> from starfish.core.test.factories import SyntheticData
>>> sd = SyntheticData(n_ch=3, n_round=4, n_codes=2, n_spots=3)
>>> codes = sd.codebook()
>>> sd.intensities(codebook=codes)
<xarray.IntensityTable (features: 3, r: 4, c: 3)>
array([[[1., 0., 0.],
        [0., 1., 0.],
        [0., 0., 1.],
        [0., 1., 0.]],

       [[1., 0., 0.],
        [0., 1., 0.],
        [0., 0., 1.],
        [0., 1., 0.]],

       [[1., 0., 0.],
        [0., 1., 0.],
        [0., 0., 1.],
        [0., 1., 0.]]], dtype=float32)
Coordinates:
    z         (features) int64 8 6 2
    y         (features) float64 14.61 41.9 3.935
    x         (features) float64 11.0 42.42 5.249
    radius    (features) float64 nan nan nan
  * features  (features) int64 0 1 2
  * r         (r) int64 0 1 2 3
  * c         (c) int64 0 1 2
Attributes:
has_physical_coords

Returns True if this table’s features have physical-space loci.

Methods

concatenate_intensity_tables(intensity_tables)

Parameters:

from_image_stack(image_stack[, crop_x, ...])

Generate an IntensityTable from all the pixels in the ImageStack

from_spot_data(intensities, spot_attributes, ...)

Creates an IntensityTable from a (features, channel, round) array and a SpotAttributes object.

get_log()

Deserialize and return a list of pipeline components that have been applied throughout a starfish session to create this :py:class:IntensityTable:.

item(*args)

Copy an element of an array to a standard Python scalar and return it.

open_netcdf(filename)

Load an IntensityTable from Netcdf.

searchsorted(v[, side, sorter])

Find indices where elements of v should be inserted in a to maintain order.

synthetic_intensities(codebook[, num_z, ...])

Creates an IntensityTable with synthetic spots, that correspond to valid codes in a provided codebook.

to_features_dataframe()

Generates a dataframe of the underlying features metadata.

to_netcdf(filename)

Save an IntensityTable as a Netcdf File.

zeros(spot_attributes, round_labels, ch_labels)

Create an empty intensity table with pre-set shape whose values are zero.

static concatenate_intensity_tables(intensity_tables: List[IntensityTable], overlap_strategy: Optional[OverlapStrategy] = None) IntensityTable[source]
Parameters:
intensity_tables: List[IntensityTable]

List of IntensityTables to be combined.

overlap_strategy
Returns:
classmethod from_image_stack(image_stack, crop_x: int = 0, crop_y: int = 0, crop_z: int = 0) IntensityTable[source]

Generate an IntensityTable from all the pixels in the ImageStack

Parameters:
crop_xint

Number of pixels to crop from both top and bottom of x.

crop_yint

Number of pixels to crop from both top and bottom of y.

crop_zint

Number of pixels to crop from both top and bottom of z.

image_stackImageStack

ImageStack containing pixels to be treated as intensities.

Returns:
IntensityTable

IntensityTable containing one intensity per pixel (across channels and rounds).

classmethod from_spot_data(intensities: ndarray, spot_attributes: SpotAttributes, round_values: Sequence[int], ch_values: Sequence[int], *args, **kwargs) IntensityTable[source]

Creates an IntensityTable from a (features, channel, round) array and a SpotAttributes object.

Parameters:
intensitiesnp.ndarray

Intensity data.

spot_attributesSpotAttributes

Table containing spot metadata. Must contain the values specified in Axes.X, Y, Z, and RADIUS.

ch_valuesSequence[int]

The possible values for the channel number, in the order that they are in the ImageStack 5D tensor.

round_valuesSequence[int]

The possible values for the round number, in the order that they are in the ImageStack

args

Additional arguments to pass to the xarray constructor.

kwargs

Additional keyword arguments to pass to the xarray constructor.

Returns:
IntensityTable

IntensityTable containing data from passed intensities, annotated by spot_attributes

get_log()[source]

Deserialize and return a list of pipeline components that have been applied throughout a starfish session to create this :py:class:IntensityTable:.

property has_physical_coords

Returns True if this table’s features have physical-space loci.

item(*args)

Copy an element of an array to a standard Python scalar and return it.

Parameters:
*argsArguments (variable number and type)
  • none: in this case, the method only works for arrays with one element (a.size == 1), which element is copied into a standard Python scalar object and returned.

  • int_type: this argument is interpreted as a flat index into the array, specifying which element to copy and return.

  • tuple of int_types: functions as does a single int_type argument, except that the argument is interpreted as an nd-index into the array.

Returns:
zStandard Python scalar object

A copy of the specified element of the array as a suitable Python scalar

Notes

When the data type of a is longdouble or clongdouble, item() returns a scalar array object because there is no available Python scalar that would not lose information. Void arrays return a buffer object for item(), unless fields are defined, in which case a tuple is returned.

item is very similar to a[args], except, instead of an array scalar, a standard Python scalar is returned. This can be useful for speeding up access to elements of the array and doing arithmetic on elements of the array using Python’s optimized math.

Examples

>>> np.random.seed(123)
>>> x = np.random.randint(9, size=(3, 3))
>>> x
array([[2, 2, 6],
       [1, 3, 6],
       [1, 0, 1]])
>>> x.item(3)
1
>>> x.item(7)
0
>>> x.item((0, 1))
2
>>> x.item((2, 2))
1
classmethod open_netcdf(filename: str) IntensityTable[source]

Load an IntensityTable from Netcdf.

Parameters:
filenamestr

File to load.

Returns:
IntensityTable
searchsorted(v, side='left', sorter=None)

Find indices where elements of v should be inserted in a to maintain order.

For full documentation, see numpy.searchsorted

See also

numpy.searchsorted

equivalent function

classmethod synthetic_intensities(codebook, num_z: int = 12, height: int = 50, width: int = 40, n_spots: int = 10, mean_fluor_per_spot: int = 200, mean_photons_per_fluor: int = 50) IntensityTable[source]

Creates an IntensityTable with synthetic spots, that correspond to valid codes in a provided codebook.

Parameters:
codebookCodebook

Starfish codebook object.

num_zint

Number of z-planes to use when localizing spots.

heightint

y dimension of each synthetic plane.

widthint

x dimension of each synthetic plane.

n_spotsint

Number of spots to generate.

mean_fluor_per_spotint

Mean number of fluorophores per spot.

mean_photons_per_fluorint

Mean number of photons per fluorophore.

Returns:
IntensityTable
to_features_dataframe() DataFrame[source]

Generates a dataframe of the underlying features metadata. This is guaranteed to contain the features x, y, z, and radius.

Returns:
pd.DataFrame
to_netcdf(filename: str) None[source]

Save an IntensityTable as a Netcdf File.

Parameters:
filenamestr

Name of Netcdf file.

classmethod zeros(spot_attributes: SpotAttributes, round_labels: Sequence[int], ch_labels: Sequence[int]) IntensityTable[source]

Create an empty intensity table with pre-set shape whose values are zero.

Parameters:
spot_attributesSpotAttributes

Table containing spot metadata. Must contain the values specified in Axes.X, Y, Z, and RADIUS.

round_labelsSequence[int]

The possible values for the round number, in the order that they are in the ImageStack 5D tensor.

ch_labelsSequence[int]

The possible values for the channel number, in the order that they are in the ImageStack 5D tensor.

Returns:
IntensityTable

IntensityTable filled with zeros.

starfish.core.intensity_table.intensity_table_coordinates.transfer_physical_coords_to_intensity_table(*, intensity_table: IntensityTable, image_stack: Optional[ImageStack] = None, spots: Optional[SpotFindingResults] = None) IntensityTable[source]

Transfers physical coordinates from either an Imagestack or SpotFindingResults to an intensity table

  1. Creates three new coords on the intensity table (xc, yc, zc)

  2. For every spot:
    • Get pixel x,y values

    • Calculate the physical x,y values

    • Assign those values to the coords arrays for this spot