MuData

0.3.4 · active · verified Thu Apr 16

MuData (Multimodal Data) is a Python library for working with multimodal single-cell data, building upon the AnnData ecosystem. It provides a container for multiple AnnData objects, representing different modalities, allowing for unified storage and analysis. The current version is 0.3.4, and the library typically releases minor versions every few months, with patch releases addressing compatibility and bug fixes.

Common errors

```
ValueError: Mismatching AnnData version. MuData requires anndata>=0.10.8 for numpy>=2.0 compatibility.
```
cause Your installed `anndata` version is too old for your `numpy` or `mudata` version, or you have `numpy` 2.0.0+ installed with an incompatible `anndata`.

fix Upgrade both `anndata` and `mudata` to their latest compatible versions: `pip install --upgrade anndata mudata`.
```
AttributeError: 'MuData' object has no attribute 'update' (or unexpected behavior of .update())
```
cause After MuData v0.3.0, the default behavior of `.update()` changed, and its primary purpose shifted. If you're encountering an `AttributeError`, you might be using an older syntax or expecting the pre-0.3.0 implicit `pull_on_update`.

fix Adopt the new annotation management interface using `.pull()` to fetch metadata from modalities or `.push()` to send it. If you need the old implicit behavior, set `mudata.set_options(pull_on_update=True)` before creating or updating the `MuData` object.
```
OSError: Unable to open file (file is not an HDF5 file) or ValueError: Invalid H5Mu format.
```
cause This usually indicates an attempt to read an `h5mu` file created with an older (or different) `anndata`/`mudata` I/O specification, which is no longer compatible with your current library versions.

fix Ensure `anndata` and `mudata` are both fully updated (`pip install --upgrade anndata mudata`). If the problem persists, the file may need to be re-exported from its original source using a compatible version of the libraries.

Warnings

breaking The default behavior of `mudata.update()` changed in v0.3.0. Previously, it would implicitly pull metadata from modalities. Now, by default, it does not. This was part of a new interface for managing annotations.
Fix: Adopt the new `.pull()` and `.push()` interface, or revert to the old `.update()` behavior by setting `mudata.set_options(pull_on_update=False)`.
breaking MuData v0.2.0 introduced compatibility with the new I/O specification from AnnData v0.8. Files saved with older versions of AnnData or MuData might not be readable, or read incorrectly, with newer versions.
Fix: Ensure `anndata` and `mudata` are up-to-date and compatible. If encountering issues with old files, try loading with the version of `mudata`/`anndata` that created the file and resaving it with the latest versions.
gotcha MuData v0.2.4 introduced compatibility with `numpy` 2.0.0, but this requires `anndata` 0.10.8 or newer. Using an older `anndata` with `numpy` 2.0 can lead to incompatibility errors.
Fix: Always ensure your `anndata` installation is compatible with your `numpy` and `mudata` versions. A `pip install --upgrade anndata mudata` can resolve most dependency mismatches.
gotcha Improvements for slicing and copying `MuData` objects and views were implemented in v0.3.2. Older versions might have exhibited unexpected behavior or inconsistencies when performing these operations, particularly with backed objects.
Fix: Upgrade to MuData v0.3.2 or newer to benefit from improved stability and correctness when slicing or copying `MuData` objects and their views.

Install

pip install mudata Install stable version

Imports

MuData
```
from mudata import MuData
```
read_h5mu
wrong:
```
mudata.read(...)
```
correct:
```
from mudata import read_h5mu
```
While `mudata.read()` might work for .h5mu, `read_h5mu` is more explicit and often preferred for this specific format.
concat
```
from mudata import concat
```

Quickstart

This quickstart demonstrates how to create a `MuData` object from multiple `AnnData` objects, access individual modalities, and inspect shared observation metadata. The example simulates two modalities (RNA and ATAC) for 10 cells.

import anndata as ad
import mudata as md
import numpy as np
import pandas as pd

# Create dummy AnnData objects for two modalities (e.g., RNA and ATAC)
adata_rna = ad.AnnData(
    X=np.random.rand(10, 20), # 10 cells, 20 genes
    obs=pd.DataFrame(index=[f"cell_{i}" for i in range(10)], data={'donor': np.random.choice(['D1', 'D2'], 10)}),
    var=pd.DataFrame(index=[f"gene_{j}" for j in range(20)])
)
adata_atac = ad.AnnData(
    X=np.random.randint(0, 5, size=(10, 15)), # 10 cells, 15 peaks
    obs=pd.DataFrame(index=[f"cell_{i}" for i in range(10)], data={'donor': np.random.choice(['D1', 'D2'], 10)}),
    var=pd.DataFrame(index=[f"peak_{j}" for j in range(15)])
)

# Create a MuData object from a dictionary of AnnData objects
mdata = md.MuData({'rna': adata_rna, 'atac': adata_atac})

print("MuData object created:")
print(mdata)

# Access a specific modality
print("\nAccessing the 'rna' modality:")
print(mdata['rna'])

# Access shared observation metadata
print("\nShared observation metadata:")
print(mdata.obs.head())

view raw JSON →