mlpack.krann

krann(...)K-Rank-Approximate-Nearest-Neighbors (kRANN)

>>> from mlpack import krann

This program will calculate the k rank-approximate-nearest-neighbors of a set of points. You may specify a separate set of reference points and query points, or just a reference set which will be used as both the reference and query set. You must specify the rank approximation (in %) (and optionally the success probability).

For example, the following will return 5 neighbors from the top 0.1% of the data (with probability 0.95) for each point in 'input.csv' and store the distances in 'distances.csv' and the neighbors in the file 'neighbors.csv':

$ allkrann -k 5 -r input.csv -d distances.csv -n neighbors.csv --tau 0.1

Note that tau must be set such that the number of points in the corresponding percentile of the data is greater than k. Thus, if we choose tau = 0.1 with a dataset of 1000 points and k = 5, then we are attempting to choose 5 nearest neighbors out of the closest 1 point -- this is invalid and the program will terminate with an error message.

The output files are organized such that row i and column j in the neighbors output file corresponds to the index of the point in the reference set which is the i'th nearest neighbor from the point in the query set with index j. Row i and column j in the distances output file corresponds to the distance between those two points.

## input options

- alpha (float): The desired success probability. Default value 0.95.
- copy_all_inputs (bool): If specified, all input parameters will be deep copied before the method is run. This is useful for debugging problems where the input parameters are being modified by the algorithm, but can slow down the code.
- first_leaf_exact (bool): The flag to trigger sampling only after exactly exploring the first leaf.
- input_model (mlpack.RANNModelType): Pre-trained kNN model.
- k (int): Number of nearest neighbors to find. Default value 0.
- leaf_size (int): Leaf size for tree building (used for kd-trees, UB trees, R trees, R* trees, X trees, Hilbert R trees, R+ trees, R++ trees, and octrees). Default value 20.
- naive (bool): If true, sampling will be done without using a tree.
- query (numpy matrix or arraylike, float dtype): Matrix containing query points (optional).
- random_basis (bool): Before tree-building, project the data onto a random orthogonal basis.
- reference (numpy matrix or arraylike, float dtype): Matrix containing the reference dataset.
- sample_at_leaves (bool): The flag to trigger sampling at leaves.
- seed (int): Random seed (if 0, std::time(NULL) is used). Default value 0.
- single_mode (bool): If true, single-tree search is used (as opposed to dual-tree search.
- single_sample_limit (int): The limit on the maximum number of samples (and hence the largest node you can approximate). Default value 20.
- tau (float): The allowed rank-error in terms of the percentile of the data. Default value 5.
- tree_type (string): Type of tree to use: 'kd', 'ub', 'cover', 'r', 'x', 'r-star', 'hilbert-r', 'r-plus', 'r-plus-plus', 'oct'. Default value kd.
- verbose (bool): Display informational messages and the full list of parameters and timers at the end of execution.

## output options

The return value from the binding is a dict containing the following elements:

- distances (numpy matrix, float dtype): Matrix to output distances into.
- neighbors (numpy matrix, int dtype): Matrix to output neighbors into.
- output_model (mlpack.RANNModelType): If specified, the kNN model will be output here.