perturb#

scdiffeq.tools._perturb.perturb(adata: AnnData, model: scdiffeq.scDiffEq, t_sim: Tensor, obs_key: str, genes: List[str], subset_key: str, subset_val: str, gene_id_key: str = 'gene_ids', target_value: float = 10, PCA: PCA | None = None, seed: int = 0, use_key: str = 'X_scaled', replicates: int = 5, N: int = 200, save_simulation: bool = False, *args, **kwargs) → PerturbationExperimentResult[source]#

Perturb a population of cells and simulate the resulting trajectories.

Parameters:

  • adata (AnnData) – The AnnData object containing the data to perturb.

  • model (scdiffeq.scDiffEq) – The scDiffEq model to perturb.

  • t_sim (Tensor) – Simulation time points.

  • obs_key (str) – Key in adata.obs to use for observations.

  • genes (List[str]) – List of genes to perturb.

  • subset_key (str) – Key in adata.obs to subset the data.

  • subset_val (str) – Value in subset_key to subset the data.

  • gene_id_key (str, optional) – Key in adata.var for gene identifiers. Default is “gene_ids”.

  • target_value (float, optional) – Target value for the perturbation. Default is 10.

  • PCA (optional) – PCA object for dimensionality reduction. Default is None.

  • seed (int, optional) – Random seed for reproducibility. Default is 0.

  • use_key (str, optional) – Key in adata.obsm for the data to use. Default is “X_scaled”.

  • replicates (int, optional) – Number of replicates for the perturbation. Default is 5.

  • N (int, optional) – Number of cells to perturb. Default is 200.

  • save_simulation (bool, optional) – Whether to save the simulation results. Default is False.

  • *args – Additional arguments.

  • **kwargs – Additional keyword arguments.

Returns:

The result of the perturbation experiment.

Return type:

PerturbationExperimentResult

Operational classes#

class scdiffeq.tools._fate_perturbation_experiment.FatePerturbationExperiment(seed: int = 0, use_key: str = 'X_scaled', replicates: int = 5, N: int = 200, time_key: str = 't', save_simulation: bool = False, save_path: Path | None = PosixPath('scdiffeq_simulations'), *args, **kwargs)[source]#

Bases: ABCParse

Container class for an expression perturbation experiment, designed to facilitate the analysis of gene expression perturbations and their effects on cell fate and state.

Inherits from ABCParse for abstract base class parsing functionality.

Attributes:

Initializes the FatePerturbationExperiment object.

Parameters:

  • seed (int) – Seed for random number generation to ensure reproducibility.

  • use_key (str) – Key to use for the expression data within the AnnData object.

  • replicates (int) – Number of replicates to consider in the perturbation experiment.

  • N (int) – The number of cells to simulate.

  • time_key (str) – Key to access time-related data within the AnnData object.

  • *args – Additional arguments and keyword arguments for flexibility and future extensions.

  • **kwargs –

    Additional arguments and keyword arguments for flexibility and future extensions.

__init__(seed: int = 0, use_key: str = 'X_scaled', replicates: int = 5, N: int = 200, time_key: str = 't', save_simulation: bool = False, save_path: Path | None = PosixPath('scdiffeq_simulations'), *args, **kwargs) → None[source]#

Initializes the FatePerturbationExperiment object.

Parameters:

  • seed (int) – Seed for random number generation to ensure reproducibility.

  • use_key (str) – Key to use for the expression data within the AnnData object.

  • replicates (int) – Number of replicates to consider in the perturbation experiment.

  • N (int) – The number of cells to simulate.

  • time_key (str) – Key to access time-related data within the AnnData object.

  • *args – Additional arguments and keyword arguments for flexibility and future extensions.

  • **kwargs –

    Additional arguments and keyword arguments for flexibility and future extensions.

property adata_prtb: AnnData#

Lazily loads or generates the AnnData object resulting from perturbation.

Returns:

The AnnData object after applying perturbation.

Return type:

adata_prtb (AnnData)

_subset_final_state(adata_sim) → AnnData[source]#

Extracts the subset of the AnnData object corresponding to the final state of simulation.

Parameters:

adata_sim (AnnData) – The simulated AnnData object.

Returns:

A subset of the AnnData object at its final state.

Return type:

adata_final (AnnData)

property DiffEq: LightningModule#

Accessor for the differential equation model used in the simulation.

Returns:

DiffEq (lightning.LightningModule)

forward() → Tuple[AnnData, AnnData][source]#

Executes the perturbation experiment, comparing control and perturbed conditions.

Simulates, subsets the final simulated state, annotates respective replicates, then annotates cell states/fates using the given kNN.

Returns:

A tuple containing AnnData objects for control and perturbation experiments, respectively.

Return type:

[adata_ctrl, adata_prtb] (Tuple[AnnData, AnnData])

__call__(adata: AnnData, model: scdiffeq.scDiffEq, t_sim: Tensor, obs_key: str, genes: List[str], subset_key: str, subset_val: str, target_value: float = 10, PCA: Optional = None, *args, **kwargs)[source]#

Run perturbation screen.

Parameters:

  • adata (AnnData) – adata obj.

  • model ("scdiffeq.scDiffEq") – scDiffEq model.

  • genes (List[str]) – Genes over which screen should be run.

  • subset_key (str)

  • subset_val (str)

  • target_value (float) – Z-score value at which perturbation should be set. Default: 10

  • (Optional[sklearn.decomposition.PCA] (PCA) – PCA model for transforming expression to model input. Default: None.

Returns:

PerturbationExperimentResult

__parse__(kwargs: Dict, public: List | None = [None], private: List | None = [], ignore: List | None = []) → None#

Made to be called during cls.__init__ of the inherited class. Central function of this autoparsing base class.

Parameters:

  • kwargs (Dict,)

  • public (Optional[List] = [None],)

  • private (Optional[List] = [],)

  • ignore (Optional[List] = [])

Return type:

None

__update__(kwargs: Dict, public: List | None = [None], private: List | None = [], ignore: List | None = []) → None#

To be called after __parse__ has already been called (e.g., during cls.__call__) of the inherited class.

Parameters:

  • kwargs (Dict) – Typically, locals()

  • public (Optional[List] = [None])

  • private (Optional[List] = [])

  • ignore (Optional[List] = [])

  • class. (Second-most central function of this autoparsing base)

Return type:

None

class scdiffeq.tools._fate_perturbation_experiment.PerturbationExperimentResult(ctrl_result: AnnData, prtb_result: AnnData, *args, **kwargs)[source]#

Bases: ABCParse

Container for the results of a perturbation of experiment. Both the control and perturbed arms of the experiment are given as input.

Generally the user interacts with this class, but does not instantiate it. Instead, it is instantiated through the output of FatePerturbationExperiment.

ctrl#
prtb#
stats#

Initialize the PerturbationExperimentResult class.

Parameters:
Returns:

None

__init__(ctrl_result: AnnData, prtb_result: AnnData, *args, **kwargs) → None[source]#

Initialize the PerturbationExperimentResult class.

Parameters:
Returns:

None

property ctrl: DataFrame#
property prtb: DataFrame#
property stats#
__parse__(kwargs: Dict, public: List | None = [None], private: List | None = [], ignore: List | None = []) → None#

Made to be called during cls.__init__ of the inherited class. Central function of this autoparsing base class.

Parameters:

  • kwargs (Dict,)

  • public (Optional[List] = [None],)

  • private (Optional[List] = [],)

  • ignore (Optional[List] = [])

Return type:

None

__update__(kwargs: Dict, public: List | None = [None], private: List | None = [], ignore: List | None = []) → None#

To be called after __parse__ has already been called (e.g., during cls.__call__) of the inherited class.

Parameters:

  • kwargs (Dict) – Typically, locals()

  • public (Optional[List] = [None])

  • private (Optional[List] = [])

  • ignore (Optional[List] = [])

  • class. (Second-most central function of this autoparsing base)

Return type:

None