Lineage Simulation Module

The lineage simulation module provides functions for simulating CRISPR-based lineage tracing data and constructing phylogenetic trees from single-cell data.

Core Functions

`simulate_lineage_tracing`(sim_ad, terminal_ad)	Simulate lineage tracing using Cassiopeia on single-cell data.
`construct_tree`(sim_ad, terminal_ad[, ...])	Construct phylogenetic tree from latent space coordinates.
`introduce_crispr_mutations`(tree[, ...])	Simulate CRISPR mutations on a phylogenetic tree.

Utility Functions

Function Details

Lineage simulation module for CRISPR-based lineage tracing.

This module provides functions for simulating lineage tracing data, constructing phylogenetic trees from single-cell data, and introducing CRISPR-based mutations to create realistic lineage relationships for plasticity analysis.

plastro.lineage_simulation.simulate_lineage_tracing(sim_ad: anndata.AnnData, terminal_ad: anndata.AnnData, latent_space_key: str = 'X_dc', number_of_cassettes: int = 100, save_to: str | None = None) → cassiopeia.data.CassiopeiaTree[source]

Simulate lineage tracing using Cassiopeia on single-cell data.

Builds a phylogenetic tree from latent space coordinates and simulates CRISPR-based lineage tracing to generate character matrices.

Parameters:

sim_ad (anndata.AnnData) – Complete simulated single-cell dataset.
terminal_ad (anndata.AnnData) – Subset containing only terminal/observed cells.
latent_space_key (str, optional) – Key in sim_ad.obsm containing latent space coordinates, by default ‘X_dc’.
number_of_cassettes (int, optional) – Number of mutation sites, by default 100 so we can accurately resolve lineage relationships.
save_to (str, optional) – Directory to save tree and results, by default None.

Returns:

Cassiopeia tree object with character matrix and phylogenetic structure.

Return type:

cassiopeia.data.CassiopeiaTree

Examples

>>> import plastro
>>> # Assume sim_ad contains full simulated data and terminal_ad contains observed cells
>>> cass_tree = plastro.simulate_lineage_tracing(sim_ad, terminal_ad, 'X_dc')
>>> character_matrix = cass_tree.character_matrix
>>> print(f"Character matrix shape: {character_matrix.shape}")

Notes

This function combines tree construction from phenotypic similarity with CRISPR mutation simulation to create realistic lineage tracing data that can be used for plasticity analysis.

plastro.lineage_simulation.construct_tree(sim_ad: anndata.AnnData, terminal_ad: anndata.AnnData, latent_space_key: str = 'X_dc', save_to: str | None = None) → TreeNode[source]

Construct phylogenetic tree from latent space coordinates.

Uses neighbor-joining algorithm on distances computed from latent space to build a phylogenetic tree representing cellular relationships.

Parameters:

sim_ad (anndata.AnnData) – Complete simulated dataset with latent space coordinates.
terminal_ad (anndata.AnnData) – Terminal/observed cells to include in the tree.
latent_space_key (str, optional) – Key for latent space coordinates in sim_ad.obsm, by default ‘X_dc’.
save_to (str, optional) – Directory to save the tree file, by default None.

Returns:

Phylogenetic tree of the cells.

Return type:

ete3.Tree

Raises:

KeyError – If latent_space_key is not found in sim_ad.obsm.
ValueError – If no suitable root cell is found.

Examples

>>> tree = construct_tree(sim_ad, terminal_ad, latent_space_key='X_dc')
>>> print(f"Tree has {len(tree.get_leaves())} leaves")
>>> tree.show()  # Display tree visualization

plastro.lineage_simulation.introduce_crispr_mutations(tree: TreeNode, number_of_cassettes: int = 100) → cassiopeia.data.CassiopeiaTree[source]

Simulate CRISPR mutations on a phylogenetic tree.

Uses Cassiopeia’s mutation simulation to add realistic CRISPR-based lineage tracing mutations to the tree structure.

Parameters:

tree (ete3.Tree) – Phylogenetic tree to add mutations to.
number_of_cassettes (int, optional) – Number of mutation sites, by default 100 so we can accurately resolve lineage relationships.

Returns:

Tree with simulated character matrix containing mutation data.

Return type:

cassiopeia.data.CassiopeiaTree

Examples

>>> from ete3 import Tree
>>> tree = Tree("((A,B),C);")
>>> cass_tree = introduce_crispr_mutations(tree)
>>> print(cass_tree.character_matrix.shape)

Notes

This function requires the Cassiopeia package for mutation simulation. The resulting character matrix will have cells as rows and mutation sites as columns, with values representing different mutation states.