Package 'manifoldsR'

Description

Get the cluster membership at the best persistence score

Usage

best_membership(x)

## S3 method for class 'Evoc'
best_membership(x)

Arguments

Value

A named list with elements labels (integer vector of cluster assignments, -1 for noise), membership (numeric vector of strengths), layer (which layer index was selected), and persistence (the score).

Description

Calculates the adjusted Rand index between two sets of cluster assignments.

Usage

calc_ari(members_a, members_b)

Arguments

Value

Adjusted Rand index

Description

Calculate the cluster inertia

Usage

calc_inertia(x, data)

## S3 method for class 'KMeansCluster'
calc_inertia(x, data)

Arguments

Value

The cluster inertia

Description

If the membership has only one group, the function will return NaN for mean_silhouette and silhouette_scores.

Usage

calc_silhouette_score(data, membership)

Arguments

Value

A list with the following items:

• mean_silhouette - The average Silhouette scores across all the data points.

• silhouette_scores - The individual Silhouette scores of all the data points.

Description

Performs densMAP dimensionality reduction on the input data. densMAP is UMAP with an added density-preserving term, so a tight cluster stays tight and a diffuse one stays diffuse. Plain UMAP gives you no such guarantee: relative sizes in the embedding mean nothing. This function provides a user-friendly interface with input validation before calling the Rust implementation.

Usage

densmap(
  data,
  knn = NULL,
  n_dim = 2L,
  k = 15L,
  min_dist = 0.5,
  spread = 1,
  knn_method = c("kmknn", "balltree", "hnsw", "annoy", "nndescent", "exhaustive", "ivf"),
  nn_params = params_nn(),
  umap_params = params_umap(),
  dens_params = params_densmap(),
  seed = 42L,
  use_high_precision = NULL,
  .verbose = TRUE
)

Arguments

Details

Setting lambda to 0 in params_densmap() recovers plain umap() exactly. The density term is only active over the final frac of the epochs, which is why it costs comparatively little.

Value

A numerical matrix with dimensions samples x n_dim containing the densMAP embedding.

References

Narayan, Berger & Cho, Nat. Biotechnol., 2021

Description

Performs den-SNE dimensionality reduction on the input data. den-SNE is t-SNE with an added density-preserving term, so a tight cluster stays tight and a diffuse one stays diffuse. Plain t-SNE gives you no such guarantee: relative sizes in the embedding mean nothing. This function provides a user-friendly interface with input validation before calling the Rust implementation.

Usage

densne(
  data,
  knn = NULL,
  n_dim = 2L,
  perplexity = 20,
  approx_type = c("bh", "bh_qd", "fft", "fft_3k"),
  knn_method = c("kmknn", "balltree", "hnsw", "annoy", "nndescent", "exhaustive", "ivf"),
  nn_params = params_nn(),
  tsne_params = params_tsne(),
  dens_params = params_densne(),
  seed = 42L,
  use_high_precision = NULL,
  .verbose = TRUE
)

Arguments

Details

The number of neighbours will be 3 * perplexity, as this is a usual default in tSNE. Setting lambda to 0 in params_densne() recovers plain tsne() exactly. The default lambda is twenty times smaller than the densMAP one, matching the reference implementations.

Value

A numerical matrix with dimensions samples x n_dim containing the den-SNE embedding.

References

Narayan, Berger & Cho, Nat. Biotechnol., 2021

Description

Performs diffusion maps dimensionality reduction on the input data. This function provides a user-friendly interface with input validation before calling the Rust implementation.

Usage

diffusion_maps(
  data,
  knn = NULL,
  n_dim = 2L,
  k = 5L,
  knn_method = c("kmknn", "balltree", "hnsw", "annoy", "nndescent", "exhaustive", "ivf"),
  nn_params = params_nn(),
  dm_params = params_diffusion_maps(),
  seed = 42L,
  use_high_precision = NULL,
  .verbose = TRUE
)

Arguments

Value

A numerical matrix with dimensions samples x n_dim containing the diffusion maps embedding.

Description

Performs EVoC (Embedding Vector Oriented Clustering) on the input data. Combines a UMAP-like node embedding with HDBSCAN-style density-based clustering and multi-layer persistence analysis.

Usage

evoc(
  data,
  knn = NULL,
  n_neighbours = 15L,
  knn_method = c("kmknn", "hnsw", "annoy", "nndescent", "balltree", "ivf", "exhaustive"),
  nn_params = params_nn(),
  evoc_params = params_evoc(),
  return_knn = FALSE,
  seed = 42L,
  use_high_precision = NULL,
  .verbose = TRUE
)

Arguments

Value

An Evoc S3 object (see print.Evoc, best_membership, get_layer).

Description

Lays out the kNN graph of the data with ForceAtlas2, the way scanpy's draw_graph does: the kNN graph is turned into the UMAP fuzzy union graph and every edge pulls, every node pair pushes (1/d, with masses 1 + degree), plus gravity towards the origin. Repulsion runs on a Barnes-Hut tree. Already have a graph? Use forceatlas2_from_graph().

Usage

forceatlas2(
  data,
  knn = NULL,
  k = 15L,
  knn_method = c("kmknn", "balltree", "hnsw", "annoy", "nndescent", "exhaustive", "ivf"),
  nn_params = params_nn(),
  fa2_params = params_fa2(),
  seed = 42L,
  use_high_precision = NULL,
  .verbose = TRUE
)

Arguments

Value

A numerical matrix with dimensions samples x 2 containing the ForceAtlas2 layout.

References

Jacomy, et al., PLoS ONE, 2014

Description

Lays out any undirected graph with ForceAtlas2, for example an SNN graph or a graph from another package. Edge weights come from the weight edge attribute; without one, every edge weighs 1. Self-loops are dropped. Only the optimisation parameters in fa2_params are used; the graph and initialisation ones do not apply here.

Usage

forceatlas2_from_graph(
  graph,
  init = NULL,
  fa2_params = params_fa2(),
  seed = 42L,
  use_high_precision = NULL,
  .verbose = TRUE
)

Arguments

Value

A numerical matrix with dimensions ⁠vcount(graph) x 2⁠ containing the ForceAtlas2 layout, rows in vertex order.

References

Jacomy, et al., PLoS ONE, 2014

Description

This function generates a kNN graph based on a given numeric matrix. Seven different algorithms are implemented with different speed and accuracy trade-offs:

• "hnsw" - Hierarchical Navigable Small Worlds vector search with slower index generation (which ammortises on larger data sets) and high precision.

• "annoy" - Approximate Nearest Neighbours Oh Yeah algorithm, faster to index but querying on large data sets can be slow.

• "nndescent" - Rust-based implementation of the PyNNDescent algorithm, a good all-rounder that performs well on very large data sets.

• "balltree" - Ball tree structure for exact search with a configurable budget.

• "ivf" - Inverted file index that leverages k-means clustering and probing a few of the clusters.

• "exhaustive" - Exact nearest neighbour search.

• "kmknn" - Fast exact nearest neighbour search using triangle inequality

Usage

generate_knn_graph(
  data,
  k,
  knn_method = c("kmknn", "hnsw", "annoy", "nndescent", "balltree", "ivf", "exhaustive"),
  nn_params = params_nn(),
  seed = 42L,
  .verbose = TRUE
)

Arguments

Value

A nearest neighbours class object with 1-indexed neighbour indices and distances. Distances are on the scale of the metric they are named after, so dist_metric = "euclidean" returns Euclidean distance, not the squared Euclidean the backends sort on internally.

Description

Get cluster centroids

Usage

get_centroids(x)

## S3 method for class 'KMeansCluster'
get_centroids(x)

Arguments

Value

Numeric matrix of shape k x features.

Description

Get the distances as a flat vector

Usage

get_dist_flat(x)

## S3 method for class 'NearestNeighbours'
get_dist_flat(x)

Arguments

Value

The distances in a flat format like ⁠c(dist1.1, dist1.2, ... , dist2.1, dist2.2, ... dist3.1, dist3.2)⁠

Description

Get the indices as a matrix

Usage

get_dist_mat(x)

## S3 method for class 'NearestNeighbours'
get_dist_mat(x)

Arguments

Value

The indices in samples x neighbours format

Description

Get the indices as a flat vector

Usage

get_idx_flat(x)

## S3 method for class 'NearestNeighbours'
get_idx_flat(x)

Arguments

Value

The indices in a flat format like ⁠c(idx1.1, idx1.2, ... , idx.2.1, idx2.2, ... idx3.1, idx3.2)⁠

Description

Get the indices as a matrix

Usage

get_idx_mat(x)

## S3 method for class 'NearestNeighbours'
get_idx_mat(x)

Arguments

Value

The indices in samples x neighbours format

Description

Get a specific EVoC layer

Usage

get_layer(x, i)

## S3 method for class 'Evoc'
get_layer(x, i)

Arguments

Value

A named list with labels, membership, and persistence for the requested layer.

Description

Get the kNN graph from an Evoc object

Usage

get_nearest_neighbours(x)

## S3 method for class 'Evoc'
get_nearest_neighbours(x)

Arguments

Value

A NearestNeighbours object, or NULL if the kNN was not stored.

Description

Performs k-means clustering on the input data. Supports both full Lloyd's iterations (with SIMD/GEMM acceleration) and mini-batch k-means for large data sets.

Usage

kmeans_cluster(
  data,
  k,
  method = c("full", "minibatch"),
  kmeans_params = params_kmeans(),
  seed = 42L,
  .verbose = TRUE
)

Arguments

Value

A named list with:

centroids

Numeric matrix of shape k x features containing the final cluster centroids.

assignments

Integer vector of length samples with cluster assignments (1-indexed).

Description

A unified wrapper function for generating various types of synthetic data to test manifold learning techniques and demonstrate differences.

Usage

manifold_synthetic_data(
  type = c("swiss_role", "biased_swiss_role", "clusters", "trajectory", "hierarchical"),
  n_samples,
  dim = 32L,
  seed = 42L,
  parameters = NULL
)

Arguments

Value

A list with the following elements:

• data - Numeric matrix of shape ⁠n_samples x dim⁠

• membership - Integer vector of cluster/branch assignments (NULL for "swiss_role")

Description

Get cluster assignments

Usage

membership(x)

## S3 method for class 'KMeansCluster'
membership(x)

Arguments

Value

Integer vector of length samples with cluster assignments (1-indexed).

Description

Generate a new NearestNeighbours

Usage

new_nearest_neighbour(indices, dist, k, n)

generate_nearest_neigbours_class(indices, dist, k, n)

Arguments

Value

Initialised NearestNeighbours class.

Description

Performs PaCMAP dimensionality reduction on the input data. This function provides a user-friendly interface with input validation before calling the Rust implementation.

Usage

pacmap(
  data,
  knn = NULL,
  n_dim = 2L,
  knn_method = c("kmknn", "balltree", "hnsw", "annoy", "nndescent", "exhaustive", "ivf"),
  nn_params = params_nn(),
  pacmap_params = params_pacmap(),
  seed = 42L,
  use_high_precision = NULL,
  .verbose = TRUE
)

Arguments

Value

A numerical matrix with dimensions samples x n_dim containing the PaCMAP embedding.

Description

For use with manifold_synthetic_data().

Usage

params_clusters(n_clusters = 15L)

Arguments

Value

A named list with the following elements:

• n_clusters - Integer. Number of clusters to generate. Defaults to 15L.

Description

The density-preservation knobs on top of the usual UMAP parameters. densMAP adds ⁠-lambda * Corr(log Ro, log Re)⁠ to the UMAP loss, where Ro is the local radius in the input space and Re the matching radius in the embedding. Setting lambda to 0 recovers plain UMAP.

Usage

params_densmap(lambda = 2, frac = 0.3, var_shift = 0.1)

Arguments

Value

A named list with the following elements:

• lambda - Numeric. Weight of the density term. 0 disables it. The default is the densMAP reference value. Defaults to 2.0.

• frac - Numeric. Fraction of the total epochs, at the end of the run, over which the density term is active. Defaults to 0.3.

• var_shift - Numeric. Additive shift on the variance of the embedding log-radii. Defaults to 0.1.

References

Narayan, Berger & Cho, Nat. Biotechnol., 2021

Description

The density-preservation knobs on top of the usual t-SNE parameters. den-SNE adds ⁠-lambda * Corr(log Ro, log Re)⁠ to the t-SNE loss, where Ro is the local radius in the input space and Re the matching radius in the embedding. Setting lambda to 0 recovers plain t-SNE.

Usage

params_densne(lambda = 0.5, frac = 0.3, var_shift = 0.1)

Arguments

Value

A named list with the following elements:

• lambda - Numeric. Weight of the density term. 0 disables it. The default is higher than the den-SNE reference value (original: 0.1). Defaults to 0.5.

• frac - Numeric. Fraction of the total epochs, at the end of the run, over which the density term is active. Defaults to 0.3.

• var_shift - Numeric. Additive shift on the variance of the embedding log-radii. Defaults to 0.1.

References

Narayan, Berger & Cho, Nat. Biotechnol., 2021

Description

Wrapper function to generate diffusion maps parameters

Usage

params_diffusion_maps(
  bandwidth_scale = 1,
  thresh = 1e-04,
  graph_symmetry = c("additive", "multiplicative", "mnn", "none"),
  alpha_norm = 1,
  t_max = 100L,
  t_custom = NULL,
  n_landmarks = 2048L,
  landmark_method = c("spectral", "random", "density"),
  n_svd = NULL
)

Arguments

Value

A named list with the following elements:

• bandwidth_scale - Numeric. Multiplicative factor applied to the adaptive kernel bandwidth. Defaults to 1.0.

• thresh - Numeric. Sparsity threshold applied to kernel entries. Defaults to 1e-04.

• graph_symmetry - String. Method used to symmetrise the affinity graph. One of c("additive", "multiplicative", "mnn", "none"). Defaults to "additive".

• alpha_norm - Numeric. Anisotropic density-correction exponent. 0 gives the normalised graph Laplacian, 0.5 the Fokker-Planck operator, 1 the Laplace-Beltrami operator. Defaults to 1.0.

• t_max - Integer. Maximum diffusion time considered during automatic selection via Von Neumann entropy knee point detection. Defaults to 100L.

• t_custom - Integer or NULL. Fixed diffusion time. If set, overrides automatic time selection. Defaults to NULL.

• n_landmarks - Integer or NULL. Number of landmarks for compressed diffusion. If NULL, the full N x N diffusion operator is used. Defaults to 2048L.

• landmark_method - String. Method used to select landmarks. One of c("spectral", "random", "density"). Defaults to "spectral".

• n_svd - Integer or NULL. Number of SVD components used in landmark construction. If NULL, the library selects a sensible default. Defaults to NULL.

Description

Wrapper function to generate EVoC parameters

Usage

params_evoc(
  noise_level = 0.5,
  n_epochs = 50L,
  embedding_dim = NULL,
  neighbour_scale = 1,
  symmetrise = TRUE,
  min_samples = 5L,
  base_min_cluster_size = 5L,
  approx_n_clusters = NULL,
  min_similarity_threshold = 0.2,
  max_layers = 10L
)

Arguments

Value

A named list with the following elements:

• noise_level - Numeric. Noise level for the embedding gradient. 0.0 = aggressive, 1.0 = conservative. Defaults to 0.5.

• n_epochs - Integer. Number of embedding optimisation epochs. Defaults to 50L.

• embedding_dim - Integer or NULL. Embedding dimensionality. If NULL, uses min(max(n_neighbours / 4, 4), 16). Defaults to NULL.

• neighbour_scale - Numeric. Multiplier on effective neighbours for fuzzy graph construction. Defaults to 1.0.

• symmetrise - Boolean. Whether to symmetrise the fuzzy graph. Defaults to TRUE.

• min_samples - Integer. Minimum samples for core distance in MST density estimation. Defaults to 5L.

• base_min_cluster_size - Integer. Base minimum cluster size for the finest layer. Defaults to 5L.

• approx_n_clusters - Integer or NULL. If set, binary-searches for approximately this many clusters (single layer output). Defaults to NULL.

• min_similarity_threshold - Numeric. Jaccard similarity threshold for filtering redundant layers. Defaults to 0.2.

• max_layers - Integer. Maximum number of cluster layers to return. Defaults to 10L.

Description

The graph, initialisation and optimisation knobs for ForceAtlas2. local_connectivity, bandwidth, init and randomised only apply when the graph is built from the data via forceatlas2(); forceatlas2_from_graph() ignores them.

Usage

params_fa2(
  local_connectivity = 1,
  bandwidth = 1e-05,
  n_epochs = 500L,
  scaling_ratio = 2,
  gravity = 1,
  strong_gravity = FALSE,
  lin_log = FALSE,
  dissuade_hubs = FALSE,
  edge_weight_influence = 1,
  jitter_tolerance = 1,
  theta = 1.2,
  init = c("spectral", "pca", "random"),
  randomised = FALSE
)

Arguments

Value

A named list with the following elements:

• local_connectivity - Numeric. Number of nearest neighbours assumed to be at distance zero. Defaults to 1.0.

• bandwidth - Numeric. Convergence tolerance for smooth kNN distance binary search. Defaults to 1e-05.

• n_epochs - Integer. Number of optimisation epochs. Defaults to 500L.

• scaling_ratio - Numeric. Repulsion strength. Larger values spread the layout. Defaults to 2.0.

• gravity - Numeric. Pull towards the origin. Keeps disconnected components from drifting off. Defaults to 1.0.

• strong_gravity - Boolean. Distance-independent gravity, scaled by scaling_ratio. Defaults to FALSE.

• lin_log - Boolean. Logarithmic attraction (LinLog). Gives tighter communities. Defaults to FALSE.

• dissuade_hubs - Boolean. Divide the attraction by the node mass. Pushes hubs to the periphery. Defaults to FALSE.

• edge_weight_influence - Numeric. Exponent applied to the edge weights. 0 ignores the weights. Defaults to 1.0.

• jitter_tolerance - Numeric. Tolerated swinging. Larger is faster but less precise. Defaults to 1.0.

• theta - Numeric. Barnes-Hut opening parameter on Gephi's scale. 0 gives the exact repulsion. Defaults to 1.2.

• init - String. Embedding initialisation method. One of c("spectral", "pca", "random"). Defaults to "spectral".

• randomised - Boolean. Use randomised SVD for PCA initialisation. Defaults to FALSE.

References

Jacomy, et al., PLoS ONE, 2014

Description

For use with manifold_synthetic_data().

Usage

params_hierarchical(
  n_supergroups = 3L,
  n_subclusts = 3L,
  supergroup_spread = 15,
  subcluster_spread = 2,
  point_std = 0.4
)

Arguments

Value

A named list with the following elements:

• n_supergroups - Integer. Number of top-level groups. Defaults to 3L.

• n_subclusts - Integer. Number of subclusters per supergroup. Defaults to 3L.

• supergroup_spread - Numeric. Spread of supergroup centres in the ambient space. Defaults to 15.0.

• subcluster_spread - Numeric. Spread of subcluster centres around their supergroup centre. Defaults to 2.0.

• point_std - Numeric. Within-subcluster Gaussian noise. Defaults to 0.4.

Description

Wrapper function to generate k-means parameters

Usage

params_kmeans(
  metric = c("euclidean", "cosine"),
  max_iters = 1000L,
  batch_size = 4096L,
  drift_threshold = 1e-04,
  lr_alpha = 1,
  init = c("parallel", "random"),
  use_hamerly = NULL,
  use_gemm = NULL
)

Arguments

Value

A named list with the following elements:

• metric - String. Distance metric to use. One of c("euclidean", "cosine"). Defaults to "euclidean".

• max_iters - Integer. Maximum number of iterations. Defaults to 1000L.

• batch_size - Integer. Mini-batch size. Only used when method = "minibatch". Defaults to 4096L.

• drift_threshold - Numeric. Below which centroid drift the mini-batch k-means is considered converged. Only used when method = "minibatch". Defaults to 1e-04.

• lr_alpha - Numeric. Learning rate decay for the mini-batch k-means. Original paper uses 1.0. Defaults to 1.0.

• init - String. The initialisation of the centroids. One of c("parallel", "random"). Defaults to "parallel".

• use_hamerly - Boolean or NULL. Shall Hamerly's method be used (only if metric == "euclidean"). Defaults to NULL.

• use_gemm - Boolean or NULL. Shall the GEMM path be used. Useful on high dimensional data. If NULL, choice will be based on heuristics. Defaults to NULL.

Description

Wrapper function to generate nearest neighbour parameters

Usage

params_nn(
  dist_metric = c("euclidean", "cosine"),
  n_tree = 50L,
  search_budget = NULL,
  m = 16L,
  ef_construction = 100L,
  ef_search = 100L,
  diversify_prob = 0,
  delta = 0.001,
  ef_budget = NULL,
  extract_knn = TRUE,
  bt_budget = 0.1,
  n_list = NULL,
  n_probes = NULL
)

Arguments

Value

A named list with the following elements:

• dist_metric - String. The distance metric to use. One of c("euclidean", "cosine"). Defaults to "euclidean".

• n_tree - Integer. Number of trees for Annoy. Defaults to 50L.

• search_budget - Integer or NULL. Search budget for Annoy. Defaults to NULL.

• m - Integer. Number of bidirectional links for HNSW. Defaults to 16L.

• ef_construction - Integer. Size of the dynamic candidate list during HNSW construction. Defaults to 100L.

• ef_search - Integer. Size of the dynamic candidate list during HNSW search. Defaults to 100L.

• diversify_prob - Numeric. Diversification probability for NN descent. Defaults to 0.0.

• delta - Numeric. Precision parameter for NN descent. Defaults to 0.001.

• ef_budget - Integer or NULL. Effort budget for NN descent. Ignored when extract_knn is TRUE, as no search runs. Defaults to NULL.

• extract_knn - Boolean. Only affects the "nndescent" backend. If TRUE, the descent hands back the graph it just built instead of running a beam search over it. Faster, at a recall of roughly 0.98 rather than 0.99-1.00. Defaults to TRUE.

• bt_budget - Numeric. Budget for ball tree search. Defaults to 0.1.

• n_list - Integer or NULL. Number of clusters to use for IVF. If NULL, uses sqrt(n). Defaults to NULL.

• n_probes - Integer or NULL. Number of clusters to probe for IVF. If NULL, uses sqrt(n_list). Defaults to NULL.

Description

Wrapper function to generate PaCMAP parameters

Usage

params_pacmap(
  n_near = 10L,
  n_mid_near = 5L,
  n_further = 20L,
  mn_candidate_start = 4L,
  mn_candidate_end = 50L,
  init = c("pca", "random"),
  optimiser = c("adam_parallel", "adam"),
  lr = 1,
  n_epochs = NULL,
  beta1 = 0.9,
  beta2 = 0.999,
  eps = 1e-07,
  phase1_end = NULL,
  phase2_end = NULL
)

Arguments

Value

A named list with the following elements:

• n_near - Integer. Near pairs per point (attractive). Defaults to 10L.

• n_mid_near - Integer. Mid-near pairs per point. Defaults to 5L.

• n_further - Integer. Further (random) pairs per point. Defaults to 20L.

• mn_candidate_start - Integer. Start index into kNN list for mid-near candidate window. Defaults to 4L.

• mn_candidate_end - Integer. End index into kNN list for mid-near candidate window. Also determines the kNN search size. Defaults to 50L.

• init - String. Embedding initialisation. One of c("pca", "random"). Defaults to "pca".

• optimiser - String. The optimiser. One of c("adam_parallel", "adam"). Defaults to "adam_parallel".

• lr - Numeric. Adam learning rate. Defaults to 1.0.

• n_epochs - Integer or NULL. Total optimisation epochs. If NULL, resolved downstream to 450. Defaults to NULL.

• beta1 - Numeric. Adam first moment decay. Defaults to 0.9.

• beta2 - Numeric. Adam second moment decay. Defaults to 0.999.

• eps - Numeric. Adam numerical stability constant. Defaults to 1e-07.

• phase1_end - Integer or NULL. Epoch at which phase 1 ends. If NULL, resolved downstream to 100. Defaults to NULL.

• phase2_end - Integer or NULL. Epoch at which phase 2 ends. If NULL, resolved downstream to 200. Defaults to NULL.

Description

Wrapper function to generate PHATE parameters

Usage

params_phate(
  decay = 40,
  bandwidth_scale = NULL,
  t_max = 100L,
  t_custom = NULL,
  gamma = 1,
  n_landmarks = 2048L,
  landmark_method = c("spectral", "random", "density"),
  n_svd = NULL,
  mds_method = c("sgd_dense", "classic"),
  graph_symmetry = c("additive", "multiplicative", "mnn", "none")
)

Arguments

Value

A named list with the following elements:

• decay - Numeric. Alpha decay parameter controlling the kernel bandwidth. Higher values create sharper transitions. Defaults to 40.0.

• bandwidth_scale - Numeric or NULL. Scaling factor applied to the kernel bandwidth. If NULL, the library selects a sensible default. Defaults to NULL.

• t_max - Integer. Maximum diffusion time considered during automatic selection via Von Neumann entropy knee point detection. Defaults to 100L.

• t_custom - Integer or NULL. Fixed diffusion time. If set, overrides automatic time selection. Defaults to NULL.

• gamma - Numeric. Informational distance parameter for the diffusion potential. Defaults to 1.0.

• n_landmarks - Integer or NULL. Number of landmarks for compressed diffusion. If NULL, the full N x N diffusion operator is used. Defaults to 2048L.

• landmark_method - String. Method used to select landmarks. One of c("spectral", "random", "density"). Defaults to "spectral".

• n_svd - Integer or NULL. Number of SVD components used in landmark construction. If NULL, the library selects a sensible default. Defaults to NULL.

• mds_method - String. MDS algorithm used for the final embedding. One of c("sgd_dense", "classic"). Defaults to "sgd_dense".

• graph_symmetry - String. Method used to symmetrise the affinity graph. One of c("additive", "multiplicative", "mnn", "none"). Defaults to "additive".

Description

For use with manifold_synthetic_data().

Usage

params_swiss_role(noise = 0.1)

Arguments

Value

A named list with the following elements:

• noise - Numeric. Amount of noise to add. Defaults to 0.1.

Description

For use with manifold_synthetic_data().

Usage

params_swiss_role_biased(noise = 0.1, bias = 2.5)

Arguments

Value

A named list with the following elements:

• noise - Numeric. Amount of noise to add. Defaults to 0.1.

• bias - Numeric. The sampling bias across the manifold. Defaults to 2.5.

Description

For use with manifold_synthetic_data().

Usage

params_trajectory(
  topology = c("bifurcation", "linear", "combination"),
  cell_trajectories = NULL,
  noise = 0.1
)

Arguments

Value

A named list with the following elements:

• topology - String. Ignored if cell_trajectories is not NULL. One of c("bifurcation", "linear", "combination"). Defaults to "bifurcation".

• cell_trajectories - Any. Optional named list with three equal-length vectors: parent (integer, NA for root, zero-indexed), split_at (numeric, fraction along parent where branch starts), and length (numeric, length of the branch). If NULL, topology is used instead. Defaults to NULL.

• noise - Numeric. Amount of noise to add. Defaults to 0.1.

Description

Wrapper function to generate t-SNE parameters

Usage

params_tsne(
  lr = NULL,
  n_epochs = 1000L,
  early_exag_iter = 250L,
  early_exag_factor = 12,
  late_exag_factor = NULL,
  theta = 0.5,
  n_interp_points = 3L,
  max_depth = 7L,
  init = c("pca", "spectral", "random"),
  randomised = TRUE
)

Arguments

Value

A named list with the following elements:

• lr - Numeric or NULL. Learning rate. If NULL, the Rust backend sets it to max((n_samples / 12), 200), following the N-dependent heuristic of Belkina et al. (2019). Defaults to NULL.

• n_epochs - Integer. Number of optimisation epochs. Defaults to 1000L.

• early_exag_iter - Integer. Number of early exaggeration iterations. Defaults to 250L.

• early_exag_factor - Numeric. Early exaggeration factor. Defaults to 12.0.

• late_exag_factor - Numeric or NULL. Late exaggeration factor, if you wish to use one. Can be useful on large data sets (set it to 2.0 to 4.0). Defaults to NULL.

• theta - Numeric. Barnes-Hut approximation angle. Lower values increase accuracy at the cost of speed. Defaults to 0.5.

• n_interp_points - Integer. Number of interpolation points per grid cell for FFT acceleration ("fft" and "fft_3k"). Defaults to 3L.

• max_depth - Integer. Maximum Barnes-Hut tree depth for the quick-and-dirty optimiser ("bh_qd"). Smaller is faster and coarser; qdtsne recommends 7 to 10. No effect on the other optimisers. Defaults to 7L.

• init - String. Embedding initialisation method. One of c("pca", "spectral", "random"). Defaults to "pca".

• randomised - Boolean. Use randomised SVD for PCA initialisation. Defaults to TRUE.

References

Belkina, et al., Nat. Commun., 2019

Description

Wrapper function to generate UMAP parameters

Usage

params_umap(
  local_connectivity = 1,
  bandwidth = 1e-05,
  mix_weight = 1,
  lr = 1,
  n_epochs = NULL,
  neg_sample_rate = 5L,
  gamma = 1,
  optimiser = c("adam_parallel", "sgd", "adam"),
  init = c("spectral", "pca", "random"),
  randomised = TRUE
)

Arguments

Value

A named list with the following elements:

• local_connectivity - Numeric. Number of nearest neighbours assumed to be at distance zero. Defaults to 1.0.

• bandwidth - Numeric. Convergence tolerance for smooth kNN distance binary search. Defaults to 1e-05.

• mix_weight - Numeric. Balance between fuzzy union and directed graph during symmetrisation. Defaults to 1.0.

• lr - Numeric. Learning rate. Defaults to 1.0.

• n_epochs - Integer or NULL. Number of optimisation epochs. If NULL, resolved downstream based on data size. Defaults to NULL.

• neg_sample_rate - Integer. Number of negative samples per positive sample. Defaults to 5L.

• gamma - Numeric. Repulsion strength. Defaults to 1.0.

• optimiser - String. The optimiser. One of c("adam_parallel", "sgd", "adam"). Defaults to "adam_parallel".

• init - String. Embedding initialisation method. One of c("spectral", "pca", "random"). Defaults to "spectral".

• randomised - Boolean. Use randomised SVD for PCA initialisation. Defaults to TRUE.

Description

Performs PHATE dimensionality reduction on the input data. This function provides a user-friendly interface with input validation before calling the Rust implementation.

Usage

phate(
  data,
  knn = NULL,
  n_dim = 2L,
  k = 5L,
  knn_method = c("kmknn", "balltree", "hnsw", "annoy", "nndescent", "exhaustive", "ivf"),
  nn_params = params_nn(),
  phate_params = params_phate(),
  seed = 42L,
  use_high_precision = NULL,
  .verbose = TRUE
)

Arguments

Value

A numerical matrix with dimensions samples x n_dim containing the PHATE embedding.

Description

This is an interface into various (approximate) nearest neighbour searches implemented in the Rust crate ann-search-rs. They designed for incredible fast in-memory searches for kNN generation.

Usage

rs_approx_nearest_neighbours(data, k, ann_method, ann_params, seed, verbose)

Arguments

Value

A list with the following elements

• indices - flat representation of the indices.

• dist - flat representaitons of the distances.

• k - number of neighbours.

• n - number of samples.

Description

Calculates the adjusted Rand index in Rust between two membership vectors.

Usage

rs_ari(cluster_membership_a, cluster_membership_b)

Arguments

Value

Returns the adjusted Rand index between the two groups.

Description

Generates synthetic data, i.e., the Swiss role to test different manifold learning techniques

Usage

rs_data_biased_swiss_role(n_samples, noise, bias, seed)

Arguments

Value

The biased swiss role synthetic data with the desired parameters.

Description

Generates synthetic data with clear cluster structure.

Usage

rs_data_clusters(n_samples, dim, n_clusters, seed)

Arguments

Value

A list with the following elements:

• data - Numerical matrix with the data.

• clusters - Cluster assignments

Description

Generates synthetic data with a two-level cluster hierarchy: n_supergroups top-level groups each containing n_subclusts tight subclusters. Supergroup centres are spread far apart; subcluster centres sit tightly around their supergroup centre.

Note that the actual number of samples returned may be slightly less than n_samples if it is not evenly divisible by n_supergroups * n_subclusts.

Usage

rs_data_hierarchical(
  n_samples,
  dim,
  n_supergroups,
  n_subclusts,
  supergroup_spread,
  subcluster_spread,
  point_std,
  seed
)

Arguments

Value

A named list with three elements: data, a numeric matrix of shape samples x dim; supergroup, an integer vector of supergroup labels (⁠0..n_supergroups⁠) one per sample; and subgroup, an integer vector of subcluster labels (⁠0..n_supergroups * n_subclusts⁠) one per sample.

Description

Generates synthetic data, i.e., the Swiss role to test different manifold learning techniques

Usage

rs_data_swiss_role(n_samples, noise, seed)

Arguments

Value

The swiss role synthetic data with the desired parameters.

Description

Generates synthetic data that has a tree-like structure to simulate evolution/trajectory of data.

Usage

rs_data_trajectory(n_samples, dim, topology, cell_trajectories, noise, seed)

Arguments

Value

A list with the following elements:

• data - Numerical matrix with the generated data.

• branches - Branch assignments for each sample.

Description

Leverages the densMAP implementation in manifolds-rs - a very fast Rust-based implementation. densMAP is UMAP with an added density-preserving term, so tight clusters stay tight and diffuse ones stay diffuse. Setting lambda to 0 in the parameters recovers plain UMAP.

Usage

rs_densmap(
  embd,
  n_dim,
  min_dist,
  spread,
  k,
  densmap_params,
  seed,
  use_high_precision,
  verbose
)

Arguments

Value

The densMAP embeddings.

References

Narayan, Berger & Cho, Nature Biotechnology, 2021

Description

Leverages the densMAP implementation in manifolds-rs - a very fast Rust-based implementation. densMAP is UMAP with an added density-preserving term, so tight clusters stay tight and diffuse ones stay diffuse. This version uses a pre-computed kNN graph, please see new_nearest_neighbour().

Usage

rs_densmap_from_knn(
  embd,
  knn_data,
  n_dim,
  min_dist,
  spread,
  k,
  densmap_params,
  seed,
  use_high_precision,
  verbose
)

Arguments

Value

The densMAP embeddings.

References

Narayan, Berger & Cho, Nature Biotechnology, 2021

Description

Leverages the den-SNE implementation in manifolds-rs - a very fast Rust-based implementation. den-SNE is tSNE with an added density-preserving term, so tight clusters stay tight and diffuse ones stay diffuse. Setting lambda to 0 in the parameters recovers plain tSNE.

Usage

rs_densne(
  embd,
  n_dim,
  perplexity,
  approx_type,
  densne_params,
  seed,
  use_high_precision,
  verbose
)

Arguments

Value

The den-SNE embeddings.

References

Narayan, Berger & Cho, Nature Biotechnology, 2021

Description

Leverages the den-SNE implementation in manifolds-rs - a very fast Rust-based implementation. den-SNE is tSNE with an added density-preserving term, so tight clusters stay tight and diffuse ones stay diffuse. This version uses a pre-computed kNN graph, please see new_nearest_neighbour().

Usage

rs_densne_from_knn(
  embd,
  knn_data,
  n_dim,
  perplexity,
  approx_type,
  densne_params,
  seed,
  use_high_precision,
  verbose
)

Arguments

Value

The den-SNE embeddings.

References

Narayan, Berger & Cho, Nature Biotechnology, 2021

Description

Leverages the Diffusion Maps implementation in manifolds-rs - a very fast Rust-based implementation.

Usage

rs_diffusion_maps(embd, n_dim, k, dm_params, seed, use_high_precision, verbose)

Arguments

Value

The diffusion maps embeddings.

Description

Leverages the Diffusion Maps implementation in manifolds-rs - a very fast Rust-based implementation. This version uses a pre-computed kNN graph, please see new_nearest_neighbour().

Usage

rs_diffusion_maps_from_knn(
  embd,
  knn_data,
  n_dim,
  k,
  dm_params,
  seed,
  use_high_precision,
  verbose
)

Arguments

Value

The diffusion maps embeddings.

Description

Wrapper function into the Rust interface for EVoC clustering.

Usage

rs_evoc(
  embd,
  n_neighbours,
  evoc_params,
  return_knn,
  seed,
  use_high_precision,
  verbose
)

Arguments

Value

A named list with:

• evoc_res - List with the EVoC results

• knn - Optional list (can be NULL) with the kNN graph

Description

Wrapper function into the Rust interface for EVoC clustering. This version uses a pre-computed kNN graph, please see new_nearest_neighbour().

Usage

rs_evoc_from_knn(
  embd,
  knn_data,
  n_neighbours,
  evoc_params,
  seed,
  use_high_precision,
  verbose
)

Arguments

Value

A named list with cluster layers, membership strengths, persistence scores, and the kNN graph.

Description

Leverages the ForceAtlas2 implementation in manifolds-rs. Builds the UMAP fuzzy union graph from the data and lays it out with ForceAtlas2.

Usage

rs_forceatlas2(embd, k, fa2_params, seed, use_high_precision, verbose)

Arguments

Value

The ForceAtlas2 embedding, samples x 2.

Description

Leverages the ForceAtlas2 implementation in manifolds-rs and lays out a caller-supplied undirected graph. Each edge is passed once; the Rust side adds the reverse direction.

Usage

rs_forceatlas2_from_graph(
  from,
  to,
  weight,
  n,
  init,
  fa2_params,
  seed,
  use_high_precision,
  verbose
)

Arguments

Value

The ForceAtlas2 embedding, n x 2.

Description

Leverages the ForceAtlas2 implementation in manifolds-rs. This version uses a pre-computed kNN graph, please see new_nearest_neighbour().

Usage

rs_forceatlas2_from_knn(
  embd,
  knn_data,
  k,
  fa2_params,
  seed,
  use_high_precision,
  verbose
)

Arguments

Value

The ForceAtlas2 embedding, samples x 2.

Description

Calculates inertia for k-means clustering given the data, centroids and membership

Usage

rs_intertia(data, centroids, cluster_membership)

Arguments

Value

The inertia score

Description

Rust interface for k-means clustering using Lloyd's algorithm with SIMD or GEMM acceleration depending on dimensionality. It exposes the high performance k-means clustering code from the Rust crate ann-search-rs for rapid clustering.

Usage

rs_k_means(data, k, kmeans_params, seed, verbose)

Arguments

Value

A named list with:

• centroids - Numeric matrix of shape k x features.

• assignments - Integer vector of length samples (1-indexed).

Description

Rust interface for mini batch k-means clustering from bixverse-rs. This version can be very useful in cases where you overcluster the data.

Usage

rs_k_means_mini_batch(data, k, kmeans_params, seed, verbose)

Arguments

Value

A named list with:

• centroids - Numeric matrix of shape k x features.

• assignments - Integer vector of length samples (1-indexed).

Description

Leverages the PacMAP implementation in manifolds-rs - a very fast Rust-based implementation.

Usage

rs_pacmap(embd, n_dim, pacmap_params, seed, use_high_precision, verbose)

Arguments

Value

The PaCMAP embeddings.

Description

Leverages the PacMAP implementation in manifolds-rs - a very fast Rust-based implementation. This version uses a pre-computed kNN graph, please see new_nearest_neighbour().

Usage

rs_pacmap_from_knn(
  embd,
  knn_data,
  n_dim,
  pacmap_params,
  seed,
  use_high_precision,
  verbose
)

Arguments

Value

The PaCMAP embeddings.

Description

Leverages the PHATE implementation in manifolds-rs - a very fast Rust-based implementation.

Usage

rs_phate(embd, n_dim, k, phate_params, seed, use_high_precision, verbose)

Arguments

Value

The PHATE embedding as a matrix of shape samples x n_dim.

Description

Leverages the PHATE implementation in manifolds-rs - a very fast Rust-based implementation. This version uses a pre-computed kNN graph, please see new_nearest_neighbour().

Usage

rs_phate_from_knn(
  embd,
  knn_data,
  n_dim,
  k,
  phate_params,
  seed,
  use_high_precision,
  verbose
)

Arguments

Value

The PHATE embedding as a matrix of shape samples x n_dim.

Description

Calculates the Silhouette in Rust given the original data and a membership vector. a(i) and b(i) are mean squared Euclidean distances, which keeps the whole thing closed-form and avoids materialising any pairwise distance. The trade-off is that the scores are not the numbers a plain-Euclidean silhouette gives: squaring inflates b more than a, so the values run higher. The sign is unaffected, so which points sit in the wrong cluster is the same call, but do not compare the magnitudes against implementations that use plain Euclidean.

Usage

rs_silhouette_score(data, cluster_membership)

Arguments

Value

A list with the following items

• mean_silhouette - Mean silhouette scores per cluster.

• silhouette_scores - Silhouette scores per given data point.

Description

Leverages the tSNE implementation in manifolds-rs - a very fast Rust-based implementation. You have three optimiser options: "bh" which tends to be faster on smaller datasets, and "fft" or its three-kernel variant "fft_3k" for large data sets.

Usage

rs_tsne(
  embd,
  n_dim,
  perplexity,
  approx_type,
  tsne_params,
  seed,
  use_high_precision,
  verbose
)

Arguments

Value

The tSNE embeddings.

Description

Leverages the tSNE implementation in manifolds-rs - a very fast Rust-based implementation. You have three optimiser options: "bh" which tends to be faster on smaller datasets, and "fft" or its three-kernel variant "fft_3k" for large data sets. This version uses a pre-computed kNN graph, please see new_nearest_neighbour().

Usage

rs_tsne_from_knn(
  embd,
  knn_data,
  n_dim,
  perplexity,
  approx_type,
  tsne_params,
  seed,
  use_high_precision,
  verbose
)

Arguments

Value

The tSNE embeddings.

Description

Leverages the UMAP implementation in manifolds-rs - a very fast Rust-based implementation.

Usage

rs_umap(
  embd,
  n_dim,
  min_dist,
  spread,
  k,
  umap_params,
  seed,
  use_high_precision,
  verbose
)

Arguments

Value

The UMAP embeddings.

Description

Leverages the UMAP implementation in manifolds-rs - a very fast Rust-based implementation. This version uses a pre-computed kNN graph, please see new_nearest_neighbour().

Usage

rs_umap_from_knn(
  embd,
  knn_data,
  n_dim,
  min_dist,
  spread,
  k,
  umap_params,
  seed,
  use_high_precision,
  verbose
)

Arguments

Value

The UMAP embeddings.

Description

Performs t-SNE dimensionality reduction on the input data. This function provides a user-friendly interface with input validation before calling the Rust implementation.

Usage

tsne(
  data,
  knn = NULL,
  n_dim = 2L,
  perplexity = 20,
  approx_type = c("bh", "bh_qd", "fft", "fft_3k"),
  knn_method = c("kmknn", "balltree", "hnsw", "annoy", "nndescent", "exhaustive", "ivf"),
  nn_params = params_nn(),
  tsne_params = params_tsne(),
  seed = 42L,
  use_high_precision = NULL,
  .verbose = TRUE
)

Arguments

Details

The number of neighbours will be '3 * perplexity“, as this is a usual default in tSNE.

Value

A numerical matrix with dimensions samples x n_dim containing the t-SNE embedding.

Description

Performs UMAP dimensionality reduction on the input data. This function provides a user-friendly interface with input validation before calling the Rust implementation.

Usage

umap(
  data,
  knn = NULL,
  n_dim = 2L,
  k = 15L,
  min_dist = 0.5,
  spread = 1,
  knn_method = c("kmknn", "balltree", "hnsw", "annoy", "nndescent", "exhaustive", "ivf"),
  nn_params = params_nn(),
  umap_params = params_umap(),
  seed = 42L,
  use_high_precision = NULL,
  .verbose = TRUE
)

Arguments

Value

A numerical matrix with dimensions samples x n_dim containing the UMAP embedding.