I/O (gd.io)

The I/O module wraps standard AnnData and MuData readers and writers and provides a safe, compact format for persisting the result tree stored in .uns.

Reading annotated data

read_h5ad

Read H5AD file.

read_h5mu

Read an H5MU file into a mudata.MuData object.

read_10x_h5

Read 10X Genomics H5 file.

read_10x_mtx

Read 10X Genomics MTX directory.
multigedi.io.read_h5ad(filename, *, backed=None)[source]

Read H5AD file.

Wrapper around anndata.read_h5ad() with consistent interface.

Parameters:

  • filename (str | Path) – Path to the H5AD file.

  • backed (str | None, default: None) – If 'r', open in read-only backed mode. If 'r+', open in read-write backed mode. If None, load into memory.

Return type:

Annotated data matrix.

Examples

>>> import multigedi as gd
>>> adata = gd.read_h5ad("data.h5ad")
multigedi.io.read_h5mu(filename, *, backed=None)[source]

Read an H5MU file into a mudata.MuData object.

Wrapper around mudata.read_h5mu() with a consistent interface matching multigedi.io.read_h5ad().

Parameters:

  • filename (str | Path) – Path to the H5MU file.

  • backed (str | None, default: None) – If 'r', open in read-only backed mode. If 'r+', open in read-write backed mode. If None, load into memory.

Return type:

Multi-modal annotated data container.

Examples

>>> import multigedi as gd
>>> mdata = gd.io.read_h5mu("data.h5mu")
>>> gd.tl.multigedi(mdata, modalities={"gene": {}}, sample_key="sample")
multigedi.io.read_10x_h5(filename, *, genome=None, gex_only=True)[source]

Read 10X Genomics H5 file.

Reads gene expression data from 10X Genomics HDF5 format files, including those from Cell Ranger.

Parameters:

  • filename (str | Path) – Path to the 10X H5 file.

  • genome (str | None, default: None) – Genome name to read (for multi-genome references). If None, reads the first available genome.

  • gex_only (bool, default: True) – If True, only read gene expression features (exclude antibody capture, CRISPR, etc. for multi-modal data).

Returns:

  • X: Sparse count matrix (cells × genes)

  • obs: Cell barcodes

  • var: Gene information (id, name, feature_type)

Return type:

Annotated data matrix with

Notes

Compatible with:

  • Cell Ranger v2 (matrix.h5)

  • Cell Ranger v3+ (filtered_feature_bc_matrix.h5)

  • Multi-modal outputs

Examples

>>> import multigedi as gd
>>> adata = gd.read_10x_h5("filtered_feature_bc_matrix.h5")
>>> adata
AnnData object with n_obs × n_vars = 5000 × 20000
multigedi.io.read_10x_mtx(path, *, var_names='gene_symbols', make_unique=True)[source]

Read 10X Genomics MTX directory.

Reads gene expression data from 10X Genomics Market Exchange format directory (matrix.mtx, genes.tsv/features.tsv, barcodes.tsv).

Parameters:

  • path (str | Path) – Path to the directory containing matrix files.

  • var_names (str, default: 'gene_symbols') – Which column to use for variable names: 'gene_symbols' or 'gene_ids'.

  • make_unique (bool, default: True) – If True, make variable names unique by appending suffixes.

Return type:

Annotated data matrix.

Examples

>>> import multigedi as gd
>>> adata = gd.read_10x_mtx("filtered_feature_bc_matrix/")

Examples

import multigedi as gd

adata = gd.read_h5ad("data.h5ad")
backed = gd.read_h5ad("large_data.h5ad", backed="r")
mdata = gd.io.read_h5mu("multimodal_data.h5mu")
counts = gd.read_10x_h5("filtered_feature_bc_matrix.h5")
matrix = gd.read_10x_mtx("filtered_feature_bc_matrix/")

read_10x_mtx accepts var_names and make_unique. Other Scanpy reader options are not forwarded by this wrapper.

Writing annotated data

write_h5ad

Write AnnData to H5AD file.

write_h5mu

Write a mudata.MuData object to an H5MU file.
multigedi.io.write_h5ad(adata, filename, *, compression='gzip', compression_opts=None)[source]

Write AnnData to H5AD file.

Wrapper around anndata.AnnData.write_h5ad() with consistent interface.

Parameters:

  • adata (AnnData) – Annotated data matrix to write.

  • filename (str | Path) – Path to output H5AD file.

  • compression (str | None, default: 'gzip') – Compression algorithm. Options: 'gzip', 'lzf', None.

  • compression_opts (int | None, default: None) – Compression level (for gzip, 1-9).

Return type:

None

Examples

>>> import multigedi as gd
>>> gd.write_h5ad(adata, "results.h5ad")
multigedi.io.write_h5mu(mdata, filename, *, compression='gzip', compression_opts=None)[source]

Write a mudata.MuData object to an H5MU file.

Wrapper around mudata.MuData.write_h5mu() with a consistent interface matching multigedi.io.write_h5ad().

Parameters:

  • mdata (MuData) – Multi-modal annotated data container to write.

  • filename (str | Path) – Path to the output H5MU file.

  • compression (str | None, default: 'gzip') – Compression algorithm. Options: 'gzip', 'lzf', None.

  • compression_opts (int | None, default: None) – Compression level (for gzip, 1-9).

Return type:

None

Examples

>>> import multigedi as gd
>>> gd.io.write_h5mu(mdata, "results.h5mu")

Use H5AD or H5MU when the complete annotated object is required. These formats retain the data matrices and the relevant obs, var, layers, obsm, varm, and uns mappings.

gd.write_h5ad(adata, "results.h5ad", compression="gzip")
gd.io.write_h5mu(mdata, "multimodal_results.h5mu", compression="gzip")

Model-result persistence

save_model

Save one GEDI result tree from .uns to a safe NPZ archive.

load_model

Load a safely serialized GEDI result tree into .uns.
multigedi.io.save_model(adata, filename, *, key='gedi', compression='gzip')[source]

Save one GEDI result tree from .uns to a safe NPZ archive.

The archive contains a versioned JSON manifest and separate NumPy array members. It does not contain pickle data. Supported result values are nested dictionaries with string keys, lists, tuples, Python scalars, NumPy scalars, and non-object NumPy arrays.

Parameters:

  • adata (AnnData | MuData) – AnnData or MuData container with GEDI results.

  • filename (str | Path) – Output path. .npz is added when no suffix is supplied; other suffixes are rejected.

  • key (str, default: 'gedi') – Key in adata.uns or mdata.uns containing the result tree.

  • compression (str | None, default: 'gzip') – "gzip" writes a compressed NPZ archive. None writes an uncompressed NPZ archive.

Return type:

None

Notes

This function saves only adata.uns[key] (or mdata.uns[key]). It does not save the data matrix, annotations, layers, embeddings, or loadings. Use H5AD/H5MU persistence when the full annotated object is required.

Examples

>>> import multigedi as gd
>>> gd.tl.gedi(adata, batch_key="sample")
>>> gd.io.save_model(adata, "gedi_model.npz")
multigedi.io.load_model(adata, filename, *, key='gedi')[source]

Load a safely serialized GEDI result tree into .uns.

Only the versioned JSON-manifest NPZ format written by save_model() is accepted. NumPy archives are always opened with allow_pickle=False; legacy archives containing stringified Python dictionaries are rejected.

Parameters:

  • adata (AnnData | MuData) – AnnData or MuData container that receives the result tree.

  • filename (str | Path) – Path to a .npz model archive.

  • key (str, default: 'gedi') – Key in adata.uns or mdata.uns where the loaded tree is stored.

Return type:

None

Notes

Loading restores only adata.uns[key] (or mdata.uns[key]). It does not reconstruct or modify X, obs, var, layers, obsm, or varm. The destination is mutated only after the complete archive has passed validation.

Examples

>>> import multigedi as gd
>>> gd.io.load_model(adata, "gedi_model.npz")
>>> adata.uns["gedi"]["model"]

save_model stores exactly one result tree, container.uns[key], in a versioned NPZ archive. The format uses a strict JSON manifest and separate NumPy array members. It does not use pickle or evaluate serialized Python expressions. Nested dictionaries with string keys, lists, tuples, Python and NumPy scalars, and non-object NumPy arrays are preserved.

For a single-modal result:

gd.tl.gedi(adata, batch_key="sample", n_latent=10)
gd.io.save_model(adata, "gedi_model.npz")

target = gd.read_h5ad("data.h5ad")
gd.io.load_model(target, "gedi_model.npz")
result = target.uns["gedi"]

For the canonical multi-modal result on the MuData container:

gd.io.save_model(mdata, "multigedi_model.npz", key="multigedi")

target = gd.io.read_h5mu("data.h5mu")
gd.io.load_model(target, "multigedi_model.npz", key="multigedi")
result = target.uns["multigedi"]

Important

load_model restores only container.uns[key]. It does not reconstruct or modify the data matrix, annotations, layers, cell embeddings in obsm, or feature loadings in varm. Use H5AD/H5MU to persist a complete analysis object.

Note

Legacy NPZ files that stored stringified Python dictionaries are rejected. Regenerate them from the original trusted analysis with the current save_model. Object arrays are deliberately unsupported.

Top-level convenience exports

The AnnData and 10X helpers are also available at the package top level:

adata = gd.read_h5ad("data.h5ad")
gd.write_h5ad(adata, "output.h5ad")

H5MU and model-result persistence helpers are available through gd.io.