LargeMarginDimensionalityReduction (OpenIMAJ master project 1.3.10 API)

java.lang.Object
- org.openimaj.ml.linear.projection.LargeMarginDimensionalityReduction

```
public class LargeMarginDimensionalityReduction
extends Object
```
LargeMarginDimensionalityReduction is a technique to compress high dimensional features into a lower-dimension representation using a learned linear projection. Supervised learning is used to learn the projection such that the squared Euclidean distance between two low-dimensional vectors is less than a threshold if they correspond to the same object, or greater otherwise. In addition, it is imposed that this condition is satisfied with a margin of at least one.
In essence, the Euclidean distance in the low dimensional space produced by this technique can be seen as a low-rank Mahalanobis metric in the original space; the Mahalanobis matrix would have rank equal to the number of dimensions of the smaller space.
This class implements the technique using stochastic sub-gradient descent. As the objective function is not convex, initialisation is important, and initial conditions are generated by selecting the largest PCA dimensions, and then whitening the dimensions so they have equal magnitude. In addition, the projection matrix is not regularised explicitly; instead the algorithm is just stopped after a fixed number of iterations.

Author:

Jonathon Hare (jsh2@ecs.soton.ac.uk)

Field Summary

Fields
Modifier and Type Field and Description

protected double b

protected double bLearnRate

protected int ndims

protected Jama.Matrix W

protected double wLearnRate

Fields
Modifier and Type	Field and Description
`protected double`	`b`
`protected double`	`bLearnRate`
`protected int`	`ndims`
`protected Jama.Matrix`	`W`
`protected double`	`wLearnRate`

Constructor Summary

Constructors
Constructor and Description
`LargeMarginDimensionalityReduction(int ndims)` Construct with the given target dimensionality and default values for the other parameters (learning rate of 1.0 for W; learning rate of 0 for bias).
`LargeMarginDimensionalityReduction(int ndims, double wLearnRate, double bLearnRate)` Construct with the given target dimensionality learning rates.

Method Summary

All Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`boolean`	`classify(double[] phii, double[] phij)` Determine if two features are from the same class or different classes.
`double`	`getBias()` Get the bias, b
`Jama.Matrix`	`getTransform()` Get the transform matrix W
`void`	`initialise(double[][] datai, double[][] dataj, boolean[] same)` Initialise the LMDR with the given data in three parallel data arrays.
`double[]`	`project(double[] in)` Compute the low rank estimate of the given vector
`void`	`recomputeBias(double[][] datai, double[][] dataj, boolean[] same)`
`double`	`score(double[] phii, double[] phij)` Compute the matching score between a pair of (high dimensional) features.
`void`	`setBias(double d)`
`void`	`setTransform(Jama.Matrix proj)`
`boolean`	`step(double[] phii, double[] phij, boolean same)` Perform a single update step of the SGD optimisation.

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

- Field Detail
  - ndims
```
protected int ndims
```
  - wLearnRate
```
protected double wLearnRate
```
  - bLearnRate
```
protected double bLearnRate
```
  - W
```
protected Jama.Matrix W
```
  - b
```
protected double b
```
- Constructor Detail
  - LargeMarginDimensionalityReduction
```
public LargeMarginDimensionalityReduction(int ndims)
```
    Construct with the given target dimensionality and default values for the other parameters (learning rate of 1.0 for W; learning rate of 0 for bias).
    
    Parameters:
    
    ndims - target number of dimensions
  - LargeMarginDimensionalityReduction
```
public LargeMarginDimensionalityReduction(int ndims,
                                          double wLearnRate,
                                          double bLearnRate)
```
    Construct with the given target dimensionality learning rates.
    
    Parameters:
    
    ndims - target number of dimensions
    
    wLearnRate - learning rate for the transform matrix, W.
    
    bLearnRate - learning rate for the bias, b.
- Method Detail
  - initialise
```
public void initialise(double[][] datai,
                       double[][] dataj,
                       boolean[] same)
```
    Initialise the LMDR with the given data in three parallel data arrays. The first two arrays together store pairs of vectors, and the third array indicate whether the vectors in each pair represent the same class or different classes. All three arrays should obviously have the same length, and approximately equal numbers of true and false pairs.
    Internally, this method gathers together all the vectors and performs ThinSvdPrincipalComponentAnalysis to get a starting estimate for the transform matrix. The distance in the projected space between all true pairs and false pairs is computed and used to select an optimal initial threshold.
    
    Parameters:
    
    datai - array of the first vectors of the pairs
    
    dataj - array of the second vectors of the pairs
    
    same - array indicating where pairs are true (from the same class) or false (from different classes)
  - recomputeBias
```
public void recomputeBias(double[][] datai,
                          double[][] dataj,
                          boolean[] same)
```
  - step
```
public boolean step(double[] phii,
                    double[] phij,
                    boolean same)
```
    Perform a single update step of the SGD optimisation. Alternate calls to this method should swap between true and false pairs.
    
    Parameters:
    
    phii - first vector
    
    phij - second vector
    
    same - true if the vectors are from the same class; false otherwise
    
    Returns:
    
    true if the transform matrix was changed; false otherwise
  - getTransform
```
public Jama.Matrix getTransform()
```
    Get the transform matrix W
    
    Returns:
    
    the transform matrix
  - getBias
```
public double getBias()
```
    Get the bias, b
    
    Returns:
    
    the bias
  - score
```
public double score(double[] phii,
                    double[] phij)
```
    Compute the matching score between a pair of (high dimensional) features. Scores >=0 indicate a matching pair.
    
    Parameters:
    
    phii - first vector
    
    phij - second vector
    
    Returns:
    
    the matching score
  - classify
```
public boolean classify(double[] phii,
                        double[] phij)
```
    Determine if two features are from the same class or different classes.
    
    Parameters:
    
    phii - first vector
    
    phij - second vector
    
    Returns:
    
    the classification (true if same class; false if different)
  - project
```
public double[] project(double[] in)
```
    Compute the low rank estimate of the given vector
    
    Parameters:
    
    in - the vector
    
    Returns:
    
    the low-rank projection of the vector
  - setBias
```
public void setBias(double d)
```
  - setTransform
```
public void setTransform(Jama.Matrix proj)
```

Class LargeMarginDimensionalityReduction

Field Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

ndims

wLearnRate

bLearnRate

W

b

Constructor Detail

LargeMarginDimensionalityReduction

LargeMarginDimensionalityReduction

Method Detail

initialise

recomputeBias

step

getTransform

getBias

score

classify

project

setBias

setTransform