MultiplexImagingDataset#

class spora_io.datasets.multiplex.MultiplexImagingDataset(name, modality, standardization, resolution, path=None, tile_size=None, verbose=True, load_cell_metadata=False, disable_quantile_mask=False, filter_list=None, use_mean_std=True, return_uniprot_ids=True, replace_nuclear_uniprot_ids=False, tile_strategy=None, split=None, **kwargs)[source]#

Bases: BaseImagingDataset

Class for handling multiplex imaging datasets.

Parameters:

  • name (str)

  • modality (str)

  • standardization (str)

  • resolution (float | str)

  • path (os.PathLike | str | None)

  • tile_size (Optional[int])

  • verbose (bool)

  • load_cell_metadata (bool)

  • disable_quantile_mask (bool)

  • filter_list (List[str] | None)

  • use_mean_std (bool)

  • return_uniprot_ids (bool)

  • replace_nuclear_uniprot_ids (bool)

  • tile_strategy (Optional[str])

  • split (Optional[str])

VALID_MODALITIES#

A set of valid modalities for multiplex imaging datasets. Valid options are “imc”, “codex”, and “cycif”.

Type:

set

standardization#

The type of standardization to apply to the images. This is passed to the build_standardizer function to create a standardizer instance.

Type:

str

disable_quantile_mask#

Quantile masking will search for channels with 0 quantile / variance and exclude them from standardization. Setting this to True will disable this behavior and include all channels in standardization. This is passed to the build_standardizer function.

Type:

bool

filter_list#

A list of filter names to apply to the dataset. Currently supported filters are “gaussian_blur” and “median_filter”. These are applied sequentially, and the parameters for each filter can be specified in the filter_params dictionary in kwargs, with the filter name as the key and the parameters as a dictionary of parameters for that filter.

Type:

List[str]

use_mean_std#

Whether to use mean and standard deviation for standardization. If False, only quantile normalization will be applied if not disabled. This is passed to the build_standardizer function.

Type:

bool

return_uniprot_ids#

Whether to return uniprot IDs for the channels. This requires a “uniprot_id” column in the channels.parquet file. If this column is not present, uniprot IDs will not be returned regardless of this setting.

Type:

bool

replace_nuclear_uniprot_ids#

Whether to replace UniProt IDs for channels flagged with is_nuclear_marker with Histone H3’s UniProt ID (P68431). This lets nuclear markers participate in uniprot_filtered loading even when the source channel lacks a protein-specific UniProt ID.

Type:

bool

get_channel_names(tissue_id, kind='complete', measured_mask=None, qc_mask=None, filtered_mask=None)[source]#

Get the channel names for a given tissue id and kind.

Parameters:

  • tissue_id (str) – The tissue ID to retrieve the channel names for.

  • kind (str) – The kind of tissue image to retrieve channel names for. Valid options are “complete”, “qc_filtered”, and “uniprot_filtered”.

  • measured_mask (np.ndarray | None) – A boolean array indicating which channels are measured for the given tissue. If None, it will be retrieved from the image_channel_map. This is used to determine which channels to consider when applying the kind filtering.

  • qc_mask (np.ndarray | None) – A boolean array indicating which channels pass quality control for the given tissue. If None, it will be computed from the quality_control_mask and measured_mask. This is used when kind is “qc_filtered” or “uniprot_filtered” to determine which channels to include.

  • filtered_mask (np.ndarray | None) – A boolean array indicating which channels have valid UniProt IDs for the given tissue. If None, it will be computed from the uniprot_mask and qc_mask. This is used when kind is “uniprot_filtered” to determine which channels to include.

Returns:

numpy.ndarray: The channel names as a 1D array of shape (n_channels,).

get_uniprot_ids(tissue_id, kind='complete', measured_mask=None, qc_mask=None, filtered_mask=None)[source]#

Get the uniprot IDs for a given tissue id and kind. This will return None if return_uniprot_ids is False or if there are no valid uniprot IDs for the given kind.

Parameters:

  • tissue_id (str) – The tissue ID to retrieve the uniprot IDs for.

  • kind (str) – The kind of tissue image to retrieve uniprot IDs for. Valid options are “complete”, “qc_filtered”, and “uniprot_filtered”.

  • measured_mask (np.ndarray | None) – A boolean array indicating which channels are measured for the given tissue. If None, it will be retrieved from the image_channel_map. This is used to determine which channels to consider when applying the kind filtering.

  • qc_mask (np.ndarray | None) – A boolean array indicating which channels pass quality control for the given tissue. If None, it will be computed from the quality_control_mask and measured_mask. This is used when kind is “qc_filtered” or “uniprot_filtered” to determine which channels to include.

  • filtered_mask (np.ndarray | None) – A boolean array indicating which channels have valid UniProt IDs for the given tissue. If None, it will be computed from the uniprot_mask and qc_mask. This is used when kind is “uniprot_filtered” to determine which channels to include.

Returns:

numpy.ndarray | None: The UniProt IDs as a 1D array of shape (n_channels,). Returns None if return_uniprot_ids is False.

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

Get the tissue image for a given tissue id, with options for filtering channels and preprocessing.

Parameters:

  • tissue_id (str) – The tissue ID to retrieve the image for.

  • kind (str) – The kind of tissue image to retrieve. Valid options are “complete”, “qc_filtered”, and “uniprot_filtered”. Default is “uniprot_filtered”.

  • preprocess (bool) – Whether to preprocess the image using the standardizer. Default is True.

  • image_mode (str) – The image mode of the tissue image. Valid options are “CHW” and “HWC”. Default is “CHW”.

Returns:

MultiplexTissue: The tissue image as a MultiplexTissue instance.

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

Get a specific tile based on the tissue id and tile row and column coordinates.

Parameters:

  • tissue_id (str) – The tissue ID to retrieve the tile for.

  • row (int) – The row coordinate of the top-left corner of the tile.

  • col (int) – The column coordinate of the top-left corner of the tile.

  • preprocess (bool) – Whether to preprocess the tile using the standardizer. Default is True.

  • kind (str) – The kind of tissue image to retrieve for the tile. Valid options are “complete”, “qc_filtered”, and “uniprot_filtered”. Default is “uniprot_filtered”.

  • image_mode (str) – The image mode of the tissue image. Valid options are “CHW” and “HWC”. Default is “CHW”.

Returns:

MultiplexTissue: The specific tile as a MultiplexTissue instance.

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

Get a specific tile based on the tissue id and tile id

Parameters:

  • tissue_id (str) – The tissue ID to retrieve the tile for.

  • tile_id (int) – The tile ID to retrieve.

  • preprocess (bool) – Whether to preprocess the tile using the standardizer. Default is True.

  • kind (str) – The kind of tissue image to retrieve for the tile. Valid options are “complete”, “qc_filtered”, and “uniprot_filtered”. Default is “uniprot_filtered”.

  • image_mode (str) – The image mode of the tissue image. Valid options are “CHW” and “HWC”. Default is “CHW”.

Returns:

MultiplexTissue: The specific tile as an MultiplexTissue instance.