The Large Margin Nearest Neighbors function. More...

#include <lmnn_function.hpp>

Public Member Functions
	LMNNFunction (const arma::mat &dataset, const arma::Row< size_t > &labels, size_t k, double regularization, size_t range, MetricType metric=MetricType())
	Constructor for LMNNFunction class. More...

void	Shuffle ()
	Shuffle the points in the dataset. More...

double	Evaluate (const arma::mat &transformation)
	Evaluate the LMNN function for the given transformation matrix. More...

double	Evaluate (const arma::mat &transformation, const size_t begin, const size_t batchSize=1)
	Evaluate the LMNN objective function for the given transformation matrix on the given batch size from a given inital point of the dataset. More...

template<typename GradType >
void	Gradient (const arma::mat &transformation, GradType &gradient)
	Evaluate the gradient of the LMNN function for the given transformation matrix. More...

template<typename GradType >
void	Gradient (const arma::mat &transformation, const size_t begin, GradType &gradient, const size_t batchSize=1)
	Evaluate the gradient of the LMNN function for the given transformation matrix on the given batch size, from a given initial point of the dataset. More...

template<typename GradType >
double	EvaluateWithGradient (const arma::mat &transformation, GradType &gradient)
	Evaluate the LMNN objective function together with gradient for the given transformation matrix. More...

template<typename GradType >
double	EvaluateWithGradient (const arma::mat &transformation, const size_t begin, GradType &gradient, const size_t batchSize=1)
	Evaluate the LMNN objective function together with gradient for the given transformation matrix on the given batch size, from a given initial point of the dataset. More...

const arma::mat &	GetInitialPoint () const
	Return the initial point for the optimization.

size_t	NumFunctions () const
	Get the number of functions the objective function can be decomposed into. More...

const arma::mat &	Dataset () const
	Return the dataset passed into the constructor.

const double &	Regularization () const
	Access the regularization value.

double &	Regularization ()
	Modify the regularization value.

const size_t &	K () const
	Access the value of k.

size_t &	K ()
	Modify the value of k.

const size_t &	Range () const
	Access the value of range.

size_t &	Range ()
	Modify the value of k.

Detailed Description

template<typename MetricType = metric::SquaredEuclideanDistance>
class mlpack::lmnn::LMNNFunction< MetricType >

The Large Margin Nearest Neighbors function.

The actual function is

\( \epsilon(M) = \sum_{ij}\eta_{ij}|| L x_i - L x_j ||^2 + c\sum_{ijl}\eta_{ij}(1-y_{il})[1 + || L x_i - L x_j ||^2 - || L x_i - L x_l ||^2)]_{+} \)

where x_n represents a point and A is the current scaling matrix.

This class is more flexible than the original paper, allowing an arbitrary metric function to be used in place of || A x_i - A x_j ||^2, meaning that the squared Euclidean distance is not the only allowed metric for LMNN. However, that is probably the best way to use this class.

In addition to the standard Evaluate() and Gradient() functions which mlpack optimizers use, overloads of Evaluate() and Gradient() are given which only operate on one point in the dataset. This is useful for optimizers like stochastic gradient descent (see ens::SGD).

Constructor & Destructor Documentation

◆ LMNNFunction()

template<typename MetricType >

mlpack::lmnn::LMNNFunction< MetricType >::LMNNFunction	(	const arma::mat &	dataset,
		const arma::Row< size_t > &	labels,
		size_t	k,
		double	regularization,
		size_t	range,
		MetricType	metric = `MetricType()`
	)

Constructor for LMNNFunction class.

Parameters

dataset	Input dataset.
labels	Input dataset labels.
k	Number of target neighbors to be used.
regularization	Regularization value.
range	Range after which impostors need to be recalculated.
metric	Type of metric used for computation.

Member Function Documentation

◆ Evaluate() [1/2]

template<typename MetricType >

double mlpack::lmnn::LMNNFunction< MetricType >::Evaluate ( const arma::mat & transformation )

Evaluate the LMNN function for the given transformation matrix.

Evaluate cost over whole dataset.

This is the non-separable implementation, where the objective function is not decomposed into the sum of several objective functions.

Parameters

transformation Transformation matrix of Mahalanobis distance.

◆ Evaluate() [2/2]

template<typename MetricType >

double mlpack::lmnn::LMNNFunction< MetricType >::Evaluate	(	const arma::mat &	transformation,
		const size_t	begin,
		const size_t	batchSize = `1`
	)

Evaluate the LMNN objective function for the given transformation matrix on the given batch size from a given inital point of the dataset.

Calculate cost over batches.

This is the separable implementation, where the objective function is decomposed into the sum of many objective functions, and here, only one of those constituent objective functions is returned.

Parameters

transformation	Transformation matrix of Mahalanobis distance.
begin	Index of the initial point to use for objective function.
batchSize	Number of points to use for objective function.

◆ EvaluateWithGradient() [1/2]

template<typename MetricType >

template<typename GradType >

double mlpack::lmnn::LMNNFunction< MetricType >::EvaluateWithGradient	(	const arma::mat &	transformation,
		GradType &	gradient
	)

Evaluate the LMNN objective function together with gradient for the given transformation matrix.

Compute cost & gradient over whole dataset.

This is the non-separable implementation, where the objective function is not decomposed into the sum of several objective functions.

Template Parameters

GradType The type of the gradient out-param.

Parameters

transformation	Transformation matrix of Mahalanobis distance.
gradient	Matrix to store the calculated gradient in.

◆ EvaluateWithGradient() [2/2]

template<typename MetricType >

template<typename GradType >

double mlpack::lmnn::LMNNFunction< MetricType >::EvaluateWithGradient	(	const arma::mat &	transformation,
		const size_t	begin,
		GradType &	gradient,
		const size_t	batchSize = `1`
	)

Evaluate the LMNN objective function together with gradient for the given transformation matrix on the given batch size, from a given initial point of the dataset.

Compute cost & gradient over a batch of data points.

This is the separable implementation, where the objective function is decomposed into the sum of many objective functions, and here, only one of those constituent objective functions is returned. The type of the gradient parameter is a template argument to allow the computation of a sparse gradient.

Template Parameters

GradType The type of the gradient out-param.

Parameters

transformation	Transformation matrix of Mahalanobis distance.
begin	Index of the initial point to use for objective function.
gradient	Matrix to store the calculated gradient in.
batchSize	Number of points to use for objective function.

◆ Gradient() [1/2]

template<typename MetricType >

template<typename GradType >

void mlpack::lmnn::LMNNFunction< MetricType >::Gradient	(	const arma::mat &	transformation,
		GradType &	gradient
	)

Evaluate the gradient of the LMNN function for the given transformation matrix.

Compute gradient over whole dataset.

This is the non-separable implementation, where the objective function is not decomposed into the sum of several objective functions.

Template Parameters

GradType The type of the gradient out-param.

Parameters

transformation	Transformation matrix of Mahalanobis distance.
gradient	Matrix to store the calculated gradient in.

◆ Gradient() [2/2]

template<typename MetricType >

template<typename GradType >

void mlpack::lmnn::LMNNFunction< MetricType >::Gradient	(	const arma::mat &	transformation,
		const size_t	begin,
		GradType &	gradient,
		const size_t	batchSize = `1`
	)

Evaluate the gradient of the LMNN function for the given transformation matrix on the given batch size, from a given initial point of the dataset.

Compute gradient over a batch of data points.

This is the separable implementation, where the objective function is decomposed into the sum of many objective functions, and here, only one of those constituent objective functions is returned. The type of the gradient parameter is a template argument to allow the computation of a sparse gradient.

Template Parameters

GradType The type of the gradient out-param.

Parameters

transformation	Transformation matrix of Mahalanobis distance.
begin	Index of the initial point to use for objective function.
gradient	Matrix to store the calculated gradient in.
batchSize	Number of points to use for objective function.

◆ NumFunctions()

template<typename MetricType = metric::SquaredEuclideanDistance>

size_t mlpack::lmnn::LMNNFunction< MetricType >::NumFunctions ( ) const

inline

Get the number of functions the objective function can be decomposed into.

This is just the number of points in the dataset.

◆ Shuffle()

template<typename MetricType >

void mlpack::lmnn::LMNNFunction< MetricType >::Shuffle ( )

Shuffle the points in the dataset.

Shuffle the dataset.

This may be used by optimizers.

The documentation for this class was generated from the following files:

src/mlpack/methods/lmnn/lmnn_function.hpp
src/mlpack/methods/lmnn/lmnn_function_impl.hpp

Public Member Functions

Detailed Description

template<typename MetricType = metric::SquaredEuclideanDistance> class mlpack::lmnn::LMNNFunction< MetricType >

Constructor & Destructor Documentation

◆ LMNNFunction()

Member Function Documentation

◆ Evaluate() [1/2]

◆ Evaluate() [2/2]

◆ EvaluateWithGradient() [1/2]

◆ EvaluateWithGradient() [2/2]

◆ Gradient() [1/2]

◆ Gradient() [2/2]

◆ NumFunctions()

◆ Shuffle()

template<typename MetricType = metric::SquaredEuclideanDistance>
class mlpack::lmnn::LMNNFunction< MetricType >