.TH "mlpack::nca::SoftmaxErrorFunction< MetricType >" 3 "Tue Sep 9 2014" "Version 1.0.10" "MLPACK" \" -*- nroff -*-
.ad l
.nh
.SH NAME
mlpack::nca::SoftmaxErrorFunction< MetricType > \- 
.PP
The 'softmax' stochastic neighbor assignment probability function\&.  

.SH SYNOPSIS
.br
.PP
.SS "Public Member Functions"

.in +1c
.ti -1c
.RI "\fBSoftmaxErrorFunction\fP (const arma::mat &\fBdataset\fP, const arma::Col< size_t > &\fBlabels\fP, MetricType \fBmetric\fP=MetricType())"
.br
.RI "\fIInitialize with the given kernel; useful when the kernel has some state to store, which is set elsewhere\&. \fP"
.ti -1c
.RI "double \fBEvaluate\fP (const arma::mat &covariance)"
.br
.RI "\fIEvaluate the softmax function for the given covariance matrix\&. \fP"
.ti -1c
.RI "double \fBEvaluate\fP (const arma::mat &covariance, const size_t i)"
.br
.RI "\fIEvaluate the softmax objective function for the given covariance matrix on only one point of the dataset\&. \fP"
.ti -1c
.RI "const arma::mat \fBGetInitialPoint\fP () const "
.br
.RI "\fIGet the initial point\&. \fP"
.ti -1c
.RI "void \fBGradient\fP (const arma::mat &covariance, arma::mat &gradient)"
.br
.RI "\fIEvaluate the gradient of the softmax function for the given covariance matrix\&. \fP"
.ti -1c
.RI "void \fBGradient\fP (const arma::mat &covariance, const size_t i, arma::mat &gradient)"
.br
.RI "\fIEvaluate the gradient of the softmax function for the given covariance matrix on only one point of the dataset\&. \fP"
.ti -1c
.RI "size_t \fBNumFunctions\fP () const "
.br
.RI "\fIGet the number of functions the objective function can be decomposed into\&. \fP"
.ti -1c
.RI "std::string \fBToString\fP () const "
.br
.in -1c
.SS "Private Member Functions"

.in +1c
.ti -1c
.RI "void \fBPrecalculate\fP (const arma::mat &coordinates)"
.br
.RI "\fIPrecalculate the denominators and numerators that will make up the p_ij, but only if the coordinates matrix is different than the last coordinates the \fBPrecalculate()\fP method was run with\&. \fP"
.in -1c
.SS "Private Attributes"

.in +1c
.ti -1c
.RI "const arma::mat & \fBdataset\fP"
.br
.RI "\fIThe dataset\&. \fP"
.ti -1c
.RI "arma::vec \fBdenominators\fP"
.br
.RI "\fIHolds denominators for calculation of p_ij, for the non-separable \fBEvaluate()\fP and \fBGradient()\fP\&. \fP"
.ti -1c
.RI "const arma::Col< size_t > & \fBlabels\fP"
.br
.RI "\fILabels for each point in the dataset\&. \fP"
.ti -1c
.RI "arma::mat \fBlastCoordinates\fP"
.br
.RI "\fILast coordinates\&. Used for the non-separable \fBEvaluate()\fP and \fBGradient()\fP\&. \fP"
.ti -1c
.RI "MetricType \fBmetric\fP"
.br
.RI "\fIThe instantiated metric\&. \fP"
.ti -1c
.RI "arma::vec \fBp\fP"
.br
.RI "\fIHolds calculated p_i, for the non-separable \fBEvaluate()\fP and \fBGradient()\fP\&. \fP"
.ti -1c
.RI "bool \fBprecalculated\fP"
.br
.RI "\fIFalse if nothing has ever been precalculated (only at construction time)\&. \fP"
.ti -1c
.RI "arma::mat \fBstretchedDataset\fP"
.br
.RI "\fIStretched dataset\&. Kept internal to avoid memory reallocations\&. \fP"
.in -1c
.SH "Detailed Description"
.PP 

.SS "template<typename MetricType = metric::SquaredEuclideanDistance>class mlpack::nca::SoftmaxErrorFunction< MetricType >"
The 'softmax' stochastic neighbor assignment probability function\&. 

The actual function is
.PP
p_ij = (exp(-|| A x_i - A x_j || ^ 2)) / (sum_{k != i} (exp(-|| A x_i - A x_k || ^ 2)))
.PP
where x_n represents a point and A is the current scaling matrix\&.
.PP
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 \fBNCA\fP\&. However, that is probably the best way to use this class\&.
.PP
In addition to the standard \fBEvaluate()\fP and \fBGradient()\fP functions which MLPACK optimizers use, overloads of \fBEvaluate()\fP and \fBGradient()\fP are given which only operate on one point in the dataset\&. This is useful for optimizers like stochastic gradient descent (see \fBmlpack::optimization::SGD\fP)\&. 
.PP
Definition at line 52 of file nca_softmax_error_function\&.hpp\&.
.SH "Constructor & Destructor Documentation"
.PP 
.SS "template<typename MetricType  = metric::SquaredEuclideanDistance> \fBmlpack::nca::SoftmaxErrorFunction\fP< MetricType >::\fBSoftmaxErrorFunction\fP (const arma::mat &dataset, const arma::Col< size_t > &labels, MetricTypemetric = \fCMetricType()\fP)"

.PP
Initialize with the given kernel; useful when the kernel has some state to store, which is set elsewhere\&. If no kernel is given, an empty kernel is used; this way, you can call the constructor with no arguments\&. A reference to the dataset we will be optimizing over is also required\&.
.PP
\fBParameters:\fP
.RS 4
\fIdataset\fP Matrix containing the dataset\&. 
.br
\fIlabels\fP Vector of class labels for each point in the dataset\&. 
.br
\fIkernel\fP Instantiated kernel (optional)\&. 
.RE
.PP

.SH "Member Function Documentation"
.PP 
.SS "template<typename MetricType  = metric::SquaredEuclideanDistance> double \fBmlpack::nca::SoftmaxErrorFunction\fP< MetricType >::Evaluate (const arma::mat &covariance)"

.PP
Evaluate the softmax function for the given covariance matrix\&. This is the non-separable implementation, where the objective function is not decomposed into the sum of several objective functions\&.
.PP
\fBParameters:\fP
.RS 4
\fIcovariance\fP Covariance matrix of Mahalanobis distance\&. 
.RE
.PP

.SS "template<typename MetricType  = metric::SquaredEuclideanDistance> double \fBmlpack::nca::SoftmaxErrorFunction\fP< MetricType >::Evaluate (const arma::mat &covariance, const size_ti)"

.PP
Evaluate the softmax objective function for the given covariance matrix on only one 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\&.
.PP
\fBParameters:\fP
.RS 4
\fIcovariance\fP Covariance matrix of Mahalanobis distance\&. 
.br
\fIi\fP Index of point to use for objective function\&. 
.RE
.PP

.SS "template<typename MetricType  = metric::SquaredEuclideanDistance> const arma::mat \fBmlpack::nca::SoftmaxErrorFunction\fP< MetricType >::GetInitialPoint () const"

.PP
Get the initial point\&. 
.SS "template<typename MetricType  = metric::SquaredEuclideanDistance> void \fBmlpack::nca::SoftmaxErrorFunction\fP< MetricType >::Gradient (const arma::mat &covariance, arma::mat &gradient)"

.PP
Evaluate the gradient of the softmax function for the given covariance matrix\&. This is the non-separable implementation, where the objective function is not decomposed into the sum of several objective functions\&.
.PP
\fBParameters:\fP
.RS 4
\fIcovariance\fP Covariance matrix of Mahalanobis distance\&. 
.br
\fIgradient\fP Matrix to store the calculated gradient in\&. 
.RE
.PP

.SS "template<typename MetricType  = metric::SquaredEuclideanDistance> void \fBmlpack::nca::SoftmaxErrorFunction\fP< MetricType >::Gradient (const arma::mat &covariance, const size_ti, arma::mat &gradient)"

.PP
Evaluate the gradient of the softmax function for the given covariance matrix on only one 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\&.
.PP
\fBParameters:\fP
.RS 4
\fIcovariance\fP Covariance matrix of Mahalanobis distance\&. 
.br
\fIi\fP Index of point to use for objective function\&. 
.br
\fIgradient\fP Matrix to store the calculated gradient in\&. 
.RE
.PP

.SS "template<typename MetricType  = metric::SquaredEuclideanDistance> size_t \fBmlpack::nca::SoftmaxErrorFunction\fP< MetricType >::NumFunctions () const\fC [inline]\fP"

.PP
Get the number of functions the objective function can be decomposed into\&. This is just the number of points in the dataset\&. 
.PP
Definition at line 124 of file nca_softmax_error_function\&.hpp\&.
.SS "template<typename MetricType  = metric::SquaredEuclideanDistance> void \fBmlpack::nca::SoftmaxErrorFunction\fP< MetricType >::Precalculate (const arma::mat &coordinates)\fC [private]\fP"

.PP
Precalculate the denominators and numerators that will make up the p_ij, but only if the coordinates matrix is different than the last coordinates the \fBPrecalculate()\fP method was run with\&. This method is only called by the non-separable \fBEvaluate()\fP and \fBGradient()\fP\&.
.PP
This will update last_coordinates_ and stretched_dataset_, and also calculate the p_i and denominators_ which are used in the calculation of p_i or p_ij\&. The calculation will be O((n * (n + 1)) / 2), which is not great\&.
.PP
\fBParameters:\fP
.RS 4
\fIcoordinates\fP Coordinates matrix to use for precalculation\&. 
.RE
.PP

.SS "template<typename MetricType  = metric::SquaredEuclideanDistance> std::string \fBmlpack::nca::SoftmaxErrorFunction\fP< MetricType >::ToString () const"

.SH "Member Data Documentation"
.PP 
.SS "template<typename MetricType  = metric::SquaredEuclideanDistance> const arma::mat& \fBmlpack::nca::SoftmaxErrorFunction\fP< MetricType >::dataset\fC [private]\fP"

.PP
The dataset\&. 
.PP
Definition at line 131 of file nca_softmax_error_function\&.hpp\&.
.SS "template<typename MetricType  = metric::SquaredEuclideanDistance> arma::vec \fBmlpack::nca::SoftmaxErrorFunction\fP< MetricType >::denominators\fC [private]\fP"

.PP
Holds denominators for calculation of p_ij, for the non-separable \fBEvaluate()\fP and \fBGradient()\fP\&. 
.PP
Definition at line 146 of file nca_softmax_error_function\&.hpp\&.
.SS "template<typename MetricType  = metric::SquaredEuclideanDistance> const arma::Col<size_t>& \fBmlpack::nca::SoftmaxErrorFunction\fP< MetricType >::labels\fC [private]\fP"

.PP
Labels for each point in the dataset\&. 
.PP
Definition at line 133 of file nca_softmax_error_function\&.hpp\&.
.SS "template<typename MetricType  = metric::SquaredEuclideanDistance> arma::mat \fBmlpack::nca::SoftmaxErrorFunction\fP< MetricType >::lastCoordinates\fC [private]\fP"

.PP
Last coordinates\&. Used for the non-separable \fBEvaluate()\fP and \fBGradient()\fP\&. 
.PP
Definition at line 139 of file nca_softmax_error_function\&.hpp\&.
.SS "template<typename MetricType  = metric::SquaredEuclideanDistance> MetricType \fBmlpack::nca::SoftmaxErrorFunction\fP< MetricType >::metric\fC [private]\fP"

.PP
The instantiated metric\&. 
.PP
Definition at line 136 of file nca_softmax_error_function\&.hpp\&.
.SS "template<typename MetricType  = metric::SquaredEuclideanDistance> arma::vec \fBmlpack::nca::SoftmaxErrorFunction\fP< MetricType >::p\fC [private]\fP"

.PP
Holds calculated p_i, for the non-separable \fBEvaluate()\fP and \fBGradient()\fP\&. 
.PP
Definition at line 143 of file nca_softmax_error_function\&.hpp\&.
.SS "template<typename MetricType  = metric::SquaredEuclideanDistance> bool \fBmlpack::nca::SoftmaxErrorFunction\fP< MetricType >::precalculated\fC [private]\fP"

.PP
False if nothing has ever been precalculated (only at construction time)\&. 
.PP
Definition at line 149 of file nca_softmax_error_function\&.hpp\&.
.SS "template<typename MetricType  = metric::SquaredEuclideanDistance> arma::mat \fBmlpack::nca::SoftmaxErrorFunction\fP< MetricType >::stretchedDataset\fC [private]\fP"

.PP
Stretched dataset\&. Kept internal to avoid memory reallocations\&. 
.PP
Definition at line 141 of file nca_softmax_error_function\&.hpp\&.

.SH "Author"
.PP 
Generated automatically by Doxygen for MLPACK from the source code\&.