grassp.io.write_msnset

Contents

grassp.io.write_msnset#

write_msnset(data, path, *, layer=None, layers=None, nan_to_unknown=True, obs_columns=None, var_columns=None, obsm_keys=None, varm_keys=None, check_normalized=True, write_script=False, overwrite=False)[source]#

Export a grassp AnnData as a pRoloc-ready artifact.

Writes a self-describing h5ad that the companion R package turns into a real MSnSet:

remotes::install_github("czbiohub-sf/grassp", subdir = "r/grasspio")
library(grasspio)
x <- grassp_as_msnset("experiment.h5ad")

Everything crosses by default – .obs, .var, every .obsm and .varm entry, every layer, and the whole of .uns – because the expected next step is to bring the object back with read_msnset(). The exceptions are .obsp/.varp, which eSet has no slot for, and whatever you exclude yourself; both are listed in uns["msnset_dropped"]. Column names and dtypes are written out as they are; the one edit is nan_to_unknown, which swaps grassp’s NaN for the "unknown" string pRoloc requires.

Note that no column is nominated as the marker column. pRoloc’s fcol is a per-call argument, so an MSnSet can carry as many marker columns as it likes – markers, markers.orig, pd.markers – and each function is pointed at whichever it needs, exactly as in AnnData. You choose in R, at the call.

Parameters:
data AnnData

Proteins in .obs, fractions in .var (grassp’s orientation, which already matches MSnSet’s features-by-fractions exprs).

path str | Path

Destination .h5ad.

layer str | None (default: None)

Which matrix becomes exprs(), the one pRoloc’s functions operate on. None uses .X. If you name a layer here, .X itself is not carried, and that is recorded in uns["msnset_dropped"].

layers Optional[Sequence[str]] (default: None)

Additional layers to carry across as extra assayData elements. None (default) sends all of them; pass [] to send none. An MSnSet’s assayData is a Biobase environment holding any number of equal-dimension matrices, so they survive intact and – importantly – are subset together with exprs by markerMSnSet, filterNA and ordinary [ indexing. In R they are reachable with assayDataElementNames(x) and assayDataElement(x, "pvals").

nan_to_unknown bool (default: True)

Replace NaN with "unknown" in every text column of .obs – string, object and Categorical alike; numeric and boolean columns are left alone. pRoloc encodes unlabelled features with that sentinel and needs it: markerMSnSet and unknownMSnSet fail outright on NA, and a classifier’s training set is chosen with fData(object)[, fcol] != "unknown". Applying it to every text column rather than to a nominated one is what lets an object carry several marker sets at once.

obs_columns Optional[Sequence[str]] (default: None)

Restrict what crosses over. None exports everything.

var_columns Optional[Sequence[str]] (default: None)

Restrict what crosses over. None exports everything.

obsm_keys Optional[Sequence[str]] (default: None)

.obsm / .varm entries to export as matrix-valued fData / pData columns. None (default) sends all of them; pass [] to send none. pData is the same AnnotatedDataFrame class as fData, so the two use one mechanism, and R subsets each correctly along its own axis. Column names are taken from uns["obsm_colnames"]/uns["varm_colnames"], else uns[f"{key}_categories"], else the categories of the companion label column, else V1..Vn – so a probability matrix gets its compartment names even when the uns key was never written, which is how portal datasets are curated.

varm_keys Optional[Sequence[str]] (default: None)

.obsm / .varm entries to export as matrix-valued fData / pData columns. None (default) sends all of them; pass [] to send none. pData is the same AnnotatedDataFrame class as fData, so the two use one mechanism, and R subsets each correctly along its own axis. Column names are taken from uns["obsm_colnames"]/uns["varm_colnames"], else uns[f"{key}_categories"], else the categories of the companion label column, else V1..Vn – so a probability matrix gets its compartment names even when the uns key was never written, which is how portal datasets are curated.

check_normalized bool (default: True)

Warn when profiles do not sum to 1 per protein. pRoloc’s distance-based methods and its plots assume sum-normalised profiles; see grassp.pp.normalize_total().

write_script bool (default: False)

Also write <stem>_run_proloc.R next to the artifact: the install line, the grassp_as_msnset call, a worked SVM/TAGM/phenoDisco sequence, and the grassp_write_msnset call to send results back.

overwrite bool (default: False)

Overwrite an existing file rather than raising.

Return type:

Path

Returns:

The path actually written.

Raises:

ValueError – If .obs_names are not unique or contain blanks (R rownames cannot), if layer is missing, or if the destination exists and overwrite is False.

Notes

The contract owns the uns keys in grassp.io._msnset.RESERVED_UNS_KEYS; they are regenerated on every export rather than copied from data.uns, so an artifact always describes itself rather than whatever it was last read from.

Examples

>>> gr.io.write_msnset(adata, "experiment.h5ad", write_script=True)
PosixPath('experiment.h5ad')
Contents