grassp.tl.calculate_interfacialness_score

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:

  1. Count the protein’s neighbours in each compartment of compartment_annotation_column (d_c for compartment c).

  2. Only compartments holding at least 3 of the neighbours are eligible.

  3. Rank the eligible compartments by d_c / N_c, where N_c is the number of proteins annotated as c in the dataset, and take the top two: k1 and k2 with neighbour counts d1 and d2.

Proteins with fewer than two eligible compartments score 0. The flavors differ only in how d1 and d2 are 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 scores 2 / (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, script utils/Jaccard_coefficient.py), which used the connectivities graph, 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 + d2 is bounded by the number of neighbours (a few dozen), while N_k1 + N_k2 ranges from tens to thousands of proteins, so the score mostly tracks 1 / (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.AnnData with 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.

Return type:

AnnData

Returns:

AnnData object with additional columns:

interfacial_score

Interfacialness score of the chosen flavor; 0 with fewer than two partites.

interfacial_d1, interfacial_d2

Neighbour counts in the two partite compartments.

interfacial_k1, interfacial_k2

Corresponding compartment labels; missing when fewer than two (or no) compartments hold at least three of the protein’s neighbours.

and uns["interfacial_params"] recording flavor, the annotation column and exclude_category.