set_nn_control: Verify and set nearest neighbor parameter list.

In cole-trapnell-lab/monocle3: Clustering, Differential Expression, and Trajectory Analysis for Single-Cell RNA-Seq

Verify and set nearest neighbor parameter list.

Description

Verifies the listed parameter values that will be passed to the nearest neighbor function given by nn_control[['method']]. Unspecified values are set to default values. To see the default values, call the function with nn_control=list(show_values=TRUE).

Usage

set_nn_control(
  mode,
  nn_control = list(),
  nn_control_default = list(),
  nn_index = NULL,
  k = NULL,
  verbose = FALSE
)

Arguments

mode	the nearest neighbor operation for which the nn_control list will be used. 1=make index, 2=search index, and 3=both make and search index. Required parameter.
nn_control	an optional list of parameters passed to the nearest neighbor function specified by nn_control[['method']]. If a value is not given in nn_control, the value in nn_control_default is used. If neither is given, a fallback default is assigned.
nn_control_default	an optional nn_control list to use when a parameter is not given in nn_control.
nn_index	an nn_index. This may be used to look up parameters that were used to make an index. For example, the default search_k parameter depends on the n_trees values used to make the index. The default is NULL.
k	integer the number of desired nearest neighbor points to return from a search. k is used to set the annoy search_k parameter when search_k is not given in nn_control or nn_control_default where search_k is 2 * n_trees * k. test the hnsw ef parameter, which must be at least as large as k. k is ignored for index builds and does not give the number of nearest neighbors to return for a search.
verbose	a boolean indicating whether to emit verbose output.

Value

an updated nn_control list.

Optional nn_control parameters

method

The method used to find nearest neighbor points. The available methods are 'nn2', 'annoy', and 'hnsw'. Detailed information about each method can be found on the WWW sites: https://cran.r-project.org/web/packages/RANN/, https://cran.r-project.org/web/packages/RcppAnnoy/index.html, and https://cran.rstudio.com/web/packages/RcppHNSW/index.html.

metric

The distance metric used by the nearest neighbor functions. Annoy accepts 'euclidean', 'cosine', 'manhattan', and 'hamming'. HNSW accepts 'euclidean', 'l2', 'cosine', and 'ip'. RANN uses 'euclidean'.

n_trees

The annoy index build parameter that affects the build time and index size. Larger values give more accurate results, longer build times, and larger indexes.

search_k

The annoy index search parameter that affects the search accuracy and time. Larger values give more accurate results and longer search times. Default is 2 * n_trees * k. In order to set search_k, the following conditions are tested and the first TRUE condition is used: nn_control[['search_k']] exists; mode=2 and nn_index and k are not NULL; nn_control[['n_trees']] exists; nn_control_default[['search_k']] exists; nn_control_default[['n_trees']] exists. If none of those is TRUE, the fallback default n_trees value is used. If the set_nn_control k parameter value is not NULL, it is used; otherwise, the default is used.

M

The HNSW index build parameter that affects the search accuracy and memory requirements. Larger values give more accurate search results and increase the index memory use.

ef_construction

The HNSW index build parameter that affects the search accuracy and index build time. Larger values give more accurate search results and longer build times. Default is 200.

ef

The HNSW index search parameter that affects the search accuracy and search time. Larger values give more accurate results and longer search times. ef must be greater than or equal to k.

grain_size

The HNSW parameter that gives the minimum amount of work to do per thread.

cores

The annoy and HNSW parameter that gives the number of threads to use for the annoy index search and for the HNSW index build and search.

show_values

A logical value used to show the nearest neighbor parameters to use, and then exit the function. When show_values=TRUE is the only nn_control value, the parameters are the defaults for the function. Each function that calls set_nn_control may have its own nn_control_default list.

cole-trapnell-lab/monocle3 documentation built on April 7, 2024, 9:24 p.m.