dynamo.vf.SvcVectorField

class dynamo.vf.SvcVectorField(X=None, V=None, Grid=None, normalize=None, *args, **kwargs)

Methods table

assign_fixed_points([domain, cores])	assign each cell to the associated fixed points
compute_acceleration([X, method])	Calculate acceleration for many samples via
compute_curl([X, method, dim1, dim2, dim3])	Curl computation for many samples for 2/3 D systems.
compute_curvature([X, method, formula])	Calculate curvature for many samples via :rtype: ndarray
compute_divergence([X, method])	Takes the trace of the jacobian matrix to calculate the divergence.
compute_sensitivity([X, method])	Calculate sensitivity for many samples via :rtype: ndarray
compute_torsion([X, method])	Calculate torsion for many samples via :rtype: ndarray
construct_graph([X])
evaluate(CorrectIndex, VFCIndex, siz)	Evaluate the precision, recall, corrRate of the sparseVFC algorithm.
find_fixed_points([n_x0, X0, domain, ...])	Search for fixed points of the vector field function.
from_adata(adata[, basis, vf_key])
get_Hessian([method])	Get the Hessian of the vector field function.
get_Jacobian([method, input_vector_convention])	Get the Jacobian of the vector field function.
get_Laplacian([method])	Get the Laplacian of the vector field.
get_V([idx])
get_X([idx])
get_data()
get_fixed_points(**kwargs)	Get fixed points of the vector field function.
integrate(init_states[, dims, scale, t_end, ...])	Integrate along a path through the vector field field function to predict the state after a certain amount of time t has elapsed.
plot_energy([figsize, fig])
train(**kwargs)	Learn an function of vector field from sparse single cell samples in the entire space robustly.

Methods

SvcVectorField.assign_fixed_points(domain=None, cores=1, **kwargs)

assign each cell to the associated fixed points

Parameters:

• domain (Optional[ndarray] (default: None)) – Array of shape (n_dim, 2), which stores the domain for each dimension

• cores (int (default: 1)) – Defaults to 1.

Return type:

Tuple[ndarray, ndarray, ndarray]

Returns:

Tuple of fixed points, type assignments, and assignment IDs

SvcVectorField.compute_acceleration(X=None, method='analytical', **kwargs)

Calculate acceleration for many samples via

\[\]

a = || J cdot v ||.

Parameters:

• X (Optional[ndarray] (default: None)) – Current state. Defaults to None, initialized from self.data

• method (str (default: 'analytical')) – Method for calculating the Jacobian, one of numerical, analytical, parallel

Return type:

ndarray

Returns:

np.ndarray storing the vector norm of acceleration (across all genes) for each cell

SvcVectorField.compute_curl(X=None, method='analytical', dim1=0, dim2=1, dim3=2, **kwargs)

Curl computation for many samples for 2/3 D systems.

Parameters:

• X (Optional[ndarray] (default: None)) – Current state. Defaults to None, initialized from self.data

• method (str (default: 'analytical')) – Method for calculating the Jacobian, one of numerical, analytical, parallel

• dim1 (int (default: 0)) – index of first dimension

• dim2 (int (default: 1)) – index of second dimension

• dim3 (int (default: 2)) – index of third dimension

Return type:

ndarray

Returns:

np.ndarray storing curl

SvcVectorField.compute_curvature(X=None, method='analytical', formula=2, **kwargs)

Calculate curvature for many samples via :rtype: ndarray

Formula 1: .. math:: kappa =

rac{||mathbf{v} imes mathbf{a}||}{||mathbf{V}||^3}

Formula 2: .. math:: kappa =

rac{||mathbf{Jv} (mathbf{v} cdot mathbf{v}) - ||mathbf{v} (mathbf{v} cdot mathbf{Jv})}{||mathbf{V}||^4}

Args:

X: Current state. Defaults to None, initialized from self.data method: Method for calculating the Jacobian, one of numerical, analytical, parallel formula: Choose between formulas 1 and 2 to compute the curvature. Defaults to 2.

Returns:

np.ndarray storing the vector norm of curvature (across all genes) for each cell

SvcVectorField.compute_divergence(X=None, method='analytical', **kwargs)

Takes the trace of the jacobian matrix to calculate the divergence.

Parameters:

• X (Optional[ndarray] (default: None)) – Current state. Defaults to None, initialized from self.data

• method (str (default: 'analytical')) – Method for calculating the Jacobian, one of numerical, analytical, parallel

Return type:

ndarray

Returns:

The divergence of the Jacobian matrix.

SvcVectorField.compute_sensitivity(X=None, method='analytical', **kwargs)

Calculate sensitivity for many samples via :rtype: ndarray

\[\]

S = (I - J)^{-1} D(

rac{1}{{I-J}^{-1}})

Args:

X: Current state. Defaults to None, initialized from self.data method: Method for calculating the Jacobian, one of numerical, analytical, parallel Defaults to “analytical”.

Returns:

np.ndarray storing sensitivity matrix

SvcVectorField.compute_torsion(X=None, method='analytical', **kwargs)

Calculate torsion for many samples via :rtype: ndarray

\[au =\]

rac{(mathbf{v} imes mathbf{a}) cdot (mathbf{J} cdot mathbf{a})}{||mathbf{V} imes mathbf{a}||^2}

Args:

X: Current state. Defaults to None, initialized from self.data method: Method for calculating the Jacobian, one of numerical, analytical, parallel

Returns:

np.ndarray storing torsion for each sample

SvcVectorField.construct_graph(X=None, **kwargs)

Return type:

Tuple[ndarray, Union[NNDescent, NearestNeighbors]]

SvcVectorField.evaluate(CorrectIndex, VFCIndex, siz)

Evaluate the precision, recall, corrRate of the sparseVFC algorithm.

Parameters:

• CorrectIndex (List) – Ground truth indexes of the correct vector field samples.

• VFCIndex (List) – Indexes of the correct vector field samples learned by VFC.

• siz (int) – Number of initial matches.

Return type:

Tuple[float, float, float]

Returns:

A tuple of precision, recall, corrRate, where Precision, recall, corrRate are Precision and recall of VFC, percentage of initial correct matches, respectively.

See also:: sparseVFC().

SvcVectorField.find_fixed_points(n_x0=100, X0=None, domain=None, sampling_method='random', **kwargs)

Search for fixed points of the vector field function.

Parameters:

• n_x0 (int (default: 100)) – Number of sampling points

• X0 (Optional[ndarray] (default: None)) – An array of shape (n_samples, n_dim)

• domain (Optional[ndarray] (default: None)) – Domain in which to search for fixed points

• sampling_method (Literal['random', 'velocity', 'trn', 'kmeans'] (default: 'random')) – Method for sampling initial points. Can be one of random, velocity, trn, or kmeans.

Return type:

None

SvcVectorField.from_adata(adata, basis='', vf_key='VecFld')

SvcVectorField.get_Hessian(method='analytical', **kwargs)

Get the Hessian of the vector field function. If method is ‘analytical’: The analytical Hessian will be returned and it always take row vectors as input no matter what input_vector_convention is.

Return type:

ndarray

No matter the method and input vector convention, the returned Hessian is of the following format:

df^2/dx_1^2 df_1^2/(dx_1 dx_2) df_1^2/(dx_1 dx_3) … df^2/(dx_2 dx_1) df^2/dx_2^2 df^2/(dx_2 dx_3) … df^2/(dx_3 dx_1) df^2/(dx_3 dx_2) df^2/dx_3^2 … … … … …

SvcVectorField.get_Jacobian(method='analytical', input_vector_convention='row', **kwargs)

Get the Jacobian of the vector field function. If method is ‘analytical’: The analytical Jacobian will be returned and it always take row vectors as input no matter what input_vector_convention is.

If method is ‘numerical’: If the input_vector_convention is ‘row’, it means that fjac takes row vectors as input, otherwise the input should be an array of column vectors. Note that the returned Jacobian would behave exactly the same if the input is an 1d array.

The column vector convention is slightly faster than the row vector convention. So the matrix of row vector convention is converted into column vector convention under the hood.

Return type:

ndarray

No matter the method and input vector convention, the returned Jacobian is of the following format:

df_1/dx_1 df_1/dx_2 df_1/dx_3 … df_2/dx_1 df_2/dx_2 df_2/dx_3 … df_3/dx_1 df_3/dx_2 df_3/dx_3 … … … … …

SvcVectorField.get_Laplacian(method='analytical', **kwargs)

Get the Laplacian of the vector field. Laplacian is defined as the sum of the diagonal of the Hessian matrix. Because Hessian is originally defined for scalar function and here we extend it to vector functions. We will calculate the summation of the diagonal of each output (target) dimension.

A Laplacian filter is an edge detector used to compute the second derivatives of an image, measuring the rate at which the first derivatives change (so it is the derivative of the Jacobian). This determines if a change in adjacent pixel values is from an edge or continuous progression.

Return type:

ndarray

SvcVectorField.get_V(idx=None)

Return type:

ndarray

SvcVectorField.get_X(idx=None)

Return type:

ndarray

SvcVectorField.get_data()

Return type:

Tuple[ndarray, ndarray]

SvcVectorField.get_fixed_points(**kwargs)

Get fixed points of the vector field function.

Return type:

Tuple[ndarray, ndarray]

Returns:

Tuple storing the coordinates of the fixed points and the types of the fixed points.

Types of the fixed points: -1 – stable,

0 – saddle, 1 – unstable

SvcVectorField.integrate(init_states, dims=None, scale=1, t_end=None, step_size=None, args=(), integration_direction='forward', interpolation_num=250, average=True, sampling='arc_length', verbose=False, disable=False)

Integrate along a path through the vector field field function to predict the state after a certain amount of time t has elapsed.

Parameters:

• init_states (ndarray) – Initial state provided to scipy’s ivp_solver with shape (num_cells, num_dim)

• dims (Union[int, list, ndarray, None] (default: None)) – Dimensions of state to be used

• scale (default: 1) – Scale the vector field function by this factor. Defaults to 1.

• t_end (default: None) – Integrates up till when t=t_end, Defaults to None.

• step_size (default: None) – Defaults to None.

• args (default: ()) – Additional arguments provided to scipy’s ivp_solver Defaults to ().

• integration_direction (default: 'forward') – Defaults to “forward”.

• interpolation_num (default: 250) – Defaults to 250.

• average (default: True) – Defaults to True.

• sampling (default: 'arc_length') – Defaults to “arc_length”.

• verbose (default: False) – Defaults to False.

• disable (default: False) – Defaults to False.

Return type:

Tuple[ndarray, ndarray]

Returns:

Tuple storing times and predictions

SvcVectorField.plot_energy(figsize=None, fig=None)

SvcVectorField.train(**kwargs)

Learn an function of vector field from sparse single cell samples in the entire space robustly. Reference: Regularized vector field learning with sparse approximation for mismatch removal, Ma, Jiayi, etc. al, Pattern Recognition

Parameters:

normalize – Logic flag to determine whether to normalize the data to have zero means and unit covariance. This is often required for raw dataset (for example, raw UMI counts and RNA velocity values in high dimension). But it is normally not required for low dimensional embeddings by PCA or other non-linear dimension reduction methods.

Return type:

VecFldDict

Returns:

A dictionary which contains X, Y, beta, V, C, P, VFCIndex. Where V = f(X), P is the posterior probability and VFCIndex is the indexes of inliers which found by VFC.