plastro.plasticity.perform_random_walk

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