Data Formatting

Classes and functions for converting data to SpaceTx Format and building experiments.

Converting Structured Data

Format Structured Data tutorial.

from starfish.experiment.builder import format_structured_dataset
starfish.core.experiment.builder.structured_formatter.format_structured_dataset(image_directory_path_str:str, physical_coordinates_csv_path_str:str, output_experiment_dir_str:str, tile_format:slicedimage._formats.ImageFormat, in_place:bool=False) → None[source]

Format a dataset where the filenames of the tiles provide most of the metadata required to organize them into the 7D tensor (image_type, fov, round, ch, zplane, y, x). The remaining metadata, namely physical coordinates of the tiles, are provided in a CSV file.

See the documentation in Format Structured Data


The path of the directory where the image tiles are found.


The path of the csv file containing the physical coordinates.


The path of the directory to write the experiment to. The top-level experiment json will be located at <output_experiment_dir_str>/experiment.json


The format of the tiles that are written. Note that this must match the format of the original files if in_place is True.


When this is true, the original tiles are used in the resulting experiment.json. (default: False)

Return type


Tile Fetcher Interface

Formatting with TileFetcher tutorial and Loading Data through TileFetchers tutorial.

from starfish.experiment.builder import FetchedTile, TileFetcher, write_experiment_json

This module describes the contracts to provide data to the experiment builder.

class starfish.core.experiment.builder.providers.FetchedTile(*args, **kwargs)[source]

This is the contract for providing the data for constructing a slicedimage.Tile.

property coordinates

Return the tile’s coordinates in the global coordinate space..

Mapping[Union[str, Coordinates], CoordinateValue]

Maps from a coordinate type (e.g. ‘x’, ‘y’, or ‘z’) to its value or range.

Return type

Mapping[Union[str, Coordinates], Union[int, float, Tuple[Union[int, float], Union[int, float]]]]

property extras

Return the extras data associated with the tile.

Mapping[str, Any]

Maps from a key to its value.

Return type


property shape

Return Tile shape.

Mapping[Axis, int]

The shape of the tile, mapping from Axes to its size.

Return type

Mapping[Axes, int]

tile_data(self) → numpy.ndarray[source]

Return the image data representing the tile. The tile must be row-major.

ndarray :

The image data

Return type


class starfish.core.experiment.builder.providers.TileFetcher[source]

This is the contract for providing the image data for constructing a slicedimage.Collection.

get_tile(self, fov_id:int, round_label:int, ch_label:int, zplane_label:int) → starfish.core.experiment.builder.providers.FetchedTile[source]

Given fov_id, round_label, ch_label, and zplane_label, return an instance of a FetchedTile that can be queried for the image data.

Return type


starfish.core.experiment.builder.builder.write_experiment_json(path:str, fov_count:int, tile_format:slicedimage._formats.ImageFormat, *, primary_image_dimensions:Mapping[Union[str, starfish.core.types._constants.Axes], int], aux_name_to_dimensions:Mapping[str, Mapping[Union[str, starfish.core.types._constants.Axes], int]], primary_tile_fetcher:Union[starfish.core.experiment.builder.providers.TileFetcher, NoneType]=None, aux_tile_fetcher:Union[Mapping[str, starfish.core.experiment.builder.providers.TileFetcher], NoneType]=None, postprocess_func:Union[Callable[[dict], dict], NoneType]=None, default_shape:Union[Mapping[starfish.core.types._constants.Axes, int], NoneType]=None, dimension_order:Sequence[starfish.core.types._constants.Axes]=(<Axes.ZPLANE: 'z'>, <Axes.ROUND: 'r'>, <Axes.CH: 'c'>), fov_path_generator:Union[Callable[[pathlib.Path, str], pathlib.Path], NoneType]=None, tile_opener:Union[Callable[[pathlib.Path, slicedimage._tile.Tile, str], BinaryIO], NoneType]=None, writer_contract:Union[, NoneType]=None) → None[source]

Build and returns a top-level experiment description with the following characteristics:


Directory to write the files to.


Number of fields of view in this experiment.


File format to write the tiles as.

primary_image_dimensionsMapping[Union[str, Axes], int]

Dictionary mapping dimension name to dimension size for the primary image.

aux_name_to_dimensionsMapping[str, Mapping[Union[str, Axes], int]]

Dictionary mapping the auxiliary image type to dictionaries, which map from dimension name to dimension size.


TileFetcher for primary images. Set this if you want specific image data to be set for the primary images. If not provided, the image data is set to random noise via RandomNoiseTileFetcher.

aux_tile_fetcherOptional[Mapping[str, TileFetcher]]

TileFetchers for auxiliary images. Set this if you want specific image data to be set for one or more aux image types. If not provided for any given aux image, the image data is set to random noise via RandomNoiseTileFetcher.

postprocess_funcOptional[Callable[[dict], dict]]

If provided, this is called with the experiment document for any postprocessing. An example of this would be to add something to one of the top-level extras field. The callable should return what is to be written as the experiment document.

default_shapeOptional[Tuple[int, int]] (default = None)

Default shape for the tiles in this experiment.


Ordering for which dimensions vary, in order of the slowest changing dimension to the fastest. For instance, if the order is (ROUND, Z, CH) and each dimension has size 2, then the sequence is: (ROUND=0, CH=0, Z=0) (ROUND=0, CH=1, Z=0) (ROUND=0, CH=0, Z=1) (ROUND=0, CH=1, Z=1) (ROUND=1, CH=0, Z=0) (ROUND=1, CH=1, Z=0) (ROUND=1, CH=0, Z=1) (ROUND=1, CH=1, Z=1) (default = (Axes.Z, Axes.ROUND, Axes.CH))

fov_path_generatorOptional[Callable[[Path, str], Path]]

Generates the path for a FOV’s json file. If one is not provided, the default generates the FOV’s json file at the same level as the top-level json file for an image. If this is not provided, a reasonable default will be provided. If this is provided, writer_contract should not be provided.

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

Callable that gets invoked with the following arguments: 1. the directory of the experiment that is being constructed, 2. the tile that is being written, and 3. the file extension that the tile should be written with. The callable is expected to return an open file handle. If this is not provided, a reasonable default will be provided. If this is provided, writer_contract should not be provided.


Contract for specifying how the slicedimage image is to be laid out. If this is provided, fov_path_generator and tile_opener should not be provided.

Return type