mudata.MuData

mudata.MuData#

class mudata.MuData(data=None, feature_types_names=mappingproxy({'Gene Expression': 'rna', 'Peaks': 'atac', 'Antibody Capture': 'prot'}), as_view=False, index=None, **kwargs)#

Multimodal data object

MuData represents modalities as collections of AnnData objects as well as includes multimodal annotations such as embeddings and neighbours graphs learned jointly on multiple modalities and generalised sample and feature metadata tables.

Parameters:

  • data (AnnData | Mapping[str, AnnData] | MuData | None (default: None)) – AnnData object or dictionary with AnnData objects as values. If a dictionary is passed, the keys will be used as modality names. If None, creates an empty MuData object.

  • feature_types_names (Mapping[str, str] | None (default: mappingproxy({'Gene Expression': 'rna', 'Peaks': 'atac', 'Antibody Capture': 'prot'}))) – Dictionary to map feature types encoded in data.var[“feature_types”] to modality names. Only relevant when data is an AnnData object. Default: {“Gene Expression”: “rna”, “Peaks”: “atac”, “Antibody Capture”: “prot”}

  • as_view (bool (default: False)) – Create a view of the MuData object.

  • index (tuple[slice | int, slice | int] | slice | int | None (default: None)) – Index to slice the MuData object when creating the view.

  • **kwargs – Additional arguments to create a MuData object.

Attributes table#

axis

MuData axis.

filename

Change the backing mode by setting the filename to a .h5mu file.

is_view

Whether the object is a view of another MuData object.

isbacked

Whether the object is backed on disk.

mod

Dictionary of modalities.

mod_names

Names of modalities (alias for list(mdata.mod.keys()))

n_mod

Number of modalities.

n_obs

Total number of observations

n_var

Total number of variables.

n_vars

Total number of variables.

obs

Annotation of observation

obs_names

Names of variables (alias for .obs.index).

obsm

Multi-dimensional annotation of observations.

obsmap

Mapping of observation indices in the object to indices in individual modalities.

obsp

Pairwise annotatation of observations.

shape

Shape of data, all variables and observations combined (n_obs, n_vars).

uns

Unstructured annotation (ordered dictionary).

var

Annotation of variables.

var_names

Names of variables (alias for .var.index)

varm

Multi-dimensional annotation of variables.

varmap

Mapping of feature indices in the object to indices in individual modalities.

varp

Pairwise annotatation of variables.

Methods table#

copy([filename])

Make a copy.

obs_keys()

List keys of observation annotation obs.

obs_names_make_unique()

Call AnnData.obs_names_make_unique on each modality.

obs_vector(key[, layer])

Return an array of values for the requested key of length n_obs.

obsm_keys()

List keys of observation annotation obsm.

pull_obs([columns, mods, common, ...])

Copy data from the obs of the modalities to the global obs

pull_var([columns, mods, common, ...])

Copy data from the var of the modalities to the global var

push_obs([columns, mods, common, prefixed, ...])

Copy the data from obs to the obs of the modalities.

push_var([columns, mods, common, prefixed, ...])

Copy the data from var to the var of the modalities.

strings_to_categoricals([df])

Transform string annotations to categoricals.

to_anndata(**kwargs)

Convert the object to AnnData.

uns_keys()

List keys of unstructured annotation.

update()

Update both obs and var indices of the object with the data from all the modalities.

update_obs()

Update obs indices of the object with the data from all the modalities.

update_var()

Update var indices of the object with the data from all the modalities.

var_keys()

List keys of variable annotation var.

var_names_make_unique()

Call AnnData.var_names_make_unique on each modality.

var_vector(key[, layer])

Return an array of values for the requested key of length n_var.

varm_keys()

List keys of variable annotation varm.

write([filename])

Write the object to an HDF5 file.

write_h5mu([filename])

Write the object to an HDF5 file.

write_zarr(store, **kwargs)

Write the object to a Zarr store.

Attributes#

property axis: Literal[-1, 0, 1]#

MuData axis.

  • 0 if the modalities have shared observations

  • 1 if the modalities have shared features

  • -1 if both observations and features are shared

property filename: Path | None#

Change the backing mode by setting the filename to a .h5mu file.

  • Setting the filename writes the stored data to disk.

  • Setting the filename when the filename was previously another name moves the backing file from the previous file to the new file. If you want to copy the previous file, use copy(filename="new_filename").

property is_view: bool#

Whether the object is a view of another MuData object.

property isbacked: bool#

Whether the object is backed on disk.

property mod: Mapping[str, AnnData | MuData]#

Dictionary of modalities.

property mod_names: list[str]#

Names of modalities (alias for list(mdata.mod.keys()))

property n_mod: int#

Number of modalities.

property n_obs: int#

Total number of observations

property n_var: int#

Total number of variables.

property n_vars: int#

Total number of variables.

property obs: DataFrame#

Annotation of observation

property obs_names: Index#

Names of variables (alias for .obs.index).

property obsm: MutableMapping[str]#

Multi-dimensional annotation of observations.

Stores for each key a two- or higher-dimensional ndarray or DataFrame of length n_obs. Is sliced with obs but otherwise behaves like a mapping.

property obsmap: Mapping[str]#

Mapping of observation indices in the object to indices in individual modalities.

Contains an entry for each modality. Each entry is an ndarray with shape (n_obs, 1). Each element in the array contains the numerical index of the observation in the respective modality corresponding to the MuData observation in that position. The index is 1-based, 0 indicates that the observation is missing in the modality.

property obsp: MutableMapping[str]#

Pairwise annotatation of observations.

Stores for each key a two- or higher-dimensional ndarray whose first two dimensions are of liength n_obs. Is sliced with obs but otherwise behaves like a mapping.

property shape: tuple[int, int]#

Shape of data, all variables and observations combined (n_obs, n_vars).

property uns: MutableMapping#

Unstructured annotation (ordered dictionary).

property var: DataFrame#

Annotation of variables.

property var_names: Index#

Names of variables (alias for .var.index)

property varm: MutableMapping[str]#

Multi-dimensional annotation of variables.

Stores for each key a two- or higher-dimensional ndarray or DataFrame of length n_vars. Is sliced with var but otherwise behaves like a mapping.

property varmap: Mapping[str]#

Mapping of feature indices in the object to indices in individual modalities.

Contains an entry for each modality. Each entry is an ndarray with shape (n_obs, 1). Each element in the array contains the numerical index of the feature in the respective modality corresponding to the MuData feature in that position. The index is 1-based, 0 indicates that the feature is missing in the modality.

property varp: MutableMapping[str]#

Pairwise annotatation of variables.

Stores for each key a two- or higher-dimensional ndarray whose first two dimensions are of liength n_obs. Is sliced with obs but otherwise behaves like a mapping.

Methods#

copy(filename=None)#

Make a copy.

Parameters:

filename (str | PathLike | None (default: None)) – If the object is backed, copy the object to a new file.

Return type:

MuData

obs_keys()#

List keys of observation annotation obs.

Return type:

list[str]

obs_names_make_unique()#

Call AnnData.obs_names_make_unique on each modality.

If there are obs_names which are the same for multiple modalities, append the modality name to all obs_names.

obs_vector(key, layer=None)#

Return an array of values for the requested key of length n_obs.

Parameters:

  • key (str) – The key to use. Must be in .obs.columns.

  • layer (str | None (default: None)) – Ignored, only for compatibility with AnnData.

Return type:

ndarray

obsm_keys()#

List keys of observation annotation obsm.

Return type:

list[str]

pull_obs(columns=None, mods=None, common=None, join_common=None, nonunique=None, join_nonunique=None, unique=None, prefix_unique=True, drop=False, only_drop=False)#

Copy data from the obs of the modalities to the global obs

Existing columns to be overwritten or updated.

Parameters:

  • columns (list[str] | None (default: None)) – List of columns to pull from the modalities’ .obs tables

  • common (bool | None (default: None)) – If True, pull common columns. Common columns do not have modality prefixes. Pull from all modalities. Cannot be used with columns. True by default.

  • mods (list[str] | None (default: None)) – List of modalities to pull from.

  • join_common (bool | None (default: None)) – If True, attempt to join common columns. Common columns are present in all modalities. True for MuData wth axis=1 (shared var). False for MuData with axis=0 and axis=-1. Cannot be used with mods, or for shared attr.

  • nonunique (bool | None (default: None)) – If True, pull columns that have a modality prefix such that there are multiple columns with the same name and different prefix. Cannot be used with columns or mods. True by default.

  • join_nonunique (bool | None (default: None)) – If True, attempt to join non-unique columns. Intended usage is the same as for join_common. Cannot be used with mods, or for shared attr. False by default.

  • unique (bool | None (default: None)) – If True, pull columns that have a modality prefix such that there is no other column with the same name and a different modality prefix. Cannot be used with columns or mods. True by default.

  • prefix_unique (bool (default: True)) – If True, prefix unique column names with modname (default). No prefix when False.

  • drop (bool (default: False)) – If True, drop the columns from the modalities after pulling.

  • only_drop (bool (default: False)) – If True, drop the columns but do not actually pull them. Forces drop=True.

pull_var(columns=None, mods=None, common=None, join_common=None, nonunique=None, join_nonunique=None, unique=None, prefix_unique=True, drop=False, only_drop=False)#

Copy data from the var of the modalities to the global var

Existing columns to be overwritten or updated.

Parameters:

  • columns (list[str] | None (default: None)) – List of columns to pull from the modalities’ .var tables

  • common (bool | None (default: None)) – If True, pull common columns. Common columns do not have modality prefixes. Pull from all modalities. Cannot be used with columns. True by default.

  • mods (list[str] | None (default: None)) – List of modalities to pull from.

  • join_common (bool | None (default: None)) – If True, attempt to join common columns. Common columns are present in all modalities. True for MuData with axis=0 (shared obs). False for MuData with axis=1 and axis=-1. Cannot be used with mods, or for shared attr.

  • nonunique (bool | None (default: None)) – If True, pull columns that have a modality prefix such that there are multiple columns with the same name and different prefix. Cannot be used with columns or mods. True by default.

  • join_nonunique (bool | None (default: None)) – If True, attempt to join non-unique columns. Intended usage is the same as for join_common. Cannot be used with mods, or for shared attr. False by default.

  • unique (bool | None (default: None)) – If True, pull columns that have a modality prefix such that there is no other column with the same name and a different modality prefix. Cannot be used with columns or mods. True by default.

  • prefix_unique (bool (default: True)) – If True, prefix unique column names with modname (default). No prefix when False.

  • drop (bool (default: False)) – If True, drop the columns from the modalities after pulling.

  • only_drop (bool (default: False)) – If True, drop the columns but do not actually pull them. Forces drop=True.

push_obs(columns=None, mods=None, common=None, prefixed=None, drop=False, only_drop=False)#

Copy the data from obs to the obs of the modalities.

Existing columns to be overwritten.

Parameters:

  • columns (list[str] | None (default: None)) – List of columns to push

  • mods (list[str] | None (default: None)) – List of modalities to push to

  • common (bool | None (default: None)) – If True, push common columns. Common columns do not have modality prefixes. Push to each modality unless all values for a modality are null. Cannot be used with columns. True by default.

  • prefixed (bool | None (default: None)) – If True, push columns that have a modality prefix. which are prefixed by modality names. Only push to the respective modality names. Cannot be used with columns. True by default.

  • drop (bool (default: False)) – If True, drop the columns from the global .obs after pushing. False by default.

  • only_drop (bool (default: False)) – If True, drop the columns but do not actually pull them. Forces drop=True. False by default.

push_var(columns=None, mods=None, common=None, prefixed=None, drop=False, only_drop=False)#

Copy the data from var to the var of the modalities.

Existing columns to be overwritten.

Parameters:

  • columns (list[str] | None (default: None)) – List of columns to push

  • mods (list[str] | None (default: None)) – List of modalities to push to

  • common (bool | None (default: None)) – If True, push common columns. Common columns do not have modality prefixes. Push to each modality unless all values for a modality are null. Cannot be used with columns. True by default.

  • prefixed (bool | None (default: None)) – If True, push columns that have a modality prefix. which are prefixed by modality names. Only push to the respective modality names. Cannot be used with columns. True by default.

  • drop (bool (default: False)) – If True, drop the columns from the global .var after pushing. False by default.

  • only_drop (bool (default: False)) – If True, drop the columns but do not actually pull them. Forces drop=True. False by default.

strings_to_categoricals(df=None)#

Transform string annotations to categoricals.

Parameters:

df (DataFrame | None (default: None)) – If None, modifies var and obs attributes of the MuData object as well as each modality. Otherwise, modifies the dataframe in-place and returns it.

Return type:

DataFrame | None

to_anndata(**kwargs)#

Convert the object to AnnData.

If axis is 0 (shared observations), concatenate modalities along axis 1 (anndata.concat(axis=1)).

If axis is 1 (shared features), concatenate datasets along axis 0 (anndata.concat(axis=0)).

See anndata.concat() documentation for more details.

Parameters:

**kwargs – Keyword arguments passed to anndata.concat()

Return type:

AnnData

uns_keys()#

List keys of unstructured annotation.

Return type:

list[str]

update()#

Update both obs and var indices of the object with the data from all the modalities.

Note

From v0.4, it will not pull columns from modalities by default.

update_obs()#

Update obs indices of the object with the data from all the modalities.

Note

From v0.4, it will not pull columns from modalities by default.

update_var()#

Update var indices of the object with the data from all the modalities.

Note

From v0.4, it will not pull columns from modalities by default.

var_keys()#

List keys of variable annotation var.

Return type:

list[str]

var_names_make_unique()#

Call AnnData.var_names_make_unique on each modality.

If there are obs_names which are the same for multiple modalities, append the modality name to all obs_names.

var_vector(key, layer=None)#

Return an array of values for the requested key of length n_var.

Parameters:

  • key (str) – The key to use. Must be in .obs.columns.

  • layer (str | None (default: None)) – Ignored, only for compatibility with AnnData.

Return type:

ndarray

varm_keys()#

List keys of variable annotation varm.

Return type:

list[str]

write(filename=None, **kwargs)#

Write the object to an HDF5 file.

Parameters:

  • filename (str | PathLike | None (default: None)) – Path of the .h5mu file to write to. Defaults to the backing file.

  • **kwargs – Additional arguments to write_h5mu().

write_h5mu(filename=None, **kwargs)#

Write the object to an HDF5 file.

Parameters:

  • filename (str | PathLike | None (default: None)) – Path of the .h5mu file to write to. Defaults to the backing file.

  • **kwargs – Additional arguments to write_h5mu().

write_zarr(store, **kwargs)#

Write the object to a Zarr store.

Parameters: