Prediction and label transfer¶
Two supervised uses of the sample embedding uns['X_DR_sample'] (new in 0.5.0):
predict_phenotypepredicts a sample phenotype from the first k PCs with cross-validation, and reports how well it can be predicted.transfer_labelslabels new or unlabelled samples from their nearest labelled neighbours in the embedding.
Both take the one-row-per-sample AnnData from build_sample_adata (see Before you start) and read labels from its .obs. They return tables and write no files. The config-driven wrapper does not run them; call them from Python.
Phenotype prediction¶
from sampledisco import predict_phenotype
pred, metrics = predict_phenotype(
pseudo_adata,
label_col="sev.level", # binary or multiclass label in pseudo_adata.obs
group_col=None, # e.g. "donor" when a donor has several samples
n_pcs=None, # first k PCs; None = all
task="classification", # or "regression" for a continuous phenotype
score_by="sample", # or "group": score the per-group mean prediction
n_splits=5,
random_state=0,
)
print(metrics["auc"], metrics["balanced_accuracy"])
Model. The PCs are standardized. A classification label is fitted with an L2 logistic regression (binary or multiclass), a continuous one with ridge regression. The penalty is chosen by an inner 3-fold cross-validation inside each training split, scored by AUC (binary), balanced accuracy (multiclass) or R², from C in {10, 1, 0.1, 0.01} or alpha in {0.1, 1, 10, 100}; when several penalties score equally, the weakest is kept. The outer split is n_splits-fold, stratified by class and seeded by random_state. Each sample is predicted once, by the model trained without its fold. Samples with a missing label are skipped. This is the model used for the Sound Life trait prediction in the SampleDisco paper.
Use group_col when a donor has several samples
With repeated draws of a donor, or several units of one sample, pass the donor (or sample) column as group_col. Every sample of a group then stays in one fold, both in the outer and in the inner split. Without it, a model can recognise the donor rather than the phenotype, and the scores are inflated.
Scoring level. By default every sample is scored. With score_by="group", the out-of-fold probabilities (or predictions) and the labels are first averaged within each group_col group (the majority label for classification), so each donor counts once. This is how the paper's donor-level AUCs were computed:
pred, metrics = predict_phenotype(pseudo_adata, "cmv", group_col="donor", score_by="group")
print(metrics["auc"]) # one point per donor
Returns (pred, metrics):
pred: a DataFrame indexed by sample, withlabel,predicted,foldand, for classification, oneprob_<class>column per class (out-of-fold). It is per sample for bothscore_byvalues.metrics: a dict withscore_by,n_samples,n_groups,n_pcs, the penalty chosen in each fold (Coralpha), andauc(binary; the second class in sorted order is positive),accuracy,balanced_accuracy, orr2, computed at thescore_bylevel.
Label transfer¶
from sampledisco import transfer_labels
table, metrics = transfer_labels(
pseudo_adata,
label_col="sev.level", # samples with a missing value are the queries
query=None, # or a boolean mask: hold out labelled samples as queries
n_neighbors=5,
weighted=False, # True: each neighbour votes with weight 1/distance
n_pcs=None,
group_col=None, # e.g. "donor"; "sample" for multi-omics units
)
print(table[table["query"]])
print(metrics["loo_accuracy"])
Each query takes the majority label of its n_neighbors nearest labelled samples (Euclidean distance on the first n_pcs PCs). Ties go to the label of the nearest tied neighbour. The confidence is the share of the votes won by the assigned label (weighted by 1/distance with weighted=True).
To judge how far to trust the transfer, every labelled sample is also labelled from the other labelled samples (leave-one-out). With group_col, the other samples of the same group are left out as well. For multi-omics this matters: the RNA and ATAC units of one sample are usually each other's nearest neighbours, so pass group_col="sample".
Returns (table, metrics):
table: a DataFrame indexed by sample, withlabel(the input),query(True for samples that were labelled by the transfer),predicted(the transferred label for queries, the leave-one-out label for labelled samples) andconfidence.metrics: a dict withloo_accuracy,loo_balanced_accuracy,n_reference,n_query,n_neighborsandn_pcs.
Small cohorts
Both scores are estimates from the labelled samples. With few samples per class (the 8-sample demo has 4 per class) they are very noisy; use them to check that the call works, not to judge the embedding.
See the API pages for predict_phenotype and transfer_labels.