plastro.PLASTRO_score

plastro.PLASTRO_score(character_matrix: DataFrame, ad: AnnData, threshold: float = 0.95, maximum_radius: int = 500, interval: int = 1, latent_space_key: str = 'X_dm', flavor: str = 'gini', parallel: bool = False, save_to: str | None = None, show_plots: bool = True) → DataFrame[source]

Compute the PLASTRO overlap plasticity score.

The PLASTRO score quantifies cellular plasticity by measuring the overlap between lineage relationships (from character matrix) and phenotypic relationships (from latent space) at multiple spatial scales.

Parameters:

  • character_matrix (pd.DataFrame) – Character matrix with cells as rows and CRISPR mutation sites as columns. Values represent mutation states (0=unmutated, >0=mutated states).

  • ad (anndata.AnnData) – Annotated data object containing latent representation of phenotype.

  • threshold (float, optional) – Threshold for variance in overlap (proportion of max peak variance), by default 0.95. Only used when flavor=’variable_radii’. Radii with variance >= threshold * max_variance are used for computing the final score.

  • maximum_radius (int, optional) – Maximum radius for computing overlap, by default 500.

  • interval (int, optional) – Interval between radii for overlap computation, by default 1.

  • latent_space_key (str, optional) – Key in ad.obsm where latent space coordinates are stored, by default ‘X_dm’.

  • flavor (str, optional) –

    Method for computing PLASTRO score, by default ‘gini’.

    • ’gini’: Computes Gini inequality index for each cell’s overlap distribution across radii. Measures how concentrated the overlap is at specific spatial scales.

      • High Gini (→1): Overlap concentrated at few radii (unequal distribution)

      • Low Gini (→0): Overlap evenly distributed across radii (equal distribution)

      • Uses ALL radii from 1 to maximum_radius

    • ’variable_radii’: Computes area under overlap curve using variance-filtered radii. Measures strength of lineage-phenotype concordance at most informative scales.

      • High score: Strong lineage-phenotype concordance (low plasticity)

      • Low score: Weak lineage-phenotype concordance (high plasticity)

      • Uses SELECTED radii based on variance threshold

  • parallel (bool, optional) – Whether to use parallel processing, by default False.

  • save_to (str, optional) – Directory path to save results, by default None.

  • show_plots (bool, optional) – Whether to display variance analysis plots (only for flavor=’variable_radii’), by default True.

Returns:

PLASTRO plasticity scores for each cell. Column name depends on flavor:

  • flavor=’gini’: Column ‘Gini_Index’ with values [0,1]

  • flavor=’variable_radii’: Column ‘PLASTRO_score’ with positive values

Return type:

pd.DataFrame

Examples

>>> import plastro
>>>
>>> # Compute Gini-based plasticity scores
>>> gini_scores = plastro.PLASTRO_score(char_matrix, ad, flavor='gini')
>>> print(f"Mean Gini index: {gini_scores['Gini_Index'].mean():.3f}")
>>>
>>> # Compute variance-based plasticity scores
>>> var_scores = plastro.PLASTRO_score(char_matrix, ad, flavor='variable_radii', threshold=0.95)
>>> print(f"Mean PLASTRO score: {var_scores['PLASTRO_score'].mean():.3f}")

Notes

The PLASTRO analysis workflow:

  1. Overlap Computation: For each cell and radius r, compute overlap between: - Lineage neighbors: r cells most similar by CRISPR mutations - Phenotype neighbors: r cells most similar in latent space

  2. Score Computation: Two complementary approaches:

    Gini Approach (flavor=’gini’): - Computes Gini inequality coefficient for each cell’s overlap profile - Measures how overlap varies with spatial scale for individual cells - Interpretation: Distribution pattern of lineage-phenotype concordance

    Variable Radii Approach (flavor=’variable_radii’): - Identifies radii with high variance in overlap across cells - Computes area under overlap curve for informative radii only - Interpretation: Overall strength of lineage-phenotype concordance

When to use each flavor:

  • Use ‘gini’ to understand overlap distribution patterns per cell

  • Use ‘variable_radii’ to measure overall plasticity strength

  • Both provide complementary views of the same underlying relationships