alphapepttools.io.mulink_from_anndatas

alphapepttools.io.mulink_from_anndatas(anndatas, *, transitive_closure=True)

Build a mudata.MuData with cross-level feature linkage from a set of AnnData objects.

Combines one AnnData per feature level (genes, proteins, peptides, precursors) into a single MuData and attaches a sparse adjacency matrix to .varp["feature_mapping"] that links features across levels. The resulting object can be queried with link to filter the hierarchy by ancestors or descendants of a set of features (see Examples).

The cross-level mapping is reconstructed entirely from each AnnData’s .var: each non-coarsest level must carry the higher, i.e. coarser level’s feature-id column. When the AnnData objects come from alphapepttools.io.read_psm_table(), this is controlled by the var_columns argument of that function. The original .var, .obs, and .X of each input AnnData are preserved unchanged on the corresponding modality of the returned MuData.

Parameters:

• anndatas (dict[Literal['genes', 'proteins', 'peptides', 'precursors'], AnnData]) – Dictionary mapping feature levels to AnnData objects. Keys must be a subset of {"genes", "proteins", "peptides", "precursors"}. Each AnnData’s var index name must equal the level’s feature-id column (e.g. "proteins" for the proteins level), and each non-coarsest level must include the next-coarser level’s id as a column in .var, e.g. precursors.var must contain a column named proteins if it is to be linked to a protein-level AnnData object.

• transitive_closure (bool (default: True)) – If True (default), the linkage matrix encodes all reachable (u, v) pairs across levels, so e.g. precursors are directly linked to genes without going through peptides or proteins. If False, only direct (adjacent-level) edges are stored.

Return type:

MuData

Returns:

mudata.MuData MuData with one modality per input level and the cross-level adjacency matrix attached at .varp["feature_mapping"].

Examples

Read precursor-, protein-, and gene-level AnnData objects and assemble them into a MuLink instance. The var_columns argument is what makes the levels linkable: each level needs the next-coarser level’s id as a column in .var.

import alphapepttools as apt

data_path = apt.data.get_data("bader2020_psm_diann")

adata_precursor = apt.io.read_psm_table(
    file_paths=data_path / "top20_report.parquet",
    search_engine="diann",
    level="precursors",
    var_columns=["proteins", "genes"],
)

adata_protein = apt.io.read_psm_table(
    file_paths=data_path / "top20_report.parquet",
    search_engine="diann",
    level="proteins",
    var_columns="genes",
)

mlink = apt.io.mulink_from_anndatas(
    anndatas={
        "precursors": adata_precursor,
        "proteins": adata_protein,
    }
)

Filter the MuData down to features linked to a set of genes via the link query accessor. Each .mod[level] is the original AnnData restricted to the matched features, with .obs and .var intact:

filtered = mlink.link.query.ancestors(["TF", "SERPINA3"])
filtered_proteins = filtered.mod["proteins"]
filtered_precursors = filtered.mod["precursors"]