grassp.tl.calculate_interfacialness_score#
- calculate_interfacialness_score(data, compartment_annotation_column, neighbors_key=None, obsp=None, exclude_category=None, flavor='evenness')[source]#
Quantify interfacialness: how much a protein sits between two compartments.
Both flavors look at each protein’s direct neighbours in the neighbour graph and pick the same two partite compartments:
Count the protein’s neighbours in each compartment of
compartment_annotation_column(d_cfor compartment c).Only compartments holding at least 3 of the neighbours are eligible.
Rank the eligible compartments by
d_c / N_c, whereN_cis the number of proteins annotated as c in the dataset, and take the top two:k1andk2with neighbour countsd1andd2.
Proteins with fewer than two eligible compartments score 0. The flavors differ only in how
d1andd2are turned into a score.flavor="evenness"(default)score = 2 * min(d1, d2) / (d1 + d2): how evenly the protein’s neighbours split between the two compartments. 1 is an even split; an r:1 split scores2 / (r + 1)(0.67 for 2:1, 0.5 for 3:1, 0.2 for 9:1). Compartment size does not enter the score, so the boundary between two large compartments (e.g. cytosol and nucleus) scores like the boundary between two small ones. The score is not long-tailed, so call proteins interfacial with a fixed split, e.g.score >= 2/3(at least 2:1), rather than with an outlier rule.Exclude catch-all labels such as
"unclassified"(exclude_category): proteins without a clear localization lie between clusters, so being next to them would otherwise read as an even split.flavor="hein2024"The modified Jaccard coefficient of Hein et al., Cell (2025), Fig. 3D (https://www.cell.com/cell/fulltext/S0092-8674(24)01344-8),
score = (d1 + d2) / (N_k1 + N_k2 - (d1 + d2)). This reproduces the paper’s implementation (czbiohub-sf/Organelle_IP_analyses_and_figures, scriptutils/Jaccard_coefficient.py), which used theconnectivitiesgraph, the consensus graph-based annotation with"unclassified"counted as a compartment, and called proteins interfacial above the 1.5 IQR upper bound of all scores (0.046).This score is dominated by compartment size.
d1 + d2is bounded by the number of neighbours (a few dozen), whileN_k1 + N_k2ranges from tens to thousands of proteins, so the score mostly tracks1 / (N_k1 + N_k2). A protein split evenly between cytosol and nucleus can score at most ~0.008 (with 26 neighbours), far below the paper’s cutoff, while a protein inside a small compartment with only three neighbours in another small one can exceed it. How evenly the neighbours split does not enter the score, and proteins with many neighbours in the symmetrised graph score higher.
- Parameters:
- data
AnnData anndata.AnnDatawith a neighbour graph and compartment annotations for each protein.- compartment_annotation_column
str Observation column containing the ground-truth compartment labels.
- neighbors_key
str|None(default:None) Specify which neighbour graph to use (mirrors Scanpy conventions).
- obsp
str|None(default:None) Specify which neighbour graph to use (mirrors Scanpy conventions).
- exclude_category
Union[str,List[str],None] (default:None) One or multiple category labels (e.g. ‘unclassified’) to ignore when counting neighbours.
- flavor
Literal['evenness','hein2024'] (default:'evenness') "evenness"(default) or"hein2024"; see above.
- data
- Return type:
- Returns:
AnnDataobject with additional columns:interfacial_scoreInterfacialness score of the chosen
flavor; 0 with fewer than two partites.interfacial_d1,interfacial_d2Neighbour counts in the two partite compartments.
interfacial_k1,interfacial_k2Corresponding compartment labels; missing when fewer than two (or no) compartments hold at least three of the protein’s neighbours.
and
uns["interfacial_params"]recordingflavor, the annotation column andexclude_category.