API

metaspace_converter

metaspace_converter.anndata_to_image_array(adata, layer=None)[source]

Extracts an array of ion images from an AnnData object (that has been generated through the metaspace_to_anndata function).

Parameters:

adata (AnnData) – An AnnData object.
layer (Optional[str]) – AnnData.layer that should be extracted to an image array. Default is None, which means that adata.X will be used.

Return type:

ndarray

Returns:

A three-dimensional Numpy array in the following shape

Dimension 0: Number of ion images in the order of adata.var_names

Dimension 1: Image height adata.uns["metaspace"]["image_size"]["y"]

Dimension 2: Image width adata.uns["metaspace"]["image_size"]["x"]

Raises:

ValueError – If the AnnData object has been modified. E.g. Pixel have been removed/added and the number of pixels and their coordinates do not match the original image dimensions.

metaspace_converter.metaspace_to_anndata(dataset=None, dataset_id=None, database=None, fdr=0.1, use_tic=False, metadata_as_obs=False, add_optical_image=False, sm=None, **annotation_filter)[source]

Downloads a METASPACE dataset to an AnnData object.

See: https://metaspace2020.eu/about

Parameters:

dataset (Optional[SMDataset]) – A METASPACE dataset instance. If not provided, the dataset_id must be given.
dataset_id (Optional[str]) – The unique ID of a dataset on METASPACE, e.g. “2021-09-03_11h43m13s”
database (Optional[tuple[str, str]]) – A single METASPACE database given as a tuple of name and version. Usually it is displayed on METASPACE as “HMDB – v4” which corresponds to (“HMDB”, “v4”).
fdr (Optional[float]) – Returns only annotations for which the false discovery rate is less or equal to this limit.
use_tic (bool) – When True, the output values will be scaled by the total ion count per pixel and will be in 0.0 to 1.0 range.
metadata_as_obs (bool) – Whether to store metadata in the obs dataframe instead of uns. For a single METASPACE dataset, metadata is the same for all pixels, so it would be duplicated for all obs. When combining multiple datasets, it would be preserved in obs but not in uns.
add_optical_image (bool) – Whether to embed the optical image for SquidPy
sm (Optional[SMInstance]) – Optionally a cached SMInstance
annotation_filter – Additional keyword arguments passed to the METASPACE API.

Return type:

AnnData

Returns:

An AnnData object with

ion intensities: .X
ion image pixel coordinates: .obs[["ion_image_pixel_x", "ion_image_pixel_y"]]
spatial coordinates: .obsm["spatial"]
ion properties: .var, for example “formula”, “adduct”, “mz”, “fdr”, “moleculeNames”, “moleculeIds”, “intensity”…
METASPACE metadata: .uns["metaspace"] if not metadata_as_obs
SquidPy metadata: .uns["spatial"] if add_optical_image

Raises:

ValueError – If something is wrong with the input data or parameters
metaspace.sm_annotation_utils.DatasetNotFound – If the dataset ID is not found
ConnectionError – For any other network connectivity problems

metaspace_converter.metaspace_to_spatialdata(dataset=None, dataset_id=None, database=None, fdr=0.1, use_tic=False, metadata_as_obs=False, add_optical_image=True, optical_name_added='optical_image', add_points=True, points_name_added='maldi_points', sm=None, **annotation_filter)[source]

Download a METASPACE dataset as a SpatialData object.

See: https://metaspace2020.eu/about

Parameters:

dataset (Optional[SMDataset]) – A METASPACE dataset instance. If not provided, the dataset_id must be given.
dataset_id (Optional[str]) – The unique ID of a dataset on METASPACE, e.g. “2021-09-03_11h43m13s”
database (Optional[tuple[str, str]]) – A single METASPACE database given as a tuple of name and version. Usually it is displayed on METASPACE as “HMDB – v4” which corresponds to ("HMDB", "v4").
fdr (float) – Returns only annotations for which the false discovery rate is less or equal to this limit.
use_tic (bool) – When True, the output values will be scaled by the total ion count per pixel and will be in 0.0 to 1.0 range.
metadata_as_obs (bool) – Whether to store metadata in the obs dataframe instead of uns. For a single METASPACE dataset, metadata is the same for all pixels, so it would be duplicated for all obs. When combining multiple datasets, it would be preserved in obs but not in uns.
add_optical_image (bool) – Whether to also add the optical image (if one exists) to SpatialData images. If none exists, it is not added, and no error raised.
optical_name_added (str) – Name of the element where to store the image in the SpatialData object
add_points (bool) – Whether to also add ion image pixel coordinates as SpatialData points. This allows to spatially visualize the ion image values. If False, only ion intensities are added to the table and coordinates are added to obs.
points_name_added (str) – Name of the element where to store the points in the SpatialData object
sm (Optional[SMInstance]) – Optionally a cached SMInstance
annotation_filter – Additional keyword arguments passed to the METASPACE API.

Return type:

SpatialData

Returns:

A SpatialData object with

ion intensities and metadata: .table
optical image: .images["optical_image"] (or optical_name_added)
sampling coordinates: .points["maldi_points"] (or points_name_added) in a coordinate system relative to the top-left image corner and physical scale (micrometers)

Raises:

ValueError – If something is wrong with the input data or parameters
metaspace.sm_annotation_utils.DatasetNotFound – If the dataset ID is not found
ConnectionError – For any other network connectivity problems

metaspace_converter.colocalization

metaspace_converter.colocalization.coloc_ml_preprocessing(adata, layer='coloc_ml_preprocessing', median_filter_size=(3, 3), quantile_threshold=0.5)[source]

Preprocessing for colocalization analysis according to the colocML publication (https://doi.org/10.1093/bioinformatics/btaa085).

In the publication, the authors evaluated colocalization metrics and preprocessing approaches. They found the best performance for

median filtering of ion images with a (3, 3) kernel size and
quantile thresholding at 50%, meaning all pixels with intensities below the 50% quantile set to 0.

This function performs the same preprocessing steps. Recommended for call before running the colocalization function.

Parameters:

adata (AnnData) – An AnnData object.
layer (Optional[str]) – Key for the adata.layers dict in which the processed data will be saved. Default value is colocml_preprocessing. If None, adata.X will be overwritten with the processed data.
median_filter_size (Tuple[int, int]) – 2-dimensional filter size for the median filtering that will be performed per ion image.
quantile_threshold (float) – Float between 0 and 1. The function computes the quantile value per ion image and all pixels below the quantile threshold will be set to 0.

Returns:

None. The processed data is saved in layer. If layer is set to None, adata.X will be overwritten

Raises:

ValueError – If no annotations are available in adata.X.

metaspace_converter.colocalization.colocalization(adata, layer='coloc_ml_preprocessing')[source]

Colocalization of ion images using the cosine similarity metric.

In combination with the colocML_preprocessing function, this metric performed best in the colocML publication (https://doi.org/10.1093/bioinformatics/btaa085).

It is recommended to call the coloc_ml_preprocessing function beforehand.

Parameters:

adata (AnnData) – An AnnData object.
layer (Optional[str]) – Key for adata.layer from which the ionimage_data for preprocessing taken. If None, adata.X is used. coloc_ml_preprocessing will save the preprocessed data per default in adata.layer['coloc_ml_preprocessing'].

Returns:

None. The processed data is saved in adata.varp['colocalization'].

Raises:

ValueError – If layer is not found in adata.layers.