BaseImagingDataset#

class spora_io.datasets.base.BaseImagingDataset(name, modality, resolution, path=None, tile_size=None, load_cell_metadata=False, verbose=True, label=None, labels_to_keep=None, label_modifying_fn=None, label_type='classification', tile_strategy=None, split=None)[source]#

Bases: ABC

Base class for all imaging datasets.

Parameters:

name (str)
modality (ModKey)
resolution (float | str)
path (os.PathLike | str | None)
tile_size (Optional[int])
load_cell_metadata (bool)
verbose (bool)
label (Optional[str])
labels_to_keep (Optional[Sequence[str]])
label_modifying_fn (Optional[Callable])
label_type (str)
tile_strategy (Optional[str])
split (Optional[str])

name#

The name of the dataset.

Type:: str

path#

The root path to the dataset. If omitted, this resolves to SPORA_DATASETS_DIR / name.

Type:: Path

modality#

The modality of the dataset.

Type:: ModKey

resolution#

The resolution of the dataset in mpp, formatted as a string with underscores instead of decimals (e.g. “0_5mpp”).

Type:: str

tile_size#

The tile size in pixels. If None, tiling functionality will be disabled.

Type:: Optional[int]

tile_strategy#

The tiling strategy used for the dataset. If None, defaults to “default”. This is used to determine the subdirectory under tiling/<resolution>/ where tile coordinates are stored.

Type:: Optional[str]

label#

The name of the label column in the tissue metadata. If None, no labels will be loaded.

Type:: Optional[str]

labels_to_keep#

The list of label values to keep if label is not None. If None, all labels will be kept.

Type:: Optional[Sequence[str]]

label_modifying_fn#

A function to modify the labels after loading. For example, this can be used to binarize labels or group certain labels together. If None, labels will not be modified.

Type:: Optional[Callable]

label_type#

The type of the label, either “classification” or “regression”. This is used to determine how to encode the labels. Default is “classification”.

Type:: str

get_tissue_ids(kind='modality')[source]#

Get the unique tissue IDs from the tissue annotations.

Parameters:: kind (str) – The kind of tissue IDs to retrieve. Default is “modality”, which returns tissue ids for tissues that have the specified modality. If “all”, returns tissue ids for all tissues in the dataset.
Returns:: numpy.ndarray: An array of unique tissue IDs.

abstractmethod get_tissue(tissue_id, kind='complete', preprocess=True, image_mode='CHW')[source]#

Get a tissue image by tissue ID.

Subclasses define the valid kind values and preprocessing behavior.

Parameters:

tissue_id (str)
preprocess (bool)
image_mode (str)

Returns:

~spora_io.datasets._types.HETissue | ~spora_io.datasets._types.MultiplexTissue | ~spora_io.datasets._types.IHCTissue

get_tissue_mask(tissue_id)[source]#

Get the tissue mask for a given tissue id. If the tissue masks directory does not exist, return a full mask.

Parameters:: tissue_id (str) – The tissue ID to retrieve the mask for.
Returns:: TissueMask: The tissue mask as a TissueMask instance.

abstractmethod get_tile(tissue_id, tile_id, kind='complete', image_mode='CHW', preprocess=True)[source]#

Get a specific tile based on the tissue id and tile id. Tile IDs are precomputed during tiling. If tile coordinates are not available, this method should return a random tile from the tissue image. Subclasses that implement tiling should override this method to load the tile based on the precomputed tile coordinates.

Parameters:

tissue_id (str) – The tissue ID to retrieve the tile for.
tile_id (int) – The tile ID to retrieve.
kind (str) – The kind of tile image to retrieve. Default is “complete”.
image_mode (str) – The image mode of the tile image. Valid options are “CHW” and “HWC”. Default is “CHW”.
preprocess (bool) – Whether to preprocess the tile image (e.g. normalize) before returning it. Default is True.

Returns:

Tissue: The tile image as a Tissue instance.

abstractmethod get_tile_by_coordinates(tissue_id, row, col, kind='complete', image_mode='CHW', preprocess=True)[source]#

Get a specific tile based on the tissue id and tile coordinates. This method is used when tile coordinates are not precomputed and get_tile should return a random tile.

Parameters:

tissue_id (str) – The tissue ID to retrieve the tile for.
row (int) – The row coordinate of the tile.
col (int) – The column coordinate of the tile.
kind (str) – The kind of tile image to retrieve. Default is “complete”.
image_mode (str) – The image mode of the tile image. Valid options are “CHW” and “HWC”. Default is “CHW”.
preprocess (bool) – Whether to preprocess the tile image (e.g. normalize) before returning it. Default is True.

Returns:

Tissue: The tile image as a Tissue instance.

get_cell_instance_mask(tissue_id, use_instances_from_virtues=False)[source]#

Get the cell instance mask for a given tissue id.

Parameters:

tissue_id (str) – The tissue ID to retrieve the cell instance mask for.
use_instances_from_virtues (bool) – Whether to use instances generated using the VirTues foundation model.

Returns:

CellMask: The cell instance mask as a CellMask instance.

get_cell_task_mask(tissue_id, mask_type)[source]#

Get the cell task mask for a given tissue id and mask type.

Parameters:

tissue_id (str) – The tissue ID to retrieve the cell task mask for.
mask_type (str) – The type of cell task mask to retrieve. Valid options can be retrieved from get_cell_task_mask_types method.

Returns:

CellMask: The cell task mask as a CellMask instance.

get_cell_task_mask_types()[source]#

Get the available cell task mask types for the dataset.

Returns:: Sequence[str]: A list of available cell task mask types.

get_tissue_by_patient(patient_id, kind='complete', preprocess=True, image_mode='CHW')[source]#

Get all tissue images associated with a patient ID.

Parameters:

patient_id (str)
preprocess (bool)
image_mode (str)

Returns:

~typing.Sequence[~spora_io.datasets._types.HETissue | ~spora_io.datasets._types.MultiplexTissue | ~spora_io.datasets._types.IHCTissue]