{"id":8337,"library":"mudata","title":"MuData","description":"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.","status":"active","version":"0.3.4","language":"en","source_language":"en","source_url":"https://github.com/scverse/mudata","tags":["data science","bioinformatics","single-cell","multi-omics","anndata","scverse"],"install":[{"cmd":"pip install mudata","lang":"bash","label":"Install stable version"}],"dependencies":[{"reason":"Core data structure for individual modalities and underlying I/O. Version compatibility is crucial.","package":"anndata"}],"imports":[{"symbol":"MuData","correct":"from mudata import MuData"},{"note":"While `mudata.read()` might work for .h5mu, `read_h5mu` is more explicit and often preferred for this specific format.","wrong":"mudata.read(...)","symbol":"read_h5mu","correct":"from mudata import read_h5mu"},{"symbol":"concat","correct":"from mudata import concat"}],"quickstart":{"code":"import anndata as ad\nimport mudata as md\nimport numpy as np\nimport pandas as pd\n\n# Create dummy AnnData objects for two modalities (e.g., RNA and ATAC)\nadata_rna = ad.AnnData(\n    X=np.random.rand(10, 20), # 10 cells, 20 genes\n    obs=pd.DataFrame(index=[f\"cell_{i}\" for i in range(10)], data={'donor': np.random.choice(['D1', 'D2'], 10)}),\n    var=pd.DataFrame(index=[f\"gene_{j}\" for j in range(20)])\n)\nadata_atac = ad.AnnData(\n    X=np.random.randint(0, 5, size=(10, 15)), # 10 cells, 15 peaks\n    obs=pd.DataFrame(index=[f\"cell_{i}\" for i in range(10)], data={'donor': np.random.choice(['D1', 'D2'], 10)}),\n    var=pd.DataFrame(index=[f\"peak_{j}\" for j in range(15)])\n)\n\n# Create a MuData object from a dictionary of AnnData objects\nmdata = md.MuData({'rna': adata_rna, 'atac': adata_atac})\n\nprint(\"MuData object created:\")\nprint(mdata)\n\n# Access a specific modality\nprint(\"\\nAccessing the 'rna' modality:\")\nprint(mdata['rna'])\n\n# Access shared observation metadata\nprint(\"\\nShared observation metadata:\")\nprint(mdata.obs.head())","lang":"python","description":"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."},"warnings":[{"fix":"Adopt the new `.pull()` and `.push()` interface, or revert to the old `.update()` behavior by setting `mudata.set_options(pull_on_update=False)`.","message":"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.","severity":"breaking","affected_versions":">=0.3.0"},{"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.","message":"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.","severity":"breaking","affected_versions":">=0.2.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=0.2.4"},{"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.","message":"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.","severity":"gotcha","affected_versions":"<0.3.2"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"fix":"Upgrade both `anndata` and `mudata` to their latest compatible versions: `pip install --upgrade anndata mudata`.","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`.","error":"ValueError: Mismatching AnnData version. MuData requires anndata>=0.10.8 for numpy>=2.0 compatibility."},{"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.","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`.","error":"AttributeError: 'MuData' object has no attribute 'update' (or unexpected behavior of .update())"},{"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.","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.","error":"OSError: Unable to open file (file is not an HDF5 file) or ValueError: Invalid H5Mu format."}]}