dtne package

dtne.embedding module

class dtne.embedding.DTNE(n_components=2, verbose=0, **kwargs)

Bases: object

Parameters:

n_neighbors: int, default=15

Number of nearest neighbors used for manifold learning.

include_self: bool, default=True

Whether to include the point itself in nearest neighbors.

delta: float, default=1

Scaling factor for local sigma computation.

alpha: float, default=1

Parameter for the power of init delay kernel.

epsilon: float, default=1e-2

Threshold parameter for the restart probability.

beta: float, default=0.1

Learning rate for loss optimization.

kernel: str, default=’box’

Kernel function for computing the Markov matrix.

random_state: int, default=0

Seed for random number generator.

solver: str, default=’mds’

Solver method used for dimensionality reduction (‘mds’, ‘sgd’, ‘umap’).

cluster_cells(**params)

Clusters cells into distinct groups based on the precomputed distance matrix (self.dists). This function supports various clustering methods including agglomerative (Hierarchical) clustering, KMedoids, and DBSCAN, allowing flexible clustering of cells depending on the user’s needs.

Parameters:

• cluster_method (str, optional) – The clustering method to use, and ‘agglo’ as default clustering methods. Options include: * “kmedoids” for KMedoids clustering. * “agglo” or “hiera” for Agglomerative Clustering (default: “agglo”). * “dbscan” for Density-Based Spatial Clustering of Applications with Noise (DBSCAN).

• n_clusters (int) – The number of clusters to generate (used for KMedoids and Agglomerative).

• eps (float, optional) – The epsilon parameter for DBSCAN clustering. Defaults to 0.5.

• min_samples (int, optional) – The minimum number of samples in a DBSCAN cluster. Defaults to 5.

Returns:

An array containing the cluster labels for each cell.

Return type:

np.ndarray

compute_embedding(**params)

Computes the diffusion embedding of the data using the learned Markov matrix (R) and constructs the manifold distance matrix (H). This function calls learn_vectors to obtain the transformed Markov matrix (R) and the damping factor vector (cv), normalizes the matrix, and then computes pairwise distances in the diffusion embedding space.

Parameters:

parameters. (Keyword arguments that can be used to override default)

Returns:

The diffusion embedding (manifold distance matrix) of the data.

Return type:

np.ndarray

compute_markov_matrix(**params)

Computes the Markov matrix for the given data.

Parameters:

parameters. (Keyword arguments that can override default)

Returns:

The computed Markov matrix.

fit(**params)

Fits the diffusion embedding and computes the low-dimensional visualization of the data using the specified dimensionality reduction method (e.g., MDS, UMAP, SGD). This function computes pairwise distances using compute_embedding and then applies dimensionality reduction to project the data into a lower-dimensional space.

Parameters:

• n_components (int, optional) – Number of dimensions for the low-dimensional embedding. Defaults to self.n_components.

• random_state (int, optional) – Random seed for the dimensionality reduction algorithm. Defaults to self.random_state.

• solver (str, optional) – The solver method to use for dimensionality reduction, can be: * “mds” (Multidimensional Scaling) * “sgd” (Stochastic Gradient Descent for MDS) * “umap” (Uniform Manifold Approximation and Projection)

• min_dist (float, optional) – Minimum distance for UMAP.

• root_cells (list, optional) – Indices of root cells for cell ordering (used for pseudotime analysis).

Returns:

The object itself, enabling method chaining (e.g., obj.fit().transform()).

Return type:

self

fit_transform(X)

Fits the diffusion embedding and computes the low-dimensional visualization of the data in a single step. This function combines both the fitting and transformation steps into one. It fits the model to the input data and then returns the low-dimensional embedding.

Parameters:

X (np.ndarray) – The data to be embedded. This should be an array where each row represents a sample and each column represents a feature.

Returns:

The low-dimensional embedding of the data after applying the chosen dimensionality reduction method.

Return type:

np.ndarray

learn_vectors(**params)

This method computes the transformed Markov matrix(R) for the given data, and iteratively adjusts the damping factor vector (cv) using a gradient descent method.

Parameters:

• parameters (Keyword arguments to override default)

• as (such)

• alpha – float, the alpha parameter (transition probability)

• epsilon – float, the convergence threshold for cv

• beta – float, the learning rate for the gradient descent

• l1 – int, the initial number of iterations for Markov matrix computation

• l2 – int, the number of iterations for PPR matrix

• X – np.ndarray, the input data matrix

• cv – np.ndarray, initial damping factor vector

Returns:

The learned transformed Markov matrix. cv (np.ndarray): The refined damping factor vector.

Return type:

R (np.ndarray)

order_cells(**params)

Orders cells based on their distances to other cells in the dataset. This is typically used to arrange cells in a sequence according to their manifold distances, which can be useful for trajectory inference or pseudotime analysis.

Parameters:

root_cells (list) – A list of root cell indices that serve as starting points for ordering.

Returns:

A numpy array containing the normalized distances (diff_time) of each cell relative to the root cells.

Return type:

np.ndarray

Raises:

ValueError – If root_cells is not provided in the params.

dtne.utils module

dtne.utils.box(d, local_sigma)

Computes the box kernel (also known as the rectangular kernel).

This kernel assigns a value of 1 if the distance is within a given threshold (local_sigma), and 0 otherwise. It’s commonly used in simple forms of density estimation.

Parameters:

• d (numpy.ndarray or float) – The input distances.

• local_sigma (float) – The threshold value (cutoff distance).

Returns:

The box kernel values. Returns 1 if the distance is within local_sigma, 0 otherwise.

Return type:

numpy.ndarray or float

dtne.utils.box_kernel(data, k_neighbors)

Computes a box kernel matrix for the given data using the k-nearest neighbors. In this kernel, all distances to the k-nearest neighbors are assigned a value of 1, meaning that each data point is equally weighted within its neighborhood. And then normalize the kernel matrix.

Parameters:

• data (np.ndarray) – The input data matrix with shape (n_samples, n_features).

• k_neighbors (int) – The number of nearest neighbors to consider for each data point.

Returns:

• kernel_tilde (scipy.sparse.csr_matrix):

  The normalized box kernel matrix, where connections between neighbors are weighted by degree normalization.

• knn_indices (np.ndarray):

  The indices of the k nearest neighbors for each data point.

Return type:

tuple

dtne.utils.box_kernel2(data, k_neighbors, delta=1)

Compute a kernel matrix using the box kernel and handle disconnected components using minimum spanning trees. This method builds a kernel matrix using a box function to define the influence of neighbors, and if disconnected components exist, it uses a minimum spanning tree (MST) to connect them.

Parameters:

• data – numpy.ndarray, shape (n_samples, n_features) The input data points.

• k_neighbors – int The number of nearest neighbors to consider for each data point.

• delta – float, optional (default=1) A scaling factor for local sigma computation that controls the bandwidth of the box kernel.

Returns:

• kernel_tilde (scipy.sparse.csr_matrix):

  The normalized box kernel matrix.

• knn_indices (np.ndarray):

  The indices of the k nearest neighbors for each data point.

Return type:

tuple

dtne.utils.calc_l(lamb)

This function calculates the value of ‘l’ based on the entropy and its derivatives of a power series of lambda.

Parameters:

lamb – A float value representing the lambda parameter.

Returns:

An integer value representing the calculated ‘l’.

dtne.utils.classic(D, n_components=2, random_state=None)

Fast CMDS using random SVD, the codes of this function come from the PHATE algorithm. Starting configuration of the embedding to initialize the SMACOF algorithm.

Parameters:

• D (array-like, shape=[n_samples, n_samples]) – pairwise distances

• n_components (int, optional (default: 2)) – number of dimensions in which to embed D

• random_state (int, RandomState or None, optional (default: None)) – numpy random state

Returns:

Y

Return type:

array-like, embedded data [n_sample, ndim]

dtne.utils.compute_infty_R(Phi, lamb, Psi, cv, l)

Compute the rank matrix with Eigen_decomposition when the number of iterations tends to infinity when the number of iterations tends to infinity.

Parameters:

• Phi – array-like, shape (n_samples, n_samples) The eigenvectors of the kernel matrix (from the eigen_kernel function).

• lamb – array-like, shape (n_samples) The eigenvalues of the kernel matrix (from the eigen_kernel function).

• Psi – array-like, shape (n_samples, n_samples) The pseudoinverse of the eigenvector matrix.

• cv – array-like, shape (n_samples) A vector representing the coefficient values for each sample.

• l – int The power parameter for lambda in the power series.

Returns:

R: array-like, shape (n_samples, n_samples)

The computed rank matrix at the limit where iterations tend to infinity.

dif_R: array-like, shape (n_samples, n_samples)

The differential of the rank matrix.

Return type:

A tuple containing two elements

dtne.utils.compute_landmark_operator(K, labels, random_state=None)

This function computes the landmark operator based on a kernel matrix, number of landmarks, and sample labels.

Parameters:

• K – A sparse matrix representing the kernel matrix.

• labels – A 1D numpy array containing integer labels for each sample.

• random_state – An integer (optional) to control the randomness for landmark selection (default: None).

Returns:

pmm: A 2D numpy array representing the landmark operator. pnm: A 2D numpy array representing the intermediate matrix used in the calculation.

Return type:

A tuple containing two elements

dtne.utils.eigen_kernel(kernel)

This function computes the eigenvalues, eigenvectors, and pseudoinverse of a kernel matrix.

Parameters:

kernel – A 2D numpy array representing the kernel matrix.

Returns:

• Phi: A 2D numpy array containing the eigenvectors of the kernel matrix (one eigenvector per column).

• lamb: A 1D numpy array containing the eigenvalues of the kernel matrix (absolute values).

• Psi: A 2D numpy array containing the pseudoinverse of the eigenvector matrix (Phi).

Return type:

A tuple containing three elements

dtne.utils.eigen_kernel2(matrix)

This function computes the eigenvalues, eigenvectors, and pseudoinverse of a kernel matrix.

Parameters:

matrix – A 2D numpy array representing the kernel matrix.

Returns:

lamb: A 1D numpy array containing the eigenvalues of the kernel matrix. Phi: A 2D numpy array containing the eigenvectors of the kernel matrix (one eigenvector per column). Psi: A 2D numpy array containing the pseudoinverse of the eigenvector matrix (Phi).

Return type:

A tuple containing three elements

dtne.utils.epanechnikov(d, h=1)

Computes the Epanechnikov kernel, a popular kernel function used for density estimation.

Parameters:

• d (np.ndarray or float) – An array of distances or a single distance value.

• h (float) – The bandwidth parameter, controlling the kernel’s width. Defaults to 1.

Returns:

The kernel values where distances are within the bandwidth, zero for distances outside the bandwidth.

Return type:

np.ndarray or float

dtne.utils.gauss(d, local_sigma, alpha=1)

Computes a Gaussian kernel.

Parameters:

• d (float or np.ndarray) – The distance(s) for which to compute the Gaussian kernel.

• local_sigma (float) – The scale (sigma) parameter for the Gaussian function.

• alpha (float, optional) – Controls the sharpness of the kernel. Defaults to 1.

Returns:

The Gaussian kernel values corresponding to the input distances.

Return type:

float or np.ndarray

dtne.utils.gauss_kernel(data, k_neighbors, delta=1, alpha=1)

Compute a Gaussian kernel matrix.

Parameters:

• data – array-like, shape (n_samples, n_features) The input data points.

• k_neighbors – int The number of nearest neighbors to consider for each data point.

• delta – float, optional (default=1) A scaling factor for local sigma computation that controls the bandwidth of the Gaussian kernel.

• alpha – float, optional (default=1) A parameter controlling the decay of the Gaussian function.

Returns:

• kernel_tilde (scipy.sparse.csr_matrix): The normalized Gaussian kernel matrix.

• knn_indices (np.ndarray): The indices of the k nearest neighbors for each data point.

Return type:

tuple

dtne.utils.mix_decay(d, local_sigma, alpha=1)

The function returns 1 for distances less than or equal to local_sigma, and applies an exponential Gaussian decay for larger distances. This can be useful when modeling a smooth decay of influence with distance.

Parameters:

• d (numpy.ndarray or float) – The input distances.

• local_sigma (float) – The cutoff or threshold distance for switching between constant and decayed values.

• alpha (float, optional) – The decay rate. Defaults to 1.

Returns:

The mixed decayed values, where distances less than local_sigma will return 1, and larger distances follow a decayed Gaussian function.

Return type:

numpy.ndarray or float

dtne.utils.mix_kernel(data, k_neighbors, delta=1, alpha=1)

Compute a mixed kernel matrix using a combination of box and Gaussian decay kernels.

Parameters:

• data (array-like, shape (n_samples, n_features)) – The input data points.

• k_neighbors (int) – The number of nearest neighbors to consider for each point.

• delta (float, optional, default=1) – Scaling factor for computing the local sigma (spread parameter) for the decay.

• alpha (float, optional, default=1) – Parameter for the Gaussian decay function that controls the rate of decay.

Returns:

• kernel_tilde (scipy.sparse.csr_matrix):

  The normalized, symmetric kernel matrix based on the nearest neighbors.

• knn_indices (np.ndarray):

  Indices of the k nearest neighbors for each point.

Return type:

tuple

dtne.utils.phate_kernel(data, knn=5, decay=40.0, anisotropy=0, n_pca=None, **kwargs)

This function creates a kernel matrix using the PHATE method with the help of the graph-tool library.

Parameters:

• data – A numpy array (n_samples, n_features) representing the data to be used for kernel construction.

• knn – The number of nearest neighbors to consider when constructing the graph (default: 5).

• decay – The decay parameter that controls the influence of neighboring points (default: 40.0). Higher decay values lead to smoother kernels by controlling the decay of the kernel weights.

• anisotropy – The anisotropy parameter that controls the influence of points in different directions (default: 0). Non-zero values introduce direction-based weighting into the kernel.

• n_pca – The number of principal components to use for dimensionality reduction before building the graph (default: None, meaning it uses all components).

• **kwargs – Additional keyword arguments passed to the graph-tool.Graph constructor (optional).

Returns:

A kernel matrix represented as a sparse matrix from graph-tool.

Return type:

K

dtne.utils.scanpy_kernel(data, knn=5, method='umap')

This function creates a kernel matrix using scanpy and graph-tool libraries.

Parameters:

• data – A numpy array (n_samples, n_features) representing the data to be used for kernel construction.

• knn – The number of nearest neighbors to consider when constructing the adjacency matrix (default: 5).

• method – The dimensionality reduction method to use for neighbor search (default: ‘umap’). Other possible values could be ‘gauss’ or ‘pca’, depending on Scanpy’s implementation.

Returns:

A kernel matrix represented as a sparse matrix from Graph-tools.