🧠 Key takeaways
Modern single-cell experiments often measure multiple modalities (e.g., RNA, ATAC, proteins) at the same time. While AnnData is designed for unimodal data, multimodal experiments require containers such as MuData that organize multiple datasets together.
A MuData object stores several AnnData objects (one per modality) while sharing global annotations for cells and features. This structure allows both modality-specific analyses and joint multimodal computations within the same dataset.
The framework muon extends the analysis ecosystem by providing preprocessing and analysis tools for modalities beyond RNA, such as ATAC or protein data. It also includes methods that integrate information across multiple modalities.
⚙️ Environment setup
Install conda:
Before creating the environment, ensure that conda is installed on your system.
Save the yml content:
Copy the content from the yml tab into a file named
environment.yml.
Create the environment:
Open a terminal or command prompt.
Run the following command:
conda env create -f environment.yml
Activate the environment:
After the environment is created, activate it using:
conda activate <environment_name>Replace
<environment_name>with the name specified in theenvironment.ymlfile. In the yml file it will look like this:name: <environment_name>
Verify the installation:
Check that the environment was created successfully by running:
conda env list
name: advanced_data_structures_and_frameworks
channels:
- conda-forge
- bioconda
dependencies:
- conda-forge::anndata=0.12.11
- conda-forge::mudata=0.4.1
- conda-forge::muon=0.1.9
- conda-forge::python=3.14.7
- conda-forge::scanpy=1.12
- conda-forge::python-igraph=1.0.0
- pip
- pip:
- lamindb
- pysam==0.24.1
🗄️ Get data and notebooks
This book uses lamindb to store, share, and load datasets and notebooks using the theislab/sc-best-practices instance. We acknowledge free hosting from Lamin Labs.
Install lamindb
Install the lamindb Python package:
pip install lamindbOptionally create a lamin account
Sign up and log in following the instructions
Verify your setup
Run the
lamin connectcommand:
import lamindb as ln ln.Artifact.connect("theislab/sc-best-practices").df()You should now see up to 100 of the stored datasets.
Accessing datasets (Artifacts)
Search for the datasets on the Artifacts page
Load an Artifact and the corresponding object:
import lamindb as ln af = ln.Artifact.connect("theislab/sc-best-practices").get( key="key_of_dataset", is_latest=True ) obj = af.load()The object is now accessible in memory and is ready for analysis. Adapt the
lamindb.Artifact.connect("theislab/sc-best-practices").get("SOMEIDXXXX")suffix to get respective versions.Accessing notebooks (Transforms)
Search for the notebook on the Transforms page
Load the notebook:
lamin load <notebook url>which will download the notebook to the current working directory. Analogously to
Artifacts, you can adapt the suffix ID to get older versions.

Figure 1:Scverse ecosystem overview highlighting MuData and muon, covered in this chapter, and SpatialData and Squidpy, covered in the spatial data structures chapter. The publication date by a scientific journal is shown in brackets. We have obtained the symbols of the libraries from the corresponding Github pages Virshup et al., 2021Wolf et al., 2018Bredikhin et al., 2022Palla et al., 2022Marconato et al., 2025.
This chapter assumes familiarity with AnnData and scanpy from the previous chapter. It introduces MuData for multimodal assays and muon, the analysis framework built on top of it.
Using MuData to store multimodal data¶
AnnData is primarily designed for storing and manipulating unimodal data. However, multimodal assays such as CITE-Seq generate multimodal data by simultaneously measuring RNA and surface proteins. This data requires more advanced ways of storing, which is where MuData comes into play. MuData builds on top of AnnData to store and manipulate multimodal data. Muon Bredikhin et al., 2022, a “Scanpy equivalent” and core package of scverse, can then be used to analyze the multimodal omics data. The following section is based on the MuData Quickstart and the Multimodal data objects tutorial.

Figure 2:MuData overview. Image obtained from Bredikhin et al., 2022.
Installation¶
MuData is available on PyPI and Conda. It can be installed using either of the following commands.
pip install mudata
conda install -c conda-forge mudataThe main idea behind MuData is that the MuData object contains references to single AnnData objects of the unimodal data, but the MuData object itself also stores multimodal annotations.
It is therefore possible to directly access the AnnData objects to perform unimodal data transformations which store their results in the corresponding AnnData annotations, but also to aggregate the modalities for joint calculations whose results can be stored in the global MuData object.
Technically, this is realized by MuData objects comprising a dictionary with AnnData objects, one per modality, in their .mod (=modality) attribute.
Just as AnnData objects themselves, MuData objects also contain attributes like .obs with annotation of observations (samples or cells), .obsm with their multidimensional annotations such as embeddings.
Initializing a MuData object¶
Let’s import MuData from the mudata package.
import lamindb as ln
import mudata as md
import numpy as np
ln.connect("theislab/sc-best-practices")
ln.track("em2cp9S0T9WE")Output
→ connected lamindb: theislab/sc-best-practices
! It looks like you are running jupyter lab but don't have jupyter-server module installed. Please install it via pip install jupyter-server
→ loaded Transform('em2cp9S0T9WE0001', key='advanced_data_structures_and_frameworks.ipynb'), started new Run('FOKypfLp58AYV3XG') at 2026-10-19 13:23:04 UTC
To create an example MuData object we require simulated data. Therefore, we created two AnnData objects with data for the same observations, but for different variables.
adata = ln.Artifact.get(
key="introduction/advanced_data_structures_and_frameworks_mudata_1.h5ad",
).load()
adataAnnData object with n_obs × n_vars = 1000 × 100adata2 = ln.Artifact.get(
key="introduction/advanced_data_structures_and_frameworks_mudata_2.h5ad",
).load()
adata2AnnData object with n_obs × n_vars = 1000 × 50These two AnnData objects (two “modalities”) can then be wrapped into a single MuData object.
Here, we name modality one A and modality two B.
mdata = md.MuData({"A": adata, "B": adata2})
mdataMuData object with n_obs × n_vars = 1000 × 150
2 modalities
A: 1000 × 100
B: 1000 × 50Observations and variables of the MuData object are global, which means that observations with the identical name (.obs_names) in different modalities are considered to be the same observation (e.g. obs_1 in adata and obs_1 in adata2).
This also means variable names (.var_names) should be unique (e.g. var_1 in adata and var2_1 in adata2).
This is reflected in the object description above: mdata has 1000 observations and 150 = 100+50 variables.
MuData attributes¶
.mod¶
MuData objects consist of annotations as earlier described for AnnData objects like .obs or .var, but extend this behavior with .mod which serves as an accessor to the individual modalities.
Modalities are stored in a collection accessible via the .mod attribute of the MuData object with names of modalities as keys and AnnData objects as values.
list(mdata.mod.keys())['A', 'B']Individual modalities can be accessed with their names via the .mod attribute or via the MuData object itself as a shorthand.
print(mdata.mod["A"])
print(mdata["A"])AnnData object with n_obs × n_vars = 1000 × 100
AnnData object with n_obs × n_vars = 1000 × 100
.obs and .var¶
Samples (cells) annotation is accessible via the .obs attribute and by default includes copies of columns from .obs data frames of individual modalities.
The same goes for .var, which contains annotation of variables (features).
Observations columns copied from individual modalities contain modality name as their prefix, e.g. rna:n_genes.
This is also true for variables columns.
However if there are columns with identical names in .var of multiple modalities (e.g., n_cells), these columns are merged across modalities and no prefix is added.
When those slots are changed in AnnData objects of modalities, e.g. new columns are added or samples (cells) are filtered out, the changes have to be fetched with the .update() method (see below).
mdata.var_namesIndex(['var_1', 'var_2', 'var_3', 'var_4', 'var_5', 'var_6', 'var_7', 'var_8',
'var_9', 'var_10',
...
'var2_41', 'var2_42', 'var2_43', 'var2_44', 'var2_45', 'var2_46',
'var2_47', 'var2_48', 'var2_49', 'var2_50'],
dtype='object', length=150)Multidimensional annotations of samples (cells) are accessible in the .obsm attribute.
For instance, that can be UMAP coordinates that were learnt jointly on all modalities.
If the shape of a modality is changed (e.g. change var_names), MuData.update() has to be run to bring the respective updates to the MuData object.
adata2.var_names = ["var_ad2_" + e.split("_")[1] for e in adata2.var_names]
print("Outdated variables names: ...,", ", ".join(mdata.var_names[-3:]))
mdata.update()
print("Updated variables names: ...,", ", ".join(mdata.var_names[-3:]))Outdated variables names: ..., var2_48, var2_49, var2_50
Updated variables names: ..., var_ad2_48, var_ad2_49, var_ad2_50
Importantly, individual modalities are stored as references to the original objects. Hence, if the original AnnData is changed the change will also be reflected in the MuData object.
# Add some unstructured data to the original object
adata.uns["misc"] = {"adata": True}# Access modality A via the .mod attribute
mdata.mod["A"].uns["misc"]{'adata': True}Variable mappings¶
Upon construction of a MuData object, a global binary mapping between observations and individual modalities is created as well as between variables and modalities.
Since all the observations are the same across modalities in mdata, all the values in the observations mappings are set to True.
mdata.obsm["A"]Output
array([[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True]])np.sum(mdata.obsm["A"]) == np.sum(mdata.obsm["B"]) == 1000np.True_For variables however, those are 150-long vectors.
The A modality has 100 True values followed by 50 False values.
mdata.varm["A"]Output
array([[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[ True],
[False],
[False],
[False],
[False],
[False],
[False],
[False],
[False],
[False],
[False],
[False],
[False],
[False],
[False],
[False],
[False],
[False],
[False],
[False],
[False],
[False],
[False],
[False],
[False],
[False],
[False],
[False],
[False],
[False],
[False],
[False],
[False],
[False],
[False],
[False],
[False],
[False],
[False],
[False],
[False],
[False],
[False],
[False],
[False],
[False],
[False],
[False],
[False],
[False],
[False]])MuData views¶
Analogous to the behavior of AnnData objects, slicing MuData objects returns views of the original data.
view = mdata[:100, :1000]
print(view.is_view)
print(view["A"].is_view)True
True
Subsetting MuData objects is special since it slices them across modalities.
For example, the slicing operation for a set of obs_names and/or var_names will be performed for each modality and not only for the global multimodal annotation.
This behavior makes workflows memory-efficient, which is especially important when working with large datasets.
If the object is to be modified however, a copy of it should be created, which is not a view anymore and has no dependence on the original object.
mdata_sub = view.copy()
mdata_sub.is_viewFalseCommon observations¶
While a MuData object is comprised of the same observations for both modalities, it is not always the case in the real world where some data might be missing.
By design, MuData accounts for these scenarios since there’s no guarantee observations are the same (or even intersecting) for a MuData instance.
It’s worth noting that other tools might provide convenience functions for some common scenarios of dealing with missing data, such as intersect_obs() implemented in muon.
Reading and Writing of MuData objects¶
Similarly to AnnData objects, MuData objects were designed to be serialized into HDF5 based .h5mu files.
All modalities are stored under their respective names in the /mod HDF5 group of the .h5mu file. Each individual modality, e.g. /mod/A, is stored in the same way as it would be stored in the .h5ad file.
MuData objects can be read and written as follows:
mdata.write("my_mudata.h5mu")
mdata_r = md.read("my_mudata.h5mu", backed=True)
mdata_rMuData object with n_obs × n_vars = 1000 × 150 backed at 'my_mudata.h5mu'
2 modalities
A: 1000 × 100
uns: 'misc'
B: 1000 × 50Individual modalities are backed as well inside the .h5mu file.
mdata_r["A"].isbackedTrueIf the original object is backed, provide a new filename to the .copy() call, and the resulting object will be backed at a new location.
mdata_sub = mdata_r.copy("mdata_sub.h5mu")
print(mdata_sub.is_view)
print(mdata_sub.isbacked)False
True
Multimodal methods¶
When the MuData object is prepared, it is up to multimodal methods to be used to make sense of the data. The most simple and naive approach is to concatenate matrices from multiple modalities to perform for example dimensionality reduction.
x = np.hstack([mdata.mod["A"].X, mdata.mod["B"].X])
x.shape(1000, 150)We can write a simple function to run a principal component analysis (PCA) on such a concatenated matrix.
MuData object provides a place to store multimodal embeddings: MuData .obsm.
It is similar to how the embeddings generated on individual modalities are stored, only this time it is saved inside the MuData object rather than in AnnData .obsm.
To calculate for example a PCA for the joint values of the modalities, we horizontally stack the values stored in the individual modalities and then perform the PCA on the stacked matrix. This is possible because the number of observations matches across modalities (remember, the number of features per modality does not have to match).
def simple_pca(mdata):
from sklearn import decomposition
x = np.hstack([m.X for m in mdata.mod.values()])
pca = decomposition.PCA(n_components=2)
components = pca.fit_transform(x)
# By default, methods operate in-place and embeddings are stored in the .obsm slot
mdata.obsm["X_pca"] = componentssimple_pca(mdata)
print(mdata)MuData object with n_obs × n_vars = 1000 × 150
obsm: 'X_pca'
2 modalities
A: 1000 × 100
uns: 'misc'
B: 1000 × 50
Our calculated principal components are now stored in the MuData object itself and accessible for further multimodal transformations.
In reality, however, having different modalities often means that the features between them come from different generative processes and are not comparable. This is where special multimodal integration methods come into play. For omics technologies, these methods are frequently addressed as multi-omics integration methods. In the following section we will introduce muon which provides many tools to preprocess unimodal data beyond RNA-Seq and multi-omics integration methods.
Multimodal data analysis with muon¶
Although Scanpy provides generally applicable tools such as PCA, UMAP, and various visualizations, it is primarily designed to analyze RNA-Seq data. Muon fills this gap by providing preprocessing functions for other omics, such as chromatin accessibility (ATAC) or protein (CITE) data. As mentioned above, muon further provides algorithms to run multi-omics algorithms that infer knowledge from the joint modalities. For example, users may run a PCA on a single modality, but muon further provides multi-omics factor analysis algorithms that take several modalities as input. The following sections was adopted from the muon tutorial “Processing chromatin accessibility of 10k PBMCs”.

Figure 3:muon overview. Image obtained from Bredikhin et al., 2022.
Installation¶
Muon is available on PyPI and can be installed using:
pip install muonAPI overview¶
To introduce muon, we will examine the ATAC data from a multimodal dataset. Analogously to the Scanpy chapter, this chapter solely serves as a quick demo and overview of muon and does not analyze a dataset thoroughly, let alone provide best-practice multi-omics analysis. Please read the corresponding chapters to learn how to properly conduct such analyses.
Muon separates its modules in two ways. First, analogously to Scanpy, general and multimodal functions are grouped in preprocessing (muon.pp), tools (muon.tl) and plots (muon.pl).
Second, unimodal tools are available from the corresponding muon, which are again separated into preprocessing, tools and plots.
For example, all ATAC preprocessing functions are grouped into muon.atac.pp.
This also applies to CITE-Seq preprocessing functions (muon.prot.pp).

Figure 4:Muon API overview. Modality specific functions are provided in correspondingly named modules. Functions for the joint analysis of modalities are available via the muon module directly.
Muon API demo¶
The dataset for our demo is a publicly available 10x Genomics Multiome dataset for human peripheral blood mononuclear cells (PBMCs).
import muon as mu
mdata = ln.Artifact.get(
key="introduction/advanced_data_structures_and_frameworks_muon.h5mu", is_latest=True
).load()
fragments = ln.Artifact.get(
key="introduction/advanced_data_structures_and_frameworks_atac_fragments.tsv.gz",
is_latest=True,
).cache()
fragments_tbi = ln.Artifact.get(
key="introduction/advanced_data_structures_and_frameworks_atac_fragments.tsv.gz.tbi",
is_latest=True,
).cache()
mdataMuData object with n_obs × n_vars = 11909 × 144978
var: 'gene_ids', 'feature_types', 'genome', 'interval'
2 modalities
rna: 11909 × 36601
var: 'gene_ids', 'feature_types', 'genome', 'interval'
atac: 11909 × 108377
var: 'gene_ids', 'feature_types', 'genome', 'interval'
uns: 'atac', 'files'As a first step we subset to the ATAC modality.
atac = mdata.mod["atac"]Although, we are now not working with RNA-Seq, it is possible to use some of Scanpy’s preprocessing functions which can also be used on ATAC data. This is possible due to similar distribution and quality issues of both modalities. The only thing to bear in mind here that a gene would mean a peak in the context of the AnnData object with ATAC-seq data. Afterwards, ATAC specific preprocessing can be conducted with the ATAC module of muon.
Let us start with some quality control by filtering out cells with too few peaks and peaks detected in too few cells. For now, we will filter out cells that do not pass QC.
import scanpy as sc
sc.pp.calculate_qc_metrics(atac, percent_top=None, log1p=False, inplace=True)sc.pl.violin(atac, ["total_counts", "n_genes_by_counts"], jitter=0.4, multi_panel=True)
Filter peaks whose expression is not detected.
mu.pp.filter_var(atac, "n_cells_by_counts", lambda x: x >= 10)
# This is analogous to
# sc.pp.filter_genes(rna, min_cells=10)
# but does in-place filtering and avoids copying the objectWe also filter the cells.
mu.pp.filter_obs(atac, "n_genes_by_counts", lambda x: (x >= 2000) & (x <= 15000))
# This is analogous to
# sc.pp.filter_cells(atac, max_genes=15000)
# sc.pp.filter_cells(atac, min_genes=2000)
# but does in-place filtering avoiding copying the object
mu.pp.filter_obs(atac, "total_counts", lambda x: (x >= 4000) & (x <= 40000))sc.pl.violin(atac, ["n_genes_by_counts", "total_counts"], jitter=0.4, multi_panel=True)
Muon also provides histograms which allows for a different view on the metrics.
mu.pl.histogram(atac, ["n_genes_by_counts", "total_counts"])
Now that we rudimentary filtered out cells with too few peaks and peaks detected in too few cells, we can start with ATAC specific quality control with muon. Muon has modality specific preprocessing functions in corresponding modules. We import the ATAC module to access the ATAC specific preprocessing functions.
from muon import atac as ac# Perform rudimentary quality control with muon's ATAC module
atac.obs["NS"] = 1
ac.tl.locate_fragments(mdata, fragments=str(fragments))
ac.tl.locate_fragments(atac, fragments=str(fragments))
ac.tl.nucleosome_signal(atac, n=1e6)
ac.tl.get_gene_annotation_from_rna(mdata["rna"]).head(3)
tss = ac.tl.tss_enrichment(mdata, n_tss=1000)
ac.pl.tss_enrichment(tss)Reading Fragments: 100%|██████████| 1000000/1000000 [00:01<00:00, 758143.53it/s]
Fetching Regions...: 100%|██████████| 1000/1000 [00:05<00:00, 180.89it/s]

# Save original counts, normalize data and select highly variable genes with scanpy
atac.layers["counts"] = atac.X
sc.pp.normalize_per_cell(atac, counts_per_cell_after=1e4)
sc.pp.log1p(atac)
sc.pp.highly_variable_genes(atac, min_mean=0.05, max_mean=1.5, min_disp=0.5)
atac.raw = atacAlthough PCA is also commonly used for ATAC data, latent semantic indexing (LSI) is another popular option. It is implemented in muon’s ATAC module.
ac.tl.lsi(atac)
sc.pp.neighbors(atac, use_rep="X_lsi", n_neighbors=10, n_pcs=30)
sc.tl.leiden(atac, resolution=0.5, flavor="igraph", n_iterations=2)
sc.tl.umap(atac, spread=1.5, min_dist=0.5, random_state=20)
sc.pl.umap(atac, color=["leiden", "n_genes_by_counts"], legend_loc="on data")
We can use the functionality of the ATAC module in muon to color plots by cut values in peaks corresponding to a certain gene.
ac.pl.umap(atac, color=["KLF4"], average="peak_type")
For more details on all available functions of muon, please read the muon API reference and the muon tutorials.
Multiple-choice questions¶
Contributors¶
We gratefully acknowledge the contributions of:
Authors¶
Lukas Heumos
Luis Heinzlmeier
Reviewers¶
Isaac Virshup
- Virshup, I., Rybakov, S., Theis, F. J., Angerer, P., & Wolf, F. A. (2021). anndata: Annotated data. bioRxiv. 10.1101/2021.12.16.473007
- Wolf, F. A., Angerer, P., & Theis, F. J. (2018). SCANPY: large-scale single-cell gene expression data analysis. Genome Biology, 19(1), 15. 10.1186/s13059-017-1382-0
- Bredikhin, D., Kats, I., & Stegle, O. (2022). MUON: multimodal omics analysis framework. Genome Biology, 23(1), 42. 10.1186/s13059-021-02577-8
- Palla, G., Spitzer, H., Klein, M., Fischer, D., Schaar, A. C., Kuemmerle, L. B., Rybakov, S., Ibarra, I. L., Holmberg, O., Virshup, I., Lotfollahi, M., Richter, S., & Theis, F. J. (2022). Squidpy: a scalable framework for spatial omics analysis. Nature Methods, 19(2), 171–178. 10.1038/s41592-021-01358-2
- Marconato, L., Palla, G., Yamauchi, K. A., Virshup, I., Heidari, E., Treis, T., Vierdag, W.-M., Toth, M., Stockhaus, S., Shrestha, R. B., Rombaut, B., Pollaris, L., Lehner, L., Vöhringer, H., Kats, I., Saeys, Y., Saka, S. K., Huber, W., Gerstung, M., … Stegle, O. (2025). SpatialData: an open and universal data framework for spatial omics. Nature Methods, 22(1), 58–62. 10.1038/s41592-024-02212-x