Skip to content

Data I/O (mtb.io)

Write your data as a dataset folder the methods can read, and read its canonical .h5 files back.

Name Summary
mtb.io.export_dataset Write an AnnData / MuData (or loose objects) as a canonical dataset folder.
mtb.io.read Read a canonical .h5 (a dataset file or an embedding.h5) as an AnnData.

mtb.io.export_dataset

export_dataset(
    data,
    dataset_dir: Path | str,
    *,
    rna="X",
    adt=None,
    atac=None,
    atac_kind: str | None = None,
    labels=None,
    batch=None,
    category: str | None = None,
    adt_names: list | None = None,
    batch_index: int | None = None,
    overwrite: bool = False,
) -> Path

Write an AnnData / MuData (or loose objects) as a canonical dataset folder.

Produces the dataset folder layout (rna.h5, adt.h5, ATAC files, cty.csv), so mtb.scan and mtb.run work on your own data. Give raw counts. The files of each category are listed at https://dsichang.github.io/scMultiBench/tutorials/run/#folder-layout.

PARAMETERS DESCRIPTION
data

Object the selector strings refer to; None when every modality is passed as an object. With a MuData, name each modality (rna='rna').

type (AnnData, MuData or None)

dataset_dir

Folder to create; its name is the dataset id for mtb.scan / mtb.run, and its parent their data_path.

type Path | str

rna

Raw-count matrix for RNA: a selector against data ('layer:counts', 'X[feature_types=Gene Expression]') or an AnnData, DataFrame or array; None = no RNA.

type (str, AnnData, DataFrame, array or None) default 'X'

adt

Raw-count matrix for protein (ADT), same forms as rna (e.g. 'obsm:protein'); None = no ADT.

type (str, AnnData, DataFrame, array or None) default None

atac

ATAC matrix, same forms as rna (e.g. 'X[feature_types=Peaks]'); None = no ATAC.

type (str, AnnData, DataFrame, array or None) default None

atac_kind

What atac holds: 'peak' or 'gene_activity'; decides the ATAC filename. None = read from the feature names: peaks (chr1:100-200) or the RNA's gene names.

type str or None default None

labels

Cell-type labels: a column, named 'obs:<col>' or '<col>' (a MuData's global .obs), '<mod>:<col>' (mdata[mod].obs), a Series indexed by barcode, or a sequence.

type (str, Series, sequence or None) default None

batch

Batch per cell, same forms as labels; splits the files per batch (rna1.h5, rna2.h5, ...) for mosaic or cross. Every cell needs a batch.

type (str, Series, sequence or None) default None

category

Integration category the folder is for (vertical, diagonal, mosaic or cross); sets the ATAC and label filenames.

type str or None default None

adt_names

Protein names for the ADT matrix; they override any it carries and are needed when it has none.

type list or None default None

batch_index

Write the whole object as batch N (rna<N>.h5, cty<N>.csv); mosaic, cross or diagonal in several batches, one call per batch.

type int or None default None

overwrite

True = replace files already in dataset_dir; False = raise before writing anything.

type bool default False

RETURNS DESCRIPTION
Path

dataset_dir.

RAISES DESCRIPTION
TypeError

data is not an AnnData, MuData or None.

ValueError

Missing or conflicting arguments, a missing label or batch, or cells that do not pair across modalities.

KeyError

A selector names a mod, obsm, layer, obs or var column that is absent.

FileExistsError

A file this call would write exists and overwrite is False, or the folder holds files of other data.

WARNS DESCRIPTION
UserWarning

Values that are not whole numbers, or feature names that are missing or repeated.

Examples

>>> import multibench as mtb
>>> mtb.io.export_dataset(adata, "data/MYCITE", rna="layer:counts",
...                       adt="obsm:protein", labels="obs:celltype")
>>> mtb.io.export_dataset(mdata, "data/MYMULTIOME", rna="rna", atac="atac",
...                       atac_kind="peak", labels="obs:celltype",
...                       category="vertical")
See Also

mtb.scan : confirm the folder is found and which methods can run on it.

mtb.io.read

read(path: Path | str)

Read a canonical .h5 (a dataset file or an embedding.h5) as an AnnData.

matrix/data (features x cells) becomes .X (cells x features, CSR when fewer than half of the entries are non-zero), matrix/features the var_names and matrix/barcodes the obs_names. A method's embedding.h5 goes to .obsm["X_emb"] of an AnnData without features.

PARAMETERS DESCRIPTION
path

Canonical .h5 file.

type Path | str

RETURNS DESCRIPTION
AnnData
RAISES DESCRIPTION
FileNotFoundError

path does not exist.

ValueError

path is a 10x Genomics .h5 file; the message says how to read it.

Examples

>>> import multibench as mtb
>>> rna = mtb.io.read(mtb.config.data_path / "D11" / "rna.h5")