Plasticity Module

The plasticity module provides core functions for simulating cellular plasticity through various mechanisms.

Core Functions

`random_walk_plasticity`(full_simulated_ad, ...)	Simulate random walk plasticity in single cells.
`perform_random_walk`(ad[, plastic_cells, ...])	Perform random walks on a phenotypic graph.
`visualize_walk`(ad, walk_indices[, save_to, ...])	Visualize a random walk path on UMAP coordinates.

Utility Functions

`construct_phenotypic_graph`(ad, latent_space_key)	Construct a k-nearest neighbor graph from latent space coordinates.
`graph_from_connectivities`(adj_matrix, cell_names)	Convert sparse adjacency matrix to NetworkX graph.
`get_distances_of_moves`(G, sources, targets)	Compute shortest path distances between source and target nodes.

Function Details

Core plasticity simulation module.

This module provides functions for simulating different types of cellular plasticity in single-cell datasets, including random walk plasticity and cluster-based switching.

plastro.plasticity.random_walk_plasticity(full_simulated_ad: AnnData, subset_simulated_ad: AnnData, plastic_cells: Dict[str, List[str]], walk_lengths: Dict[str, int], latent_space_key: str = 'X_dc') → AnnData[source]

Simulate random walk plasticity in single cells.

Performs random walks on specified plastic cells to simulate phenotypic transitions. Plastic cells from different leiden clusters perform walks of specified lengths, and their phenotypes are replaced with their walk targets.

Parameters:

full_simulated_ad (anndata.AnnData) – Complete simulated dataset used for performing random walks.
subset_simulated_ad (anndata.AnnData) – Subset of the dataset containing cells to be analyzed.
plastic_cells (Dict[str, List[str]]) – Dictionary mapping leiden cluster identifiers to lists of cell names that will undergo plastic transitions.
walk_lengths (Dict[str, int]) – Dictionary mapping leiden cluster identifiers to walk lengths. Must contain entries for all keys in plastic_cells.
latent_space_key (str, optional) – Key in the obsm attribute of the AnnData object that contains the latent space representation. Default is ‘X_dc’.

Returns:

Modified dataset with plastic cells replaced by their walk targets. Non-plastic cells remain unchanged.

Return type:

anndata.AnnData

Raises:

AssertionError – If walk_lengths keys don’t match plastic_cells keys.

Examples

>>> plastic_cells = {'0': ['Cell_1', 'Cell_2'], '1': ['Cell_3']}
>>> walk_lengths = {'0': 100, '1': 50}
>>> result = random_walk_plasticity(full_ad, subset_ad, plastic_cells, walk_lengths)

Notes

This function modifies cell phenotypes by replacing plastic cells with cells that represent their final positions after random walks. The walk parameters (p, q) are set within the perform_random_walk function.

plastro.plasticity.perform_random_walk(ad, plastic_cells: List[str] | None = None, latent_space_key: str = 'X_dc', walk_length: int = 100, p: float = 0.9, q: float = 1e-10, save_dir: str | None = None) → Tuple[DataFrame, DataFrame, ndarray][source]

Perform random walks on a phenotypic graph.

Constructs a k-nearest neighbor graph from the latent space representation and performs random walks to simulate cellular transitions.

Parameters:

ad (anndata.AnnData) – Annotated data object containing latent space annotations.
plastic_cells (List[str], optional) – List of cell names to perform random walks on. If None, all cells are considered, by default None.
latent_space_key (str, optional) – Key in ad.obsm where latent space coordinates are stored, by default ‘X_dc’.
walk_length (int, optional) – Length of each random walk, by default 100.
p (float, optional) – Return probability - controls likelihood of revisiting previous node, by default 0.9.
q (float, optional) – In-out probability - controls exploration vs exploitation, by default 1e-10.
save_dir (str, optional) – Directory to save walk results, by default None.

Returns:

walk_df: DataFrame with start and target cells for each walk
change_in_phenotype: DataFrame with graph distances moved
walks: Array of walk indices for each cell

Return type:

Tuple[pd.DataFrame, pd.DataFrame, np.ndarray]

Examples

>>> targets, changes, walks = perform_random_walk(ad, ['Cell_1', 'Cell_2'], walk_length=50)
>>> print(f"Cell_1 moved to: {targets.loc['Cell_1', 'target']}")

Notes

Uses Node2Vec-style random walks with parameters p and q
Higher p values encourage returning to previous nodes
Lower q values encourage exploration of new regions

plastro.plasticity.get_distances_of_moves(G: Graph, sources: List[str], targets: List[str]) → ndarray[source]

Compute shortest path distances between source and target nodes.

Parameters:

G (networkx.Graph) – Graph representing phenotypic connectivity.
sources (List[str]) – List of source node names.
targets (List[str]) – List of target node names.

Returns:

Array of shortest path distances between corresponding source-target pairs.

Return type:

np.ndarray

Raises:

AssertionError – If sources and targets have different lengths.

plastro.plasticity.construct_phenotypic_graph(ad: AnnData, latent_space_key: str, n_nbrs: int = 10) → Graph[source]

Construct a k-nearest neighbor graph from latent space coordinates.

Parameters:

ad (anndata.AnnData) – Annotated data object.
latent_space_key (str) – Key in ad.obsm containing latent space coordinates.
n_nbrs (int, optional) – Number of nearest neighbors for graph construction, by default 10.

Returns:

Graph where nodes are cells and edges connect nearest neighbors.

Return type:

networkx.Graph

plastro.plasticity.graph_from_connectivities(adj_matrix, cell_names: List[str]) → Graph[source]

Convert sparse adjacency matrix to NetworkX graph.

Parameters:

adj_matrix (scipy.sparse.csr_matrix) – Sparse adjacency matrix where 1 indicates connected nodes.
cell_names (List[str]) – List of cell names corresponding to matrix rows/columns.

Returns:

Graph with nodes labeled by cell names.

Return type:

networkx.Graph

Raises:

AttributeError – If adj_matrix is not a supported sparse matrix type.

plastro.plasticity.visualize_walk(ad: AnnData, walk_indices: ndarray, save_to: str | None = None, show_plots: bool = False) → None[source]

Visualize a random walk path on UMAP coordinates.

Creates a scatter plot showing the path of a single random walk, with origin and target cells highlighted.

Parameters:

ad (anndata.AnnData) – AnnData object containing UMAP coordinates in obsm[‘X_umap’].
walk_indices (np.ndarray) – 1D array of cell indices representing the walk path.
save_to (str, optional) – Directory to save the plot, by default None.
show_plots (bool, optional) – Whether to display plots interactively, by default False.

Examples

>>> _, _, walks = perform_random_walk(ad, ['Cell_1'])
>>> visualize_walk(ad, walks[0])

Notes

Requires UMAP coordinates in ad.obsm[‘X_umap’]
Origin cell is marked with a black star
Target cell is marked with a red star
Intermediate cells are colored with a gradient

plastro.plasticity.cluster_switch_plasticity(full_simulated_ad: AnnData, subset_simulated_ad: AnnData, plastic_cells: Dict[str, Dict[str, List[str]]], column: str = 'leiden', latent_space_key: str = 'X_dc') → AnnData[source]

Simulate plasticity through direct cluster switches.

Replaces plastic cells with randomly selected cells from their target clusters, simulating direct phenotypic transitions without intermediate states.

Parameters:

full_simulated_ad (anndata.AnnData) – Complete simulated dataset used for selecting replacement cells.
subset_simulated_ad (anndata.AnnData) – Subset of the dataset containing cells to be analyzed.
plastic_cells (Dict[str, Dict[str, List[str]]]) – Dictionary mapping cluster IDs (as strings) to a dictionary with keys ‘destination’ (target cluster ID as string) and ‘cells’ (list of cell names that will undergo plastic transitions).
column (str, optional) – Column in obs containing cluster annotations, by default ‘leiden’.
latent_space_key (str, optional) – Key in obsm containing latent space coordinates for distance calculation, by default ‘X_dc’.

Returns:

Modified dataset with plastic cells replaced by cells from target clusters. Includes ‘change_in_phenotype’ column with Euclidean distance changes in latent space.

Return type:

anndata.AnnData

Raises:

ValueError – If plastic cells are not found in subset_simulated_ad.

Examples

>>> plastic_cells = {'5': {'destination': '4', 'cells': ['Cell_1', 'Cell_2']}}
>>> result = cluster_switch_plasticity(full_ad, subset_ad, plastic_cells)

Notes

This function directly replaces plastic cells with cells from random target clusters, simulating abrupt phenotypic switches without gradual transitions. All cluster IDs are treated as strings for consistency. The ‘change_in_phenotype’ column contains the Euclidean distance between original and new positions in latent space (0 for non-plastic cells).

plastro.plasticity.plot_leiden_transitions(full_simulated_ad: AnnData, destination_clusters: dict, show_plots: bool = True, save_to: str | None = None) → None[source]

Plots UMAP with arrows indicating transitions between specified leiden clusters.

Parameters:

full_simulated_ad (AnnData) – The AnnData object containing the single-cell data with UMAP coordinates and leiden cluster annotations.
destination_clusters (dict) –
A dictionary where keys are source leiden cluster IDs (str) and values are dictionaries with keys:
- ’destination’: target leiden cluster ID (str)
- ’proportion’: proportion of cells to transition (float between 0 and 1)
show_plots (bool, optional) – Whether to display the plot immediately. Default is True.
save_to (str, optional) – If provided, the path to save the plot image. Default is None (do not save

plastro.plasticity.plot_change_in_phenotype(ad: AnnData, plastic_ad: AnnData, all_plastic_cells: List[str], latent_space_key: str = 'X_dc', show_plots: bool = False, save_to: str | None = None) → Series[source]

Visualize phenotypic changes in plastic cells before and after plasticity simulation.

Creates a three-panel plot showing: 1. Original data with plastic cells highlighted 2. Data after plasticity with plastic cells highlighted 3. Distribution of phenotypic change distances

Parameters:

ad (anndata.AnnData) – Original AnnData object before plasticity simulation.
plastic_ad (anndata.AnnData) – AnnData object after plasticity simulation.
all_plastic_cells (List[str]) – List of cell names that underwent plastic transitions.
latent_space_key (str, optional) – Key in obsm containing latent space coordinates for distance calculation, by default ‘X_dc’.
show_plots (bool, optional) – Whether to display plots interactively, by default False.
save_to (str, optional) – Directory to save the plot, by default None.

Returns:

Series containing phenotypic change distances for each plastic cell.

Return type:

pd.Series

Raises:

KeyError – If required keys are not found in the AnnData objects.
ValueError – If plastic cells are not found in both datasets.

Examples

>>> change_distances = plot_change_in_phenotype(
...     original_ad, plastic_ad, ['Cell_1', 'Cell_2'], show_plots=True
... )
>>> print(f"Mean change: {change_distances.mean():.3f}")

Notes

Requires UMAP coordinates in both AnnData objects
Requires latent space coordinates for distance calculation
Plastic cells must be present in both original and plastic datasets