dynamo.vf.sensitivity

dynamo.vf.sensitivity(adata, regulators=None, effectors=None, cell_idx=None, sampling=None, sample_ncells=1000, basis='pca', Qkey='PCs', vector_field_class=None, method='analytical', projection_method='from_jacobian', store_in_adata=True, **kwargs)[source]

Calculate Sensitivity matrix for each cell with the reconstructed vector field.

If the vector field was reconstructed from the reduced PCA space, the Sensitivity matrix will then be inverse transformed back to high dimension. Note that this should also be possible for reduced UMAP space and will be supported shortly. Note that we compute the Sensitivity for the RKHS kernel vector field analytically, which is much more computationally efficient than the numerical method.

Parameters:
  • adata (AnnData) – AnnData object that contains the reconstructed vector field in .uns.

  • regulators (Optional[List]) – The list of genes that will be used as regulators when calculating the cell-wise Jacobian matrix. The Jacobian is the matrix consisting of partial derivatives of the vector field wrt gene expressions. It can be used to evaluate the change in velocities of effectors (see below) as the expressions of regulators increase. The regulators are the denominators of the partial derivatives.

  • effectors (Optional[List]) – The list of genes that will be used as effectors when calculating the cell-wise Jacobian matrix. The effectors are the numerators of the partial derivatives.

  • cell_idx (Optional[List]) – A list of cell index (or boolean flags) for which the jacobian is calculated. If None, all or a subset of sampled cells are used.

  • sampling (Optional[Literal['random', 'velocity', 'trn']]) – {None, ‘random’, ‘velocity’, ‘trn’}, (default: None) See specific information on these methods in .tl.sample. If None, all cells are used.

  • sample_ncells (int) – The number of cells to be sampled. If sampling is None, this parameter is ignored.

  • basis (str) – The embedding data in which the vector field was reconstructed. If None, use the vector field function that was reconstructed directly from the original unreduced gene expression space.

  • Qkey (str) – The key of the PCA loading matrix in .uns.

  • vector_field_class (Optional[BaseVectorField]) – If not None, the jacobian will be computed using this class instead of the vector field stored in adata.

  • method (str) – The method that will be used for calculating Jacobian, either ‘analytical’ or ‘numerical’. ‘analytical’ method uses the analytical expressions for calculating Jacobian while ‘numerical’ method uses numdifftools, a numerical differentiation tool, for computing Jacobian. ‘analytical’ method is much more efficient.

  • projection_method (str) –

    The method that will be used to project back to original gene expression space for calculating gene-wise sensitivity matrix:

    1. ’from_jacobian’: first calculate jacobian matrix and then calculate sensitivity matrix. This method will take the combined regulator + effectors gene set for calculating a square Jacobian matrix required for the sensitivity matrix calculation.

    2. ’direct’: The sensitivity matrix on low dimension will first calculated and then projected back to original gene expression space in a way that is similar to the gene-wise jacobian calculation.

  • cores – Number of cores to calculate Jacobian. If cores is set to be > 1, multiprocessing will be used to parallel the Jacobian calculation.

  • kwargs – Any additional keys that will be passed to elementwise_jacobian_transformation function.

Returns:

AnnData object that is updated with the ‘sensitivity’ key in the .uns. This is a 3-dimensional tensor

with dimensions n_obs x n_regulators x n_effectors.

Return type:

adata