atlas.tl.PalantirExtension

atlas.tl.PalantirExtension#

class atlas.tl.PalantirExtension(mudata)#

Trajectory inference using the Palantir algorithm on MuData objects.

This class provides a high-level interface to run Palantir-based trajectory inference on multimodal single-cell data stored in a MuData object. It operates directly on the input object and stores all intermediate and final results within it.

Parameters:

mudata (MuData) – Annotated multimodal data object containing precomputed neighborhood graphs and embeddings.

Notes

This implementation is adapted from the original Palantir algorithm [SKL+19], with modifications to operate on MuData objects.

Attributes table#

mudata

Underlying MuData object.

Methods table#

compute_diffusion_maps([kernel_key, ...])

Compute diffusion maps from a precomputed kernel.

compute_kernel([knn_key, distance_key, knn, ...])

Compute an adaptive Gaussian kernel from a kNN graph.

compute_multiscale_space([n_eigs, ...])

Compute the multiscale diffusion distance.

run(early_cell[, cluster_key, ...])

Trajectory inference using Palantir ([SKL+19]).

Attributes#

PalantirExtension.mudata#

Underlying MuData object.

Represents multimodal single-cell data containing the weighted nearest neighbor graph.

Methods#

PalantirExtension.compute_diffusion_maps(kernel_key='DM_Kernel', sim_key='DM_Similarity', eigval_key='DM_EigenValues', eigvec_key='DM_EigenVectors', n_components=10, seed=42)#

Compute diffusion maps from a precomputed kernel.

This function computed the diffusion operator from the kernel stored in mudata.obsp. Results are stored back into the MuData object.

Parameters:

  • kernel_key (str (default: 'DM_Kernel')) – Key in mudata.obsp where the kernel matrix is stored.

  • sim_key (str (default: 'DM_Similarity')) – Key in mudata.obsp where the diffusion operator is stored.

  • eigval_key (str (default: 'DM_EigenValues')) – Key in mudata.uns where eigenvalues are stored.

  • eigvec_key (str (default: 'DM_EigenVectors')) – Key in mudata.obsm where the eigenvectors are stores.

  • n_components (int (default: 10)) – Number of diffusion components to compute.

  • seed (int (default: 42)) – Random seed for reproducibility.

Return type:

None

Returns:

Updates the original MuData object:

  • Sparse similarity matrix of shape (n_cells, n_cells) in .obsp[sim_key]

  • Eigenvectors, pandas.DataFrame or numpy.ndarray of shape (n_cells, n_components) in .obsm[eigval_key].

  • Eigenvalues, numpy.ndarray of shape (n_components,) in .uns[eigvec_key].

Raises:

KeyError – if kernel_key is not present in mudata.obsp.

PalantirExtension.compute_kernel(knn_key='wnn', distance_key='wnn_distances', knn=None, alpha=0, kernel_key='DM_Kernel')#

Compute an adaptive Gaussian kernel from a kNN graph.

This function builds a symmetric affinity matrix using an adaptive bandwidth scheme, following the approach described in [SKL+19]. The kernel is constructed from a k-nearest neighbors distance graph stored in mudata.obsp.

Parameters:

  • knn_key (str (default: 'wnn')) – Key in mudata.uns where neighborhood parameters are stored. Must contain ['params']['n_neighbors']. Default is "wnn".

  • distance_key (str (default: 'wnn_distances')) – Key in mudata.obsp where the kNN distance matrix is stored. Default is "wnn_distances".

  • knn (int | None (default: None)) – Number of nearest neighbors used to define the adaptive bandwidth. If None or larger than the number of neighbors stored in mudata.uns[knn_key]['params']['n_neighbors'], it is set to that value.

  • alpha (float (default: 0)) – Normalization parameter for the diffusion operator. If alpha > 0, applies degree normalization to the kernel. Default is 0.

  • kernel_key (str (default: 'DM_Kernel')) – Key in mudata.obsp where the resulting kernel matrix is stored. Default is "DM_Kernel".

Return type:

None

Returns:

Updates the original MuData object.

  • Anisotropic kernel, scipy.sparse.csr_matrix of shape (n_cells, n_cells) in obsp[kernel_key].

Raises:

KeyError – If distance_key is not present in mudata.obsp or knn_key is not present in mudata.uns.

Notes

The kernel is computed using an adaptive bandwidth defined as the distance to the floor(knn / 3)-th nearest neighbor for each cell. The resulting affinity matrix is symmetrized and optionally normalized.

PalantirExtension.compute_multiscale_space(n_eigs=None, eigval_key='DM_EigenValues', eigvec_key='DM_EigenVectors', out_key='DM_EigenVectors_multiscaled')#

Compute the multiscale diffusion distance.

This function rescales diffusion components using their associated eigenvalues to obtain a multiscale representation of the data.

Parameters:

  • n_eigs (int | None (default: None)) – Number of eigenvalues to use. If None, the eigengap heuristic is used to obtain a multiscale representation of the data.

  • eigval_key (str (default: 'DM_EigenValues')) – Key in mudata.uns where diffusion eigenvalues are stored.

  • eigvec_key (str (default: 'DM_EigenVectors')) – Key in mudata.obsm where diffusion eigenvectors are stored.

  • out_key (str (default: 'DM_EigenVectors_multiscaled')) – Key in mudata.obsm where the multiscale representation is stored.

Return type:

None

Returns:

Updates the original MuData object:

  • Multiscaled distances, pandas.DataFrame of shape (n_cells, n_eigs) in obsm[out_key].

Raises:

  • KeyError – If eigval_key is not present in mudata.uns.

  • KeyError – If eigvec_key is not present in mudata.obsm.

PalantirExtension.run(early_cell, cluster_key=None, terminal_states=None, knn=30, num_waypoints=1200, n_jobs=-1, scale_components=True, use_early_cell_as_start=False, max_iterations=25, eigvec_multi_key='DM_EigenVectors_multiscaled', eigvec_key='DM_EigenVectors', pseudotime_key='pseudotime', fate_prob_key='fate_probabilities', waypoints_key='palantir_waypoints', random_state=42)#

Trajectory inference using Palantir ([SKL+19]).

This function:

  • Computes the anisotropic kernel from the weighted nearest neighbor graph connectivites.

  • Derives diffusion components and multiscale space if not available.

  • Runs the original Palantir algorithm.

  • Computed entropy as defined in [LBK+22].

Parameters:

  • early_cell (str) – Barcode identifier of the initial cell for pseudotime inference.

  • cluster_key (str | None (default: None)) – Identifier in obs containing information about cells, optional.

  • terminal_states (Sequence[str] | Mapping[str, Sequence[str]] | Series | None (default: None)) – Terminal states can be defined by the user. When None, terminal states are automatically inferred by the algorithm.

  • knn (int (default: 30)) – Number of nearest neighbors for graph construction in the multiscale space.

  • num_waypoints (int (default: 1200)) – Number of waypoints for trajectory inference. See the original Palantir algorithm for an accurate description of the parameter.

  • n_jobs (int (default: -1)) – Parameter for parallelization.

  • scale_components (bool (default: True)) – When set to True diffusion components are scaled.

  • use_early_cell_as_start (bool (default: False)) – If True ther early cell is used as start.

  • max_iterations (int (default: 25)) – Maximum number of iterations for pseudotime convergence.

  • eigvec_multi_key (str (default: 'DM_EigenVectors_multiscaled')) – Identifier of the multiscale space matrix in .obsm.

  • pseudotime_key (str (default: 'pseudotime')) – Key in .obs where pseudotime results are stored.

  • fate_prob_key (str (default: 'fate_probabilities')) – Key in .obsm where fate probabilities are stored.

  • waypoints_key (str (default: 'palantir_waypoints')) – Key in .uns where waypoints are stored if provided.

  • random_state (int (default: 42)) – Seed for reproducibility.

Return type:

None

Returns:

Updates the MuData object:

  • Pseudotime is added in .obs[pseudotime_key].

  • Fate probabilites, a pandas.DataFrame of shape (n_cells, n_terminal_states) in obsm[fate_prob_key].

  • List of inferred waypoints in .uns[waypoints_key].

  • Shannon entropy and KL-divergence values, respectively, in .obs["shannon_entropy"] and .obs["kl_divergence"].

  • Initial and terminal cell identifiers, respectively, in .uns["initial_states"] and uns["terminal_states"].

Notes

If the multiscale space identified by eigvec_multi_key is not present, the anisotropc kernel, the diffusion components and the multiscaled distances are inferred using the default parameters on the graph stored as “wnn_distances” in .obsp.