grassp.io.read_proloc_results

grassp.io.read_proloc_results#

read_proloc_results(path, data, *, key_prefix='', suffix='', on_missing='warn', on_extra='warn', set_colors=True, id_column=None, strict_spec=True, copy=False)[source]#

Graft a pRoloc artifact’s annotations onto an AnnData you already have.

A convenience wrapper over read_msnset(), for keeping an in-memory session going: prefer the plain round trip (read_msnset) unless you specifically want to keep an object you have been working on. It merges rather than replaces – .X, .layers, .obsp, .varp, .var and .varm are never touched, and rows are never reordered or dropped – which is also its limitation: matrices the R side altered do not come back.

What it does write, it writes under the artifact’s own names, so a same-named .obs column or .obsm entry is replaced. Since an export carries every .obsm entry by default, that routinely includes your embeddings, with values that made the trip unchanged. Pass key_prefix or suffix to keep the two apart.

Beyond aligning rows on .obs_names, it changes nothing. Every .obs column is copied under its own name with its own dtype, and every .obsm matrix likewise. There is no notion of which method produced a column, so svm, knn, rf, plsda, nnet, perTurbo, ksvm, phenoDisco, TAGM, BANDLE and anything added to pRoloc later all work identically – and what you see in Python is what fvarLabels(x) showed in R.

Parameters:
path str | Path | AnnData

Path to an h5ad written by grasspio’s grassp_write_msnset, or an in-memory AnnData.

data AnnData

The object to merge onto. Matched on .obs_names.

key_prefix str (default: '')

Affixed to every key written, e.g. suffix="_control" to keep two conditions apart.

suffix str (default: '')

Affixed to every key written, e.g. suffix="_control" to keep two conditions apart.

on_missing Literal['error', 'warn', 'ignore'] (default: 'warn')

What to do when the artifact lacks proteins present in data (on_missing) or contains proteins absent from it (on_extra). One of "error", "warn" (default) or "ignore". Missing proteins get NaN / all-zero .obsm rows.

on_extra Literal['error', 'warn', 'ignore'] (default: 'warn')

What to do when the artifact lacks proteins present in data (on_missing) or contains proteins absent from it (on_extra). One of "error", "warn" (default) or "ignore". Missing proteins get NaN / all-zero .obsm rows.

set_colors bool (default: True)

Assign compartment colours via grassp.preprocessing.set_sensible_compartment_colors(), which decides for itself which of the new columns look like compartment annotations.

id_column str | None (default: None)

.obs column in the artifact holding the protein IDs, if the R side renamed features. Defaults to using the artifact’s index.

strict_spec bool (default: True)

Whether an artifact written by a newer contract version raises rather than warns.

copy bool (default: False)

Return a modified copy instead of writing into data.

Return type:

AnnData | None

Returns:

None when copy is False (data is modified in place), otherwise the modified copy. It writes:

  • .obs[<every column>] and .obsm[<every matrix>] – under pRoloc’s names.

  • .uns["obsm_colnames"][...] – class names for every matrix. This is the only place they can live, because .obsm arrays carry no column names.

  • .uns["proloc_import"] – provenance: source, contract version, what was copied, match counts, and any advisory notes about columns pRoloc is known to misname.

Notes

"unknown" has already become NaN by the time results arrive: the companion R package converts on the way out, because that sentinel is pRoloc’s convention and belongs on pRoloc’s side. If you are reading a .rda instead, read_prolocdata() does the same thing itself, since no R is involved there.

Names are preserved rather than translated, so pass pRoloc’s own score column where a grassp plotting helper wants a probability: gr.pl.umap_prob(adata, color="svm.pred", color_prob="svm.scores").

Examples

>>> gr.io.read_proloc_results("results.h5ad", adata)
>>> adata.obs["tagm.map.allocation"].value_counts()
>>> adata.obsm["svm.all.scores"].shape
>>> adata.uns["obsm_colnames"]["svm.all.scores"]