ImageStack

class starfish.core.imagestack.imagestack.ImageStack(data, tile_data)[source]

ImageStacks are the main objects for processing images in starfish. It is a 5-dimensional Image Tensor that labels each (z, y, x) tile with the round and channel and zplane it corresponds to. The class is a wrapper around xarray.DataArray. The names of each imaging r/ch/zplane as well as the physical coordinates of each tile are stored as coordinates on the xarray.DataArray. ImageStacks can only be initialized with aligned Tilesets.

Loads configuration from StarfishConfig.

Attributes
num_chsint

Return the number of channels in the ImageStack

num_roundsint

Return the number of rounds in the ImageStack

num_zplanesint

Return the number of z_planes in the ImageStack

xarrayxarray.DataArray

Retrieves the image data as an xarray.DataArray

raw_shapeTuple[int]

Returns the shape of the 5-d image tensor stored as self.image

shapeDict[str, int]

Returns the shape of the space that this image inhabits.

Methods

apply(func, *args[, group_by, in_place, …])

Split the image along a set of axes and apply a function across all the components.

axis_labels(axis)

Given an axis, return the sorted unique values for that axis in this ImageStack.

export(filepath[, tile_opener, tile_format])

write the image tensor to disk in spaceTx format

from_numpy(array[, index_labels, coordinates])

Create an ImageStack from a 5d numpy array with shape (n_round, n_ch, n_z, y, x)

from_path_or_url(url_or_path[, aligned_group])

Constructs an ImageStack object from an absolute URL or a filesystem path.

from_tilefetcher(tilefetcher, tile_shape, …)

Parse a TileFetcher into an ImageStack.

from_tileset(tileset[, crop_parameters])

Parse a slicedimage.TileSet into an ImageStack.

from_url(url, baseurl[, aligned_group])

Constructs an ImageStack object from a URL and a base URL.

get_slice(selector)

Given a dictionary mapping the index name to either a value or a slice range, return a numpy array representing the slice, and a list of the remaining axes beyond the normal x-y tile.

isel(indexers)

Given a dictionary mapping the index name to either a value or a range represented as a tuple, return an Imagestack with each dimension indexed by position accordingly

map(func[, module, in_place, group_by, …])

Maps the contents of the ImageStack to produce another image.

max_proj(*dims)

This method is deprecated.

reduce(dims, func[, module, level_method])

Reduces the dimensionality of the ImageStack and returns a new ImageStack with the result.

sel(indexers)

Given a dictionary mapping the index name to either a value or a range represented as a tuple, return an Imagestack with each dimension indexed accordingly

sel_by_physical_coords(indexers)

Given a dictionary mapping the coordinate name to either a value or a range represented as a tuple, return an Imagestack with each the Coordinate dimension indexed accordingly.

set_slice(selector, data[, axes, from_loader])

Given a dictionary mapping the index name to either a value or a slice range and a source numpy array, set the slice of the array of this ImageStack to the values in the source numpy array.

to_multipage_tiff(filepath)

save the ImageStack as a FIJI-compatible multi-page TIFF file

transform(func, *args[, group_by, verbose, …])

Split the image along a set of axes, and apply a function across all the components.

from_tile_collection_data

apply(func, *args, group_by=None, in_place=False, verbose=False, n_processes=None, level_method=<Levels.CLIP: 'clip'>, **kwargs)[source]

Split the image along a set of axes and apply a function across all the components. This function should yield data of the same dimensionality as the input components. These resulting components are then constituted into an ImageStack and returned.

Parameters
funcCallable

Function to apply. must expect a first argument which is a 2d or 3d numpy array and return an array of the same shape.

group_bySet[Axes]

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

in_placebool

If True, function is executed in place and returns None. If false, a new ImageStack object will be produced. (Default False)

verbosebool

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

n_processesOptional[int]

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

kwargsdict

Additional arguments to pass to func

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.

Returns
ImageStack :

If inplace is False, return a new ImageStack, otherwise return a reference to the original stack with data modified by application of func

Raises
TypeError :

If no Clip method given.

Return type

Optional[ImageStack]

axis_labels(axis)[source]

Given an axis, return the sorted unique values for that axis in this ImageStack. For instance, imagestack.axis_labels(Axes.ROUND) returns all the round ids in this imagestack.

Return type

Sequence[int]

export(filepath, tile_opener=None, tile_format=<ImageFormat.NUMPY: (<function numpy_reader>, <function numpy_writer>, 'npy', None)>)[source]

write the image tensor to disk in spaceTx format

Parameters
filepathstr

Path + prefix for the images and primary_images.json written by this function

tile_openerOptional[Callable[[PurePath, Tile, str], BinaryIO]]

A callable responsible for opening the file that a tile’s data is to be written to. The callable should accept three arguments – the path of the tileset, the tile data, and the expected file extension. If this is not specified, a reasonable default is provided.

tile_formatImageFormat

Format in which each 2D plane should be written.

Return type

None

classmethod from_numpy(array, index_labels=None, coordinates=None)[source]

Create an ImageStack from a 5d numpy array with shape (n_round, n_ch, n_z, y, x)

Parameters
arraynp.ndarray

5-d tensor of shape (n_round, n_ch, n_z, y, x)

index_labelsOptional[Mapping[Axes, Sequence[int]]]

Mapping from axes (r, ch, z) to their labels. If this is not provided, then the axes will be labeled from 0..(n-1), where n=the size of the axes.

coordinatesOptional[Mapping[Coordinates, ArrayLike[Number]]]

Map from Coordinates to a sequence of coordinate values. If this is not provided, then the ImageStack gets fake coordinates.

Returns
ImageStack :

array data stored as an ImageStack

Return type

ImageStack

classmethod from_path_or_url(url_or_path, aligned_group=0)[source]

Constructs an ImageStack object from an absolute URL or a filesystem path.

The following examples will all load from the same location:

Parameters
url_or_pathstr

Either an absolute URL or a filesystem path to an imagestack.

aligned_group: int

Which aligned tile group to load into the Imagestack, only applies if the tileset is unaligned. Default 0 (the first group)

Return type

ImageStack

classmethod from_tilefetcher(tilefetcher, tile_shape, fov, rounds, chs, zplanes, group_by=None, crop_parameters=None)[source]

Parse a TileFetcher into an ImageStack.

Parameters
tilefetcherTileFetcher

The tilefetcher to parse.

tile_shapeMapping[Axes, int]

Mapping from the axis type to the cardinality of that axis.

fovint

The fov number to retrieve from the TileFetcher to constitute this ImageStack.

roundsSequence[int]

The rounds to include in this ImageStack.

chsSequence[int]

The channels to include in this ImageStack.

zplanesSequence[int]

The zplanes to include in this ImageStack.

group_byOptional[Set[Axes]]

Axes to load the data by. If an axis is present in this list, all the data for a given value along that axis will be loaded concurrently. For example, if group_by is (Axes.ROUND, Axes.CH), then all the data for ROUND=2, CH=1 will be loaded before we progress to ROUND=3, CH=1.

crop_parametersOptional[CropParameters]

If cropping of the data is desired, it should be specified here.

Returns
ImageStack :

An ImageStack representing encapsulating the data from the TileFetcher.

Return type

ImageStack

classmethod from_tileset(tileset, crop_parameters=None)[source]

Parse a slicedimage.TileSet into an ImageStack.

Parameters
tilesetTileSet

The tileset to parse.

crop_parametersOptional[CropParameters]
Returns
ImageStack :

An ImageStack representing encapsulating the data from the TileSet.

Return type

ImageStack

classmethod from_url(url, baseurl, aligned_group=0)[source]

Constructs an ImageStack object from a URL and a base URL.

The following examples will all load from the same location:

Parameters
urlstr

Either an absolute URL or a relative URL referring to the image to be read.

baseurlOptional[str]

If url is a relative URL, then this must be provided. If url is an absolute URL, then this parameter is ignored.

aligned_group: int

Which aligned tile group to load into the Imagestack, only applies if the tileset is unaligned. Default 0 (the first group)

Returns
ImageStack :

An ImageStack representing encapsulating the data from the TileSet.

get_slice(selector)[source]

Given a dictionary mapping the index name to either a value or a slice range, return a numpy array representing the slice, and a list of the remaining axes beyond the normal x-y tile.

Examples

Slicing with a scalar
>>> from starfish import ImageStack
>>> from starfish.core.imagestack.test.factories import synthetic_stack
>>> from starfish.types import Axes
>>> stack = synthetic_stack(3, 4, 5, 20, 10)
>>> stack.shape
OrderedDict([(<Axes.ROUND: 'r'>, 3),
 (<Axes.CH: 'c'>, 4),
 (<Axes.ZPLANE: 'z'>, 5),
 ('y', 20),
 ('x', 10)])
>>> stack.axis_labels(Axes.ROUND)
[0, 1, 2]
>>> stack.axis_labels(Axes.CH)
[0, 1, 2, 3]
>>> stack.axis_labels(Axes.ZPLANE)
[2, 3, 4, 5, 6]
>>> data, axes = stack.get_slice({Axes.ZPLANE: 6})
>>> data.shape
(3, 4, 20, 10)
>>> axes
[<Axes.ROUND: 'r'>, <Axes.CH: 'c'>]
Slicing with a range
>>> from starfish import ImageStack
>>> from starfish.core.imagestack.test.factories import synthetic_stack
>>> from starfish.types import Axes
>>> stack = synthetic_stack(3, 4, 5, 20, 10)
>>> stack.shape
OrderedDict([(<Axes.ROUND: 'r'>, 3),
 (<Axes.CH: 'c'>, 4),
 (<Axes.ZPLANE: 'z'>, 5),
 ('y', 20),
 ('x', 10)])
>>> stack.axis_labels(Axes.ROUND)
[0, 1, 2]
>>> stack.axis_labels(Axes.CH)
[0, 1, 2, 3]
>>> stack.axis_labels(Axes.ZPLANE)
[2, 3, 4, 5, 6]
>>> data, axes = stack.get_slice({Axes.ZPLANE: 5, Axes.CH: slice(2, 4)})
>>> data.shape
(3, 2, 20, 10)
>>> axes
[<Axes.ROUND: 'r'>, <Axes.CH: 'c'>]
Return type

Tuple[ndarray, Sequence[Axes]]

isel(indexers)[source]

Given a dictionary mapping the index name to either a value or a range represented as a tuple, return an Imagestack with each dimension indexed by position accordingly

Parameters
indexersDict[Axes, Union[int, Sequence]]

A dictionary of dim:index where index is the value, values, or range to index the dimension

Returns
ImageStack :

a new image stack indexed by given value or range.

Examples

Create an Imagestack using the synthetic_stack method
>>> from starfish import ImageStack
>>> from starfish.types import Axes
>>> stack = ImageStack.synthetic_stack(5, 5, 15, 200, 200)
>>> stack
<starfish.ImageStack (r: 5, c: 5, z: 15, y: 200, x: 200)>
>>> stack.isel({Axes.ROUND: (1, None), Axes.CH: 0, Axes.ZPLANE: 0})
<starfish.ImageStack (r: 4, c: 1, z: 1, y: 200, x: 200)>
>>> stack.isel({Axes.ROUND: 0, Axes.CH: 0, Axes.ZPLANE: 1,
...Axes.Y: 100, Axes.X: (None, 100)})
<starfish.ImageStack (r: 1, c: 1, z: 1, y: 1, x: 100)>
and the imagestack's physical coordinates
xarray also indexed and recalculated according to the x,y slicing.
property log

Returns a list of pipeline components that have been applied to this imagestack as well as their corresponding runtime parameters.

For more information about provenance logging see Provenance Logging

Returns
List[dict]
Return type

Log

map(func, module=None, in_place=False, group_by=None, level_method=<Levels.CLIP: 'clip'>, *args, **kwargs)[source]

Maps the contents of the ImageStack to produce another image. This can be done in-place or can produce a new ImageStack. This is a shortcut for starfish.image.Filter.Map.

Return type

Optional[ImageStack]

max_proj(*dims)[source]

This method is deprecated. Please ImageStack.reduce(axes, func="max") to do max projection operations.

Return type

ImageStack

property num_chs

Return the number of channels in the ImageStack

property num_rounds

Return the number of rounds in the ImageStack

property num_zplanes

Return the number of z_planes in the ImageStack

property raw_shape

Returns the shape of the 5-d image tensor stored as self.image

Returns
Tuple[int, int, int, int, int] :

The size of the image tensor

Return type

Tuple[int, int, int, int, int]

reduce(dims, func, module=None, level_method=<Levels.CLIP: 'clip'>, *args, **kwargs)[source]

Reduces the dimensionality of the ImageStack and returns a new ImageStack with the result. This is a shortcut for starfish.image.Filter.Reduce.

Return type

ImageStack

sel(indexers)[source]

Given a dictionary mapping the index name to either a value or a range represented as a tuple, return an Imagestack with each dimension indexed accordingly

Parameters
indexersMapping[Axes, Union[int, Union[int, Sequence]]

A dictionary of dim:index where index is the value, values, or range to index the dimension

Returns
ImageStack :

a new image stack indexed by given value or range.

Examples

Create an Imagestack synthetic_stack()
>>> from starfish import ImageStack
>>> from starfish.core.imagestack.test.factories import synthetic_stack
>>> from starfish.types import Axes
>>> stack = synthetic_stack(5, 5, 15, 200, 200)
>>> stack
<starfish.ImageStack (r: 5, c: 5, z: 15, y: 200, x: 200)>
>>> stack.sel({Axes.ROUND: (1, None), Axes.CH: 0, Axes.ZPLANE: 0})
<starfish.ImageStack (r: 4, c: 1, z: 1, y: 200, x: 200)>
>>> stack.sel({Axes.ROUND: 0, Axes.CH: 0, Axes.ZPLANE: 1,
...Axes.Y: 100, Axes.X: (None, 100)})
<starfish.ImageStack (r: 1, c: 1, z: 1, y: 1, x: 100)>
and the imagestack's physical coordinates
xarray also indexed and recalculated according to the x,y slicing.
sel_by_physical_coords(indexers)[source]

Given a dictionary mapping the coordinate name to either a value or a range represented as a tuple, return an Imagestack with each the Coordinate dimension indexed accordingly.

Parameters
indexersMapping[Coordinates, CoordinateValue]:

A dictionary of coord:index where index is the value or range to index the coordinate dimension.

Returns
ImageStack :

a new image stack indexed by given value or range.

set_slice(selector, data, axes=None, from_loader=False)[source]

Given a dictionary mapping the index name to either a value or a slice range and a source numpy array, set the slice of the array of this ImageStack to the values in the source numpy array.

Consumers of this API should not be aware of the internal order of the axes in ImageStack. As a result, they should be explicitly providing the order of the axes of the numpy array. This method will reorder the data to the internal order of the axes in ImageStack before writing it.

Parameters
selectorMapping[Axes, Union[int, slice]]

The slice of the data we are writing with this operation. Each index should map to a value or a range. If the index is not present, we are writing to the entire range along that index.

datanp.ndarray

a 2- to 5-D numpy array containing the source data for the operation whose last two axes must be in (Y, X) order. If data larger than 2-D is provided, axes must be set to specify the order of the additional axes (see below).

axesOptional[Sequence[Axes]]

The order of the axes for the source data, excluding (Y, X). Optional ONLY if data is a (Y, X) 2-d tile.

Examples

Setting a slice indicated by scalars.

>>> import numpy as np
>>> from starfish import ImageStack
>>> from starfish.core.imagestack.test.factories import synthetic_stack
>>> from starfish.types import Axes
>>> stack = synthetic_stack(3, 4, 5, 20, 10)
>>> stack.shape
OrderedDict([(<Axes.ROUND: 'r'>, 3),
 (<Axes.CH: 'c'>, 4),
 (<Axes.ZPLANE: 'z'>, 5),
 ('y', 20),
 ('x', 10)])
>>> new_data = np.zeros((3, 4, 10, 20), dtype=np.float32)
>>> stack.set_slice(new_data, axes=[Axes.ROUND, Axes.CH]

Setting a slice indicated by scalars. The data presented has a different axis order than the previous example.

>>> import numpy as np
>>> from starfish import ImageStack
>>> from starfish.core.imagestack.test.factories import synthetic_stack
>>> from starfish.types import Axes
>>> stack = synthetic_stack(3, 4, 5, 20, 10)
>>> stack.shape
OrderedDict([(<Axes.ROUND: 'r'>, 3),
 (<Axes.CH: 'c'>, 4),
 (<Axes.ZPLANE: 'z'>, 5),
 ('y', 20),
 ('x', 10)])
>>> new_data = np.zeros((4, 3, 10, 20), dtype=np.float32)
>>> stack.set_slice(new_data, axes=[Axes.CH, Axes.ROUND]

Setting a slice indicated by a range.

>>> from starfish import ImageStack
>>> from starfish.core.imagestack.test.factories import synthetic_stack
>>> from starfish.types import Axes
>>> stack = synthetic_stack(3, 4, 5, 20, 10)
>>> stack.shape
OrderedDict([(<Axes.ROUND: 'r'>, 3),
 (<Axes.CH: 'c'>, 4),
 (<Axes.ZPLANE: 'z'>, 5),
 ('y', 20),
 ('x', 10)])
>>> new_data = np.zeros((3, 2, 10, 20), dtype=np.float32)
>>> stack.set_slice({Axes.ZPLANE: 5, Axes.CH: slice(2, 4)}, new_data)
property shape

Returns the shape of the space that this image inhabits. It does not include the dimensions of the image itself. For instance, if this is an X-Y image in a C-H-Y-X space, then the shape would include the axes C and H.

Returns
An ordered mapping between index names to the size of the index.
Return type

OrderedDict

property tile_metadata

return a table containing Tile metadata

Returns
pd.DataFrame :

dataframe containing per-tile metadata information for each image. Guaranteed to include information on channel, imaging round, z plane, and barcode index. Also contains any information stored in the extras field for each tile.

Return type

DataFrame

property tile_shape

Return the shape of each tile in the ImageStack. All Tiles have the same shape.

to_multipage_tiff(filepath)[source]

save the ImageStack as a FIJI-compatible multi-page TIFF file

Parameters
filepathstr

filepath for a tiff FILE. “TIFF” suffix will be added if the provided path does not end with .TIFF

Return type

None

transform(func, *args, group_by=None, verbose=False, n_processes=None, **kwargs)[source]

Split the image along a set of axes, and apply a function across all the components.

Parameters
funcCallable

Function to apply. must expect a first argument which is a numpy array (see group_by) but may return any object type.

group_bySet[Axes]

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

verbosebool

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

n_processesOptional[int]

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

kwargsdict

Additional arguments to pass to func being applied

Returns
List[Any] :

The results of applying func to stored image data

Return type

List[Any]

property xarray

Retrieves the image data as an xarray.DataArray

Return type

DataArray