LMNNFunction< MetricType > Class Template Reference

The Large Margin Nearest Neighbors function. More...

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...

 
const arma::mat & Dataset () const
 Return the dataset passed into the constructor. 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
>
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. 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...

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

 
size_t & K ()
 Modify the value of k. More...

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

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

 
size_t & Range ()
 Modify the value of k. More...

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

 
double & Regularization ()
 Modify the regularization value. More...

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

 

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).

Definition at line 46 of file lmnn_function.hpp.

Constructor & Destructor Documentation

◆ LMNNFunction()

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
datasetInput dataset.
labelsInput dataset labels.
kNumber of target neighbors to be used.
regularizationRegularization value.
rangeRange after which impostors need to be recalculated.
metricType of metric used for computation.

Member Function Documentation

◆ Dataset()

const arma::mat& Dataset ( ) const
inline

Return the dataset passed into the constructor.

Definition at line 175 of file lmnn_function.hpp.

◆ Evaluate() [1/2]

double Evaluate ( const arma::mat &  transformation)

Evaluate the LMNN function for the given transformation matrix.

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

Parameters
transformationTransformation matrix of Mahalanobis distance.

◆ Evaluate() [2/2]

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.

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
transformationTransformation matrix of Mahalanobis distance.
beginIndex of the initial point to use for objective function.
batchSizeNumber of points to use for objective function.

◆ EvaluateWithGradient() [1/2]

double EvaluateWithGradient ( const arma::mat &  transformation,
GradType &  gradient 
)

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

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

Template Parameters
GradTypeThe type of the gradient out-param.
Parameters
transformationTransformation matrix of Mahalanobis distance.
gradientMatrix to store the calculated gradient in.

◆ EvaluateWithGradient() [2/2]

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.

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
GradTypeThe type of the gradient out-param.
Parameters
transformationTransformation matrix of Mahalanobis distance.
beginIndex of the initial point to use for objective function.
gradientMatrix to store the calculated gradient in.
batchSizeNumber of points to use for objective function.

◆ GetInitialPoint()

const arma::mat& GetInitialPoint ( ) const
inline

Return the initial point for the optimization.

Definition at line 166 of file lmnn_function.hpp.

◆ Gradient() [1/2]

void Gradient ( const arma::mat &  transformation,
GradType &  gradient 
)

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

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

Template Parameters
GradTypeThe type of the gradient out-param.
Parameters
transformationTransformation matrix of Mahalanobis distance.
gradientMatrix to store the calculated gradient in.

◆ Gradient() [2/2]

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.

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
GradTypeThe type of the gradient out-param.
Parameters
transformationTransformation matrix of Mahalanobis distance.
beginIndex of the initial point to use for objective function.
gradientMatrix to store the calculated gradient in.
batchSizeNumber of points to use for objective function.

◆ K() [1/2]

const size_t& K ( ) const
inline

Access the value of k.

Definition at line 183 of file lmnn_function.hpp.

◆ K() [2/2]

size_t& K ( )
inline

Modify the value of k.

Definition at line 185 of file lmnn_function.hpp.

◆ NumFunctions()

size_t 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.

Definition at line 172 of file lmnn_function.hpp.

◆ Range() [1/2]

const size_t& Range ( ) const
inline

Access the value of range.

Definition at line 188 of file lmnn_function.hpp.

◆ Range() [2/2]

size_t& Range ( )
inline

Modify the value of k.

Definition at line 190 of file lmnn_function.hpp.

◆ Regularization() [1/2]

const double& Regularization ( ) const
inline

Access the regularization value.

Definition at line 178 of file lmnn_function.hpp.

◆ Regularization() [2/2]

double& Regularization ( )
inline

Modify the regularization value.

Definition at line 180 of file lmnn_function.hpp.

◆ Shuffle()

void Shuffle ( )

Shuffle the points in the dataset.

This may be used by optimizers.


The documentation for this class was generated from the following file:
  • /home/jenkins-mlpack/mlpack.org/_src/mlpack-git/src/mlpack/methods/lmnn/lmnn_function.hpp