Tools: tl#

This module provides various tools for analyzing proteomics data.

Annotation#

Every annotator writes the same slots, so a result can be read, scored and plotted without knowing which one produced it:

slot

contents

obsm[f"{key_added}_probabilities"]

one column per compartment, named

obs[key_added]

the call, NaN where it abstained

obs[f"{key_added}_probability"]

the probability of that call

uns[f"{key_added}_params"]

which annotator, and what it was told

uns[f"{key_added}_colors"]

in the category order of obs[key_added]

uns[f"{key_added}_params"]["kind"] says how to read the matrix. "simplex" means the compartments competed for one unit of mass, so the rows sum to 1 and an argmax is a call. "per_term" means each column is an independent membership probability; the rows do not sum to anything in particular, and resolving them into a call is a separate step.

Which annotator? If you have marker proteins and want one compartment each, use competitive_diffusion() (graph) or svm_annotation() / tagm_map_predict() (feature-space classifiers). If your labels overlap or nest — GO-CC, UniProt-SL — use independent_diffusion(), which does not force them to compete. If you have clusters and an enrichment table rather than markers, use soft_cluster_annotation().

Graph label propagation#

Mutually exclusive labels spread over the k-NN graph and compete, giving a simplex.

tl.competitive_diffusion

Propagate categorical annotations along the k-NN graph.

Marker-supervised classifiers#

Fitted in feature space on marker proteins rather than on the graph.

tl.svm_tune_hyperparameters

Grid-search the SVM's C and gamma over marker proteins.

tl.svm_annotation

Classify proteins using SVM with marker-based training.

tl.tagm_map_train

Train a TAGM-MAP (T-Augmented Gaussian Mixture, MAP variant) model.

tl.tagm_map_predict

Predict sub-cellular localization for unlabelled proteins using a fitted TAGM-MAP model.

tl.tagm_model

Fetch the stored TAGM model, preferring the current key.

tl.ccompass

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

tl.ccompass_default_params

Return (and optionally save) the default C-COMPASS hyperparameters used by ccompass().

Ontology-aware annotation#

Overlapping or hierarchical labels, diffused one-vs-rest so they do not compete. The result is a per-term membership probability, and resolving it into a call is explicit.

tl.independent_diffusion

Annotate a map with overlapping / hierarchical labels by one-vs-rest diffusion.

tl.resolve_diffusion

(Re)resolve stored diffusion probabilities into a per-protein label, in place.

tl.load_gmt

Resolve a gene-set source into a {term: [gene, ...]} dict.

Soft cluster annotation#

Propagate the uncertainty of a per-cluster enrichment rather than one hard top term. Listed in pipeline order; soft_cluster_annotation ties all three together.

tl.enrichment_to_cluster_distribution

Turn a per-cluster enrichment table into soft label distributions.

tl.mgsa_to_cluster_distribution

Convert a per-cluster MGSA posterior matrix into a soft-label distribution.

tl.soft_cluster_annotation

Soft, uncertainty-aware version of the cluster-annotation pipeline.

tl.resolve_soft_labels

Resolve soft propagated probabilities into single / multi / unresolved labels.

Marker QC and evaluation#

Clean a marker set before annotating, and score any annotation against ground truth. These take (gt_col, pred_col) and work for every annotator above.

tl.prune_markers

Remove "outliers" from marker proteins whose compartment label is not supported by their k-NN neighbourhood.

tl.annotation_f1_score

F1 score of a predicted annotation against ground-truth labels.

tl.annotation_confusion_matrix

Confusion matrix of a predicted annotation against ground-truth labels.

tl.class_balance

Return a balanced subset with equally sized clusters.

Clustering#

tl.leiden_mito_sweep

Automated sweep to pick a Leiden resolution that keeps mitochondria intact.

tl.markov_clustering

Run Markov Clustering (MCL) on the neighbour graph.

tl.calculate_interfacialness_score

Quantify interfacialness: how much a protein sits between two compartments.

tl.silhouette_score

Per-group silhouette scores.

tl.calinski_habarasz_score

Calinski–Harabasz score of cluster compactness vs separation.

tl.qsep_score

QSep cluster-separation metric for spatial proteomics.

Cluster Merging#

Consolidate overclustered Leiden solutions using PAGA connectivity and ontology enrichment.

tl.merge_clusters_go

Iteratively merge overclustered Leiden clusters using PAGA and GO enrichment.

tl.merge_small_clusters

Iteratively merge small clusters into their most-connected neighbor.

tl.paga_dendrogram

Build a dendrogram from PAGA connectivity and store it in adata.uns.

tl.dendrogram_cherry_pairs

Return all candidate merge pairs from the dendrogram, expanding ties.

Ontology Enrichment#

tl.calculate_cluster_enrichment

Gene-set enrichment for each cluster.

Model-based Gene Set Analysis#

MGSA explains an observed protein set with a sparse set of ontology terms, rather than testing each term independently.

tl.mgsa

Run model-based gene set analysis.

tl.calculate_mgsa

Model-based gene-set analysis (MGSA) per cluster.

tl.MgsaResult

Container for MGSA posterior summaries and diagnostics.

Integration#

tl.align_adatas

Return copies of several AnnData objects with matching index/columns.

tl.aligned_umap

Aligned UMAP embedding for matched datasets.

tl.remodeling_score

Compute per-protein remodeling score from two aligned datasets.

tl.mr_score

M/R score for detecting protein translocation.

Graph analysis#

tl.to_knn_graph

Convert the k-NN graph stored in AnnData to a networkx graph.

tl.get_n_nearest_neighbors

Return the set of closest neighbours for a node in a graph.

Deprecated#

Kept for one release each so existing code keeps running; both emit a DeprecationWarning and forward to :func:~grassp.tl.competitive_diffusion.

tl.competitive_propagation

Deprecated alias for competitive_diffusion().

tl.knn_annotation

Deprecated alias for competitive_diffusion().