grassp.tl.ccompass

Contents

grassp.tl.ccompass#

ccompass(data, marker_key='markers', *, condition_key=None, replicate_key=None, layer=None, scale=True, nn_params=None, reliability=None, key_added='ccompass', max_processes=1, aggregate=True, set_colors=True, inplace=True)[source]#

Predict compartment class contributions with the C-COMPASS neural network.

Converts data into the profile dictionaries expected by C-COMPASS, trains its multi-organelle network (per condition x replicate, ensembled over rounds x subrounds), and – when aggregate is True – runs C-COMPASS’s stats_proteome() to obtain reliability-filtered class contributions. Results are written into data following the same conventions as competitive_propagation().

Parameters:
data AnnData

AnnData with proteins in .obs and fractions in .var. .X (or layers[layer]) holds the fractionation profiles.

marker_key str (default: 'markers')

.obs column with known compartment labels (e.g. added by grassp.pp.add_markers()). NaN entries are treated as unlabeled proteins to be predicted.

condition_key str | None (default: None)

Optional .var columns identifying biological condition and replicate. When replicate_key is given, each replicate is trained as an independent network and averaged afterwards (C-COMPASS’s "separate" combination mode). When omitted, all samples are treated as a single condition/replicate.

replicate_key str | None (default: None)

Optional .var columns identifying biological condition and replicate. When replicate_key is given, each replicate is trained as an independent network and averaged afterwards (C-COMPASS’s "separate" combination mode). When omitted, all samples are treated as a single condition/replicate.

layer str | None (default: None)

Layer to use as the profile matrix. None uses .X.

scale bool (default: True)

If True (default), min-max scale each protein profile to [0, 1] across fractions, reproducing C-COMPASS’s per-profile normalization. Disable if the profiles are already normalized.

nn_params Any (default: None)

Neural-network / training / fCC hyperparameters. One of: None (grassp defaults), a dict of overrides, a path to a YAML/JSON parameter file (the same pydantic serialization C-COMPASS uses for its own settings/session files), or a fully-built ccompass.core.NeuralNetworkParametersModel. Every C-COMPASS hyperparameter is settable this way (upsampling, svm_filter, mixed_part, NN_epochs, rounds, subrounds, reliability, …). For None/dict/file inputs the first-hidden-layer search defaults to NN_optimization="short" (matching the C-COMPASS paper) unless you set it explicitly; a fully-built model is used exactly as given. The resolved hyperparameters are recorded in adata.uns[f"{key_added}_nn_params"]. Call ccompass_default_params() to inspect every field and its default, or to write an editable YAML template.

reliability int | None (default: None)

Percentile (0-100) for the false-positive filter that produces fCC / fNN_winner. Overrides nn_params.reliability when given.

key_added str (default: 'ccompass')

Prefix for the result slots (default "ccompass"). With more than one condition, the condition name is appended ("{key_added}_{condition}").

max_processes int (default: 1)

Number of worker processes for C-COMPASS (one per condition x round).

aggregate bool (default: True)

If True (default), reconcile rounds/replicates via stats_proteome() and write both raw (CC) and reliability-filtered (fCC) contributions. If False, only average the raw per-round network outputs.

set_colors bool (default: True)

If True, assign compartment colors to the new .obs label columns via grassp.pp.set_sensible_compartment_colors().

inplace bool (default: True)

If True (default) write into data and return None; otherwise return the C-COMPASS class_predictions dictionary.

Returns:

Modified data (in place) with, per condition suffix ("" for a single condition, else "_{condition}"):

  • .obsm[f"{key_added}{suffix}_contributions"] – proteins x compartments class-contribution matrix (rows sum to ~1).

  • .uns[f"{key_added}{suffix}_categories"] – ordered compartment names.

  • .obs[f"{key_added}{suffix}"] – winning compartment (argmax, NN_winner).

  • When aggregate: .obsm[f"{key_added}{suffix}_fcontributions"] and .obs[f"{key_added}{suffix}_fwinner"] – reliability-filtered outputs.

Notes

C-COMPASS distinguishes genuine multi-localization from measurement noise by training on synthetic mixtures of marker profiles, ensembling over many training rounds, and thresholding each contribution against the values that markers of other compartments receive (the reliability percentile). This differs from grassp’s native permutation-null approach in resolve_soft_labels(), so results are complementary rather than identical.

Contents