dynamo.pd.perturbation

dynamo.pd.perturbation(adata, genes, expression=10, perturb_mode='raw', cells=None, zero_perturb_genes_vel=False, pca_key=None, PCs_key=None, pca_mean_key=None, basis='pca', emb_basis='umap', jac_key='jacobian_pca', X_pca=None, delta_Y=None, projection_method='fp', pertubation_method='j_delta_x', J_jv_delta_t=1, delta_t=1, add_delta_Y_key=None, add_transition_key=None, add_velocity_key=None, add_embedding_key=None)[source]

In silico perturbation of single-cells and prediction of cell fate after perturbation.

To simulate genetic perturbation and its downstream effects, we take advantage of the analytical Jacobian from our vector field function. In particular, we first calculate the perturbation velocity vector:

\[\delta Y = J \dot \delta X\]

where the J is the analytical Jacobian, delta X is the perturbation vector (that is,

if overexpress gene i to expression 10 but downexpress gene j to -10 but keep others not changed, we have delta X = [0, 0, 0, delta x_i = 10, 0, 0, .., x_j = -10, 0, 0, 0]). Because Jacobian encodes the instantaneous changes of velocity of any genes after increasing any other gene, J dot delta X will produce the perturbation effect vector after propagating the genetic perturbation (delta_X) through the gene regulatory network. We then use X_pca and delta_Y as a pair (just like M_s and velocity_S) to project the perturbation vector to low dimensional space. The delta_Y can be also used to identify the strongest responders of the genetic perturbation.

Parameters:

  • adata (AnnData) – an Annodata object.

  • genes (Union[str, list]) – The gene or list of genes that will be used to perform in-silico perturbation.

  • expression (Union[float, list]) – The numerical value or list of values that will be used to encode the genetic perturbation. High positive values indicates up-regulation while low negative value repression.

  • perturb_mode (str) – The mode for perturbing the gene expression vector, either raw or z_score.

  • cells (Union[None, ndarray, list]) – The list of the cell indices that we will perform the perturbation.

  • zero_perturb_genes_vel (bool) – Whether to set the peturbed genes’ perturbation velocity vector values to be zero.

  • pca_key (Union[str, ndarray, None]) – The key that corresponds to pca embedding. Can also be the actual embedding matrix.

  • PCs_key (Union[str, ndarray, None]) – The key that corresponds to PC loading embedding. Can also be the actual loading matrix.

  • pca_mean_key (Union[str, ndarray, None]) – The key that corresponds to means values that used for pca projection. Can also be the actual means matrix.

  • basis (str) – The key that corresponds to the basis from which the vector field is reconstructed.

  • jac_key (str) – The key to the jacobian matrix.

  • X_pca (Optional[ndarray]) – The pca embedding matrix.

  • delta_Y (Optional[ndarray]) – The actual perturbation matrix. This argument enables more customized perturbation schemes.

  • projection_method (str) – The approach that will be used to project the high dimensional perturbation effect vector to low dimensional space.

  • pertubation_method (str) – The approach that will be used to calculate the perturbation effect vector after in-silico genetic perturbation. Can only be one of “j_delta_x”, “j_x_prime”, “j_jv”, “f_x_prime”, “f_x_prime_minus_f_x_0”

  • J_jv_delta_t (float) – If pertubation_method is j_jv, this will be used to determine the $delta x = jv delta t_{jv}$

  • delta_t (float) – This will be used to determine the $delta Y = jv delta t$

  • add_delta_Y_key (Optional[str]) – The key that will be used to store the perturbation effect matrix. Both the pca dimension matrix (stored in obsm) or the matrix of the original gene expression space (stored in .layers) will use this key. By default it is None and is set to be method + ‘_perturbation’.

  • add_transition_key (Optional[str]) – The dictionary key that will be used for storing the transition matrix in .obsp.

  • add_velocity_key (Optional[str]) – The dictionary key that will be used for storing the low dimensional velocity projection matrix in .obsm.

  • add_embedding_key (Optional[str]) – The dictionary key that will be used for storing the low dimensional velocity projection matrix in .obsm.

Returns:

Returns an updated AnnData with perturbation effect matrix, projected perturbation vectors

, and a cell transition matrix based on the perturbation vectors.

Return type:

adata