lmnn_main.cpp File Reference

#include <mlpack/prereqs.hpp>
#include <mlpack/core/util/io.hpp>
#include <mlpack/core/data/normalize_labels.hpp>
#include <mlpack/core/util/mlpack_main.hpp>
#include <mlpack/core/math/random.hpp>
#include <mlpack/core/metrics/lmetric.hpp>
#include <mlpack/methods/neighbor_search/neighbor_search.hpp>
#include "lmnn.hpp"
#include <ensmallen.hpp>

Include dependency graph for lmnn_main.cpp:

This graph shows which files directly or indirectly include this file:

Functions
	BINDING_NAME ("Large Margin Nearest Neighbors (LMNN)")
	BINDING_SHORT_DESC ("An implementation of Large Margin Nearest Neighbors (LMNN), a distance " "learning technique. Given a labeled dataset, this learns a transformation" " of the data that improves k-nearest-neighbor performance; this can be " "useful as a preprocessing step.")
	BINDING_LONG_DESC ("This program implements Large Margin Nearest Neighbors, a distance " "learning technique. The method seeks to improve k-nearest-neighbor " "classification on a dataset. The method employes the strategy of " "reducing distance between similar labeled data points (a.k.a target " "neighbors) and increasing distance between differently labeled points" " (a.k.a impostors) using standard optimization techniques over the " "gradient of the distance between data points." "\" "To work, this algorithm needs labeled data. It can be given as the last " "row of the input dataset (specified with "+PRINT_PARAM_STRING("input")+"), or alternatively as a separate matrix (specified with "+PRINT_PARAM_STRING("labels")+"). Additionally, a starting point for " "optimization (specified with "+PRINT_PARAM_STRING("distance")+"can be given, having (r x d) dimensionality. Here r should satisfy " "1 <= r <= d, Consequently a Low-Rank matrix will be optimized. " "Alternatively, Low-Rank distance can be learned by specifying the "+PRINT_PARAM_STRING("rank")+"parameter (A Low-Rank matrix with uniformly " "distributed values will be used as initial learning point). " "\" "The program also requires number of targets neighbors to work with ( " "specified with "+PRINT_PARAM_STRING("k")+"), A " "regularization parameter can also be passed, It acts as a trade of " "between the pulling and pushing terms (specified with "+PRINT_PARAM_STRING("regularization")+"), In addition, this " "implementation of LMNN includes a parameter to decide the interval " "after which impostors must be re-calculated (specified with "+PRINT_PARAM_STRING("range")+")." "\" "Output can either be the learned distance matrix (specified with "+PRINT_PARAM_STRING("output")+"), or the transformed dataset " " (specified with "+PRINT_PARAM_STRING("transformed_data")+"), or " "both. Additionally mean-centered dataset (specified with "+PRINT_PARAM_STRING("centered_data")+") can be accessed given " "mean-centering (specified with "+PRINT_PARAM_STRING("center")+") is performed on the dataset. Accuracy on initial dataset and final " "transformed dataset can be printed by specifying the "+PRINT_PARAM_STRING("print_accuracy")+"parameter. " "\" "This implementation of LMNN uses AdaGrad, BigBatch_SGD, stochastic " "gradient descent, mini-batch stochastic gradient descent, or the L_BFGS " "optimizer. " "\" "AdaGrad, specified by the value 'adagrad' for the parameter "+PRINT_PARAM_STRING("optimizer")+", uses maximum of past squared " "gradients. It primarily on six parameters: the step size (specified " "with "+PRINT_PARAM_STRING("step_size")+"), the batch size (specified " "with "+PRINT_PARAM_STRING("batch_size")+"), the maximum number of " "passes (specified with "+PRINT_PARAM_STRING("passes")+"). In" "addition, a normalized starting point can be used by specifying the "+PRINT_PARAM_STRING("normalize")+" parameter. " "\" "BigBatch_SGD, specified by the value 'bbsgd' for the parameter "+PRINT_PARAM_STRING("optimizer")+", depends primarily on four parameters: " "the step size (specified with "+PRINT_PARAM_STRING("step_size")+"), " "the batch size (specified with "+PRINT_PARAM_STRING("batch_size")+"), " "the maximum number of passes (specified with "+PRINT_PARAM_STRING("passes")+"). In addition, a normalized starting " "point can be used by specifying the "+PRINT_PARAM_STRING("normalize")+" parameter. " "\" "Stochastic gradient descent, specified by the value 'sgd' for the " "parameter "+PRINT_PARAM_STRING("optimizer")+", depends " "primarily on three parameters: the step size (specified with "+PRINT_PARAM_STRING("step_size")+"), the batch size (specified with "+PRINT_PARAM_STRING("batch_size")+"), and the maximum number of passes " "(specified with "+PRINT_PARAM_STRING("passes")+"). In " "addition, a normalized starting point can be used by specifying the "+PRINT_PARAM_STRING("normalize")+" parameter. Furthermore, "+"mean-centering can be performed on the dataset by specifying the "+PRINT_PARAM_STRING("center")+"parameter. " "\" "The L-BFGS optimizer, specified by the value 'lbfgs' for the parameter "+PRINT_PARAM_STRING("optimizer")+", uses a back-tracking line search " "algorithm to minimize a function. The following parameters are used by " "L-BFGS: "+PRINT_PARAM_STRING("max_iterations")+", "+PRINT_PARAM_STRING("tolerance")+"(the optimization is terminated when the gradient norm is below this " "value). For more details on the L-BFGS optimizer, consult either the " "mlpack L-BFGS documentation (in lbfgs.hpp) or the vast set of published " "literature on L-BFGS. In addition, a normalized starting point can be " "used by specifying the "+PRINT_PARAM_STRING("normalize")+" parameter." "\" "By default, the AMSGrad optimizer is used.")
	BINDING_EXAMPLE ("Example - Let's say we want to learn distance on iris dataset with " "number of targets as 3 using BigBatch_SGD optimizer. A simple call for " "the same will look like: " "\"+PRINT_CALL("mlpack_lmnn", "input", "iris", "labels", "iris_labels", "k", 3, "optimizer", "bbsgd", "output", "output")+"\" "An another program call making use of range & regularization parameter " "with dataset having labels as last column can be made as: " "\"+PRINT_CALL("mlpack_lmnn", "input", "letter_recognition", "k", 5, "range", 10, "regularization", 0.4, "output", "output"))
	BINDING_SEE_ALSO ("@nca", "#nca")
	BINDING_SEE_ALSO ("Large margin nearest neighbor on Wikipedia", "https://en.wikipedia.org/wiki/Large_margin_nearest_neighbor")
	BINDING_SEE_ALSO ("Distance metric learning for large margin nearest neighbor " "classification (pdf)", "http://papers.nips.cc/paper/2795-distance-" "metric-learning-for-large-margin-nearest-neighbor-classification.pdf")
	BINDING_SEE_ALSO ("mlpack::lmnn::LMNN C++ class documentation", "@doxygen/classmlpack_1_1lmnn_1_1LMNN.html")
	PARAM_MATRIX_IN_REQ ("input", "Input dataset to run LMNN on.", "i")
	PARAM_MATRIX_IN ("distance", "Initial distance matrix to be used as " "starting point", "d")
	PARAM_UROW_IN ("labels", "Labels for input dataset.", "l")
	PARAM_INT_IN ("k", "Number of target neighbors to use for each " "datapoint.", "k", 1)
	PARAM_MATRIX_OUT ("output", "Output matrix for learned distance matrix.", "o")
	PARAM_MATRIX_OUT ("transformed_data", "Output matrix for transformed dataset.", "D")
	PARAM_MATRIX_OUT ("centered_data", "Output matrix for mean-centered dataset.", "c")
	PARAM_FLAG ("print_accuracy", "Print accuracies on initial and transformed " "dataset", "P")
	PARAM_STRING_IN ("optimizer", "Optimizer to use; 'amsgrad', 'bbsgd', 'sgd', or " "'lbfgs'.", "O", "amsgrad")
	PARAM_DOUBLE_IN ("regularization", "Regularization for LMNN objective function ", "r", 0.5)
	PARAM_INT_IN ("rank", "Rank of distance matrix to be optimized. ", "A", 0)
	PARAM_FLAG ("normalize", "Use a normalized starting point for optimization. It" "is useful for when points are far apart, or when SGD is returning NaN.", "N")
	PARAM_FLAG ("center", "Perform mean-centering on the dataset. It is useful " "when the centroid of the data is far from the origin.", "C")
	PARAM_INT_IN ("passes", "Maximum number of full passes over dataset for " "AMSGrad, BB_SGD and SGD.", "p", 50)
	PARAM_INT_IN ("max_iterations", "Maximum number of iterations for " "L-BFGS (0 indicates no limit).", "n", 100000)
	PARAM_DOUBLE_IN ("tolerance", "Maximum tolerance for termination of AMSGrad, " "BB_SGD, SGD or L-BFGS.", "t", 1e-7)
	PARAM_DOUBLE_IN ("step_size", "Step size for AMSGrad, BB_SGD and SGD (alpha).", "a", 0.01)
	PARAM_FLAG ("linear_scan", "Don't shuffle the order in which data points are " "visited for SGD or mini-batch SGD.", "L")
	PARAM_INT_IN ("batch_size", "Batch size for mini-batch SGD.", "b", 50)
	PARAM_INT_IN ("range", "Number of iterations after which impostors needs to be " "recalculated", "R", 1)
	PARAM_INT_IN ("seed", "Random seed. If 0, 'std::time(NULL)' is used.", "s", 0)
double	KNNAccuracy (const arma::mat &dataset, const arma::Row< size_t > &labels, const size_t k)

Detailed Description

Author

Manish Kumar

Executable for Large Margin Nearest Neighbors.

mlpack is free software; you may redistribute it and/or modify it under the terms of the 3-clause BSD license. You should have received a copy of the 3-clause BSD license along with mlpack. If not, see http://www.opensource.org/licenses/BSD-3-Clause for more information.