Options for initialize(). More...

#include <Options.hpp>

Public Attributes
double	local_connectivity = 1

double	bandwidth = 1

double	mix_ratio = 1

double	spread = 1

double	min_dist = 0.1

double	a = 0

double	b = 0

double	repulsion_strength = 1

InitializeMethod	initialize_method = InitializeMethod::SPECTRAL

bool	initialize_random_on_spectral_fail = true

double	initialize_spectral_scale = 10

bool	initialize_spectral_jitter = false

double	initialize_spectral_jitter_sd = 0.0001

double	initialize_random_scale = 10

RngEngine::result_type	initialize_seed = sanisizer::cap<typename RngEngine::result_type>(9876543210)

int	num_epochs = -1

double	learning_rate = 1

double	negative_sample_rate = 5

int	num_neighbors = 15

RngEngine::result_type	optimize_seed = sanisizer::cap<typename RngEngine::result_type>(1234567890)

int	num_threads = 1

int	parallel_optimization = false

Detailed Description

Options for initialize().

Member Data Documentation

◆ a

double umappp::Options::a = 0

Positive value for the \(a\) parameter for the fuzzy set membership strength calculations. Larger values yield a sharper decay in membership strength with increasing distance between observations.

If this or Options::a is set to zero, a suitable value for this parameter is automatically determined from Options::spread and Options::min_dist.

Value in \((0, 1)\) for the \(b\) parameter for the fuzzy set membership strength calculations. Larger values yield an earlier decay in membership strength with increasing distance between observations.

If this or Options::a is set to zero, a suitable value for this parameter is automatically determined from the values provided to Options::spread and Options::min_dist.

◆ bandwidth

double umappp::Options::bandwidth = 1

Effective bandwidth of the kernel when converting the distance to a neighbor into a fuzzy set membership confidence. Larger values reduce the decay in confidence with respect to distance, increasing connectivity and favoring global structure.

◆ initialize_method

InitializeMethod umappp::Options::initialize_method = InitializeMethod::SPECTRAL

How to initialize the embedding.

◆ initialize_random_on_spectral_fail

bool umappp::Options::initialize_random_on_spectral_fail = true

Whether to fall back to random sampling from a normal distribution (i.e., same as InitializeMethod::RANDOM) if spectral initialization fails. If false, any existing values in the input array will be used, i.e., same as InitializeMethod::NONE. Only relevant if Options::initialize_method = InitializeMethod::SPECTRAL.

◆ initialize_random_scale

double umappp::Options::initialize_random_scale = 10

Scale of the randomly generated coordinates when Options::initialize_method = InitializeMethod::RANDOM. Coordinates are sampled from a uniform distribution from \([-x, x)\) where \(x\) is this value.

◆ initialize_seed

RngEngine::result_type umappp::Options::initialize_seed = sanisizer::cap<typename RngEngine::result_type>(9876543210)

Seed for the random number generation during initialization. Only relevant if Options::initialize_method = InitializeMethod::SPECTRAL and Options::initialize_spectral_jitter = true, or Options::initialize_method = InitializeMethod::RANDOM.

◆ initialize_spectral_jitter

bool umappp::Options::initialize_spectral_jitter = false

Whether to jitter the coordinates after spectral initialization to separate duplicate observations (e.g., to avoid overplotting). This is done with normally-distributed noise of mean zero and standard deviation of Options::initialize_spectral_jitter_sd. Only relevant if Options::initialize_method = InitializeMethod::SPECTRAL.

◆ initialize_spectral_jitter_sd

double umappp::Options::initialize_spectral_jitter_sd = 0.0001

Standard deviation of the jitter to apply after spectral initialization. Only relevant if Options::initialize_method = InitializeMethod::SPECTRAL and Options::initialize_spectral_jitter = true.

◆ initialize_spectral_scale

double umappp::Options::initialize_spectral_scale = 10

Maximum absolute magnitude of the coordinates after spectral initialization. All coordinates are scaled such that the maximum absolute magnitude is equal to this value. This ensures that outlier observations will not have large absolute distances that may interfere with optimization. Only relevant if Options::initialize_method = InitializeMethod::SPECTRAL.

◆ learning_rate

double umappp::Options::learning_rate = 1

Initial learning rate used in the gradient descent. Larger values can improve the speed of convergence but at the cost of stability.

◆ local_connectivity

double umappp::Options::local_connectivity = 1

The number of nearest neighbors that are assumed to be always connected, with maximum membership confidence. Larger values increase the connectivity of the embedding and reduce the focus on local structure. This may be a fractional number of neighbors.

◆ min_dist

double umappp::Options::min_dist = 0.1

Minimum distance between observations in the final low-dimensional embedding. Smaller values will increase local clustering while larger values favor a more even distribution of points throughout the low-dimensional space. This is interpreted relative to the spread of points in Options::spread.

◆ mix_ratio

double umappp::Options::mix_ratio = 1

Mixing ratio to use when combining fuzzy sets. This symmetrizes the sets by ensuring that the confidence of point \(A\) belonging to point \(B\)'s set is the same as the confidence of \(B\) belonging to \(A\)'s set. A mixing ratio of 1 will take the union of confidences, a ratio of 0 will take the intersection, and intermediate values will interpolate between them. Larger values (up to 1) favor connectivity and more global structure.

◆ negative_sample_rate

double umappp::Options::negative_sample_rate = 5

Rate of sampling negative observations to compute repulsive forces. This is interpreted with respect to the number of neighbors with attractive forces, i.e., for each attractive interaction, n negative samples are taken for repulsive interactions. Smaller values can improve the speed of convergence but at the cost of stability.

◆ num_epochs

int umappp::Options::num_epochs = -1

Number of epochs for the gradient descent, i.e., optimization iterations. Larger values improve accuracy at the cost of computational work. If the requested number of epochs is negative, a value is automatically chosen based on the size of the dataset:

For datasets with no more than 10000 observations, the number of epochs is set to 500.
For larger datasets, the number of epochs decreases from 500 according to the number of cells beyond 10000, to a lower limit of 200.

This choice aims to reduce computational work for very large datasets.

◆ num_neighbors

int umappp::Options::num_neighbors = 15

Number of neighbors to use to define the fuzzy sets. Larger values improve connectivity and favor preservation of global structure, at the cost of increased computational work. This argument is only used in certain initialize() overloads that perform identification of the nearest neighbors.

◆ num_threads

int umappp::Options::num_threads = 1

Number of threads to use. The parallelization scheme is determined by parallelize() for most calculations. The exception is the nearest-neighbor search in some of the initialize() overloads, where the scheme is determined by knncolle::parallelize() instead.

If Options::parallel_optimization = true, this option will also affect the layout optimization, i.e., the gradient descent iterations.

◆ optimize_seed

RngEngine::result_type umappp::Options::optimize_seed = sanisizer::cap<typename RngEngine::result_type>(1234567890)

Seed for the random number generator when sampling negative observations in the optimization step.

◆ parallel_optimization

int umappp::Options::parallel_optimization = false

Whether to enable parallel optimization. If set to true, this will use the number of threads specified in Options::num_threads for the layout optimization step.

By default, this is set to false as the increase in the number of threads is usually not cost-effective for layout optimization. Specifically, while CPU usage scales with the number of threads, the time spent does not decrease by the same factor. We also expect that the number of available CPUs is at least equal to the requested number of threads, otherwise contention will greatly degrade performance. Nonetheless, users can enable parallel optimization if cost is no issue - usually a higher number of threads (above 4) is required to see a reduction in time.

If the UMAPPP_NO_PARALLEL_OPTIMIZATION macro is defined, umappp will not be compiled with support for parallel optimization. This may be desirable in environments that have no support for threading or atomics, or to reduce the binary size if parallelization is not of interest. In such cases, enabling parallel optimization and calling Status::run() will raise an error.

◆ repulsion_strength

double umappp::Options::repulsion_strength = 1

Modifier for the repulsive force. Larger values increase repulsion and favor local structure.

◆ spread

double umappp::Options::spread = 1

Scale of the coordinates of the final low-dimensional embedding.

The documentation for this struct was generated from the following file:

umappp/Options.hpp

Public Attributes