RelationalNeuralGas (Relational Neural Gas 1.0.0 API)

java.lang.Object
- de.citec.ml.rng.RelationalNeuralGas

```
public final class RelationalNeuralGas
extends Object
```
This class implements the batch relational neural gas algorithm, which tries to minimize the soft quantization error for prototypes to data points and anneals the softness over time until the algorithm converges to K-means. As such, relational neural gas can be seen as a proper and more robust generalization of (relational) K-means.

To be more precise, let x₁, ..., x_m be data points and w₁, ..., w_K be the prototypes of neural gas. Then, neural gas minimizes the error

E = Σ_i=1,...,m Σ_k=1,...,K h(k|i) · d(x_i, w_k)²

where h(k|i) is the assignment strength of data point i to prototype k. Neural gas models this assignment strength as

h(k|i) = exp(-r(k|i) / λ)

where r(k|i) is the rank of prototype k with respect to data point i, that is, the number of other prototypes which are closer to data point i than prototype w_k, and λ is a hyper-parameter which regulates the 'crispness' of the assignment. For λ = 0, every data point is assigned strictly to the closest prototype and to no other. In neural gas, λ starts at K/2 and is then annealed via the falling exponential equation

λ_t := λ₀ · (0.01 / λ₀)^{(t / T)}

where t is the current epoch and T is the overall number of epochs. So λ_T is exactly 0.01.

The special property of relational neural gas is that d(x_i, w_k) is not computed via the Euclidean distance but is computed indirectly. In particular, we assume that prototype w_k is given as a convex combination of the form

w_k = Σ_i=1,...,m α_{k, i} · x_i

and that we have a m x m matrix of pairwise distances D between all data points available. In This case, the distance between prototypes and data points is given as:

d(w_k, x_i)² = α_k · D(:, i)² - 0.5 · α_k · D² · α_k^T

where α_k is the vector of convex coefficients for prototype k and D(:, i)² is the i-th column of the squared distance matrix D².

Author:

Benjamin Paassen - bpaassen(at)techfak.uni-bielefeld.de

Method Summary

All Methods Static Methods Concrete Methods
Modifier and Type	Method and Description
`static int[]`	`classify(double[][] D, RNGModel model)` Classifies new data according to a given RNGModel.
`static int`	`classify(double[] d, RNGModel model)` Classifies a new data point according to a given RNGModel.
`static int[]`	`getAssignments(RNGModel model)` Returns the strict assignments of all data points handled in the given Relational Neural Gas model to prototypes.
`static int[][]`	`getClusterMembers(RNGModel model)` Returns an array with K entries, where each entry is another array containing the indices of all data points that have been assigned to the respective cluster/prototype.
`static int[]`	`getClusterMembers(RNGModel model, int k)` Returns the indices of all data points that have been assigned to the cluster/prototype with index k.
`static int[]`	`getClusterMembers(RNGModel model, int k, int[] assignments)` Returns the indices of all data points that have been assigned to the cluster/prototype with index k.
`static int[]`	`getExamplars(RNGModel model)` Returns an array with K entries, where entry k is the index of the data point which is closest to the relational prototype for cluster k.
`static double`	`getLambda(int t, int K, int T)` Returns the λ value for the current training epoch.
`static RNGErrorModel`	`train(double[][] D, int K)` Trains a relational neural gas model with K prototypes for the given data in terms of a m x m matrix of pairwise distances D, using 30 iterations of the RNG algorithm.
`static RNGErrorModel`	`train(double[][] D, int K, int T)` Trains a relational neural gas model with K prototypes for the given data in terms of a m x m matrix of pairwise distances D, using T iterations of the RNG algorithm.

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

- Method Detail
  - train
```
public static RNGErrorModel train(double[][] D,
                                  int K)
```
    Trains a relational neural gas model with K prototypes for the given data in terms of a m x m matrix of pairwise distances D, using 30 iterations of the RNG algorithm. The algorithm takes O(m · m · K) calculation steps.
    
    Parameters:
    
    D - a m x m distance matrix. Note that this matrix is required to be symmetric and have a zero diagonal.
    
    K - the number of prototypes for the relational neural gas model.
    
    Returns:
    
    a relational neural gas model.
  - train
```
public static RNGErrorModel train(double[][] D,
                                  int K,
                                  int T)
```
    Trains a relational neural gas model with K prototypes for the given data in terms of a m x m matrix of pairwise distances D, using T iterations of the RNG algorithm. The algorithm takes O(m · m · K · T) calculation steps.
    
    Parameters:
    
    D - a m x m distance matrix. Note that this matrix is required to be symmetric and have a zero diagonal.
    
    K - the number of prototypes for the relational neural gas model.
    
    T - the number of epochs used for training.
    
    Returns:
    
    a relational neural gas model.
  - getLambda
```
public static double getLambda(int t,
                               int K,
                               int T)
```
    Returns the λ value for the current training epoch. As recommended by Martinez et al. (1993; cited after Hasenfuss, 2009) we use an exponential decay (annealing) of λ with
    
    λ_t := λ₀ * (0.01 / λ₀)^(t / (T-1))
    
    where λ₀ is the number of prototypes divided by 2, t is the current epoch and T is the total number of epochs.
    
    Parameters:
    
    t - the current training epoch.
    
    K - the number of prototypes.
    
    T - the overall number of training epochs.
    
    Returns:
    
    the λ value for the current training epoch.
  - getAssignments
```
public static int[] getAssignments(RNGModel model)
```
    Returns the strict assignments of all data points handled in the given Relational Neural Gas model to prototypes. The assignments are computed by the minimum distance to prototypes. More formally, it returns a vector assignments where
    
    assignment[i] := argmin_k d(w_k , x_i)
    
    Parameters:
    
    model - an RNGModel.
    
    Returns:
    
    the strict assignments of all data points handled in the given Relational Neural Gas model to prototypes.
  - classify
```
public static int[] classify(double[][] D,
                             RNGModel model)
```
    Classifies new data according to a given RNGModel. In particular, assume that n new data points are given. Then, this method returns an n-dimensional array, where the j-th entry is the index of the cluster the j-th data point has been assigned to.
    
    Parameters:
    
    D - an n x m dimensional distance matrix containing the distances of the new data points to the training data points.
    
    model - model a RNGModel.
    
    Returns:
    
    an n-dimensional array, where the j-th entry is the index of the cluster the j-th data point has been assigned to.
  - classify
```
public static int classify(double[] d,
                           RNGModel model)
```
    Classifies a new data point according to a given RNGModel. In particular, this method returns the index of the cluster the new data point has been assigned to.
    
    Parameters:
    
    d - an m x 1 dimensional vector containing the distances of the new data point to all training data points.
    
    model - a RNGModel.
    
    Returns:
    
    an n-dimensional array, where the j-th entry is the index of the cluster the j-th data point has been assigned to.
  - getClusterMembers
```
public static int[][] getClusterMembers(RNGModel model)
```
    Returns an array with K entries, where each entry is another array containing the indices of all data points that have been assigned to the respective cluster/prototype. That is, entry k of the output array contains the set:
    
    { i | getAssignments(model)[i] == k}
    
    The returned collection lists the data point indices in ascending order.
    
    Parameters:
    
    model - a RNGModel.
    
    Returns:
    
    an array with K entries, where each entry is another array containing the indices of all data points that have been assigned to the respective cluster/prototype.
  - getClusterMembers
```
public static int[] getClusterMembers(RNGModel model,
                                      int k)
```
    Returns the indices of all data points that have been assigned to the cluster/prototype with index k. This is equivalent to the set
    
    { i | getAssignments(model)[i] == k}
    
    The returned collection lists the data point indices in ascending order.
    
    Parameters:
    
    model - a RNGModel.
    
    k - the index of a cluster/prototype.
    
    Returns:
    
    the indices of all data points that have been assigned to the cluster with index k.
  - getClusterMembers
```
public static int[] getClusterMembers(RNGModel model,
                                      int k,
                                      int[] assignments)
```
    Returns the indices of all data points that have been assigned to the cluster/prototype with index k. This is equivalent to the set
    
    { i | getAssignments(model)[i] == k}
    
    The returned collection lists the data point indices in ascending order.
    
    Parameters:
    
    model - a RNGModel.
    
    k - the index of a cluster/prototype.
    
    assignments - the assignments vector for the given model (result of "getAssignments").
    
    Returns:
    
    the indices of all data points that have been assigned to the cluster with index k.
  - getExamplars
```
public static int[] getExamplars(RNGModel model)
```
    Returns an array with K entries, where entry k is the index of the data point which is closest to the relational prototype for cluster k. More formally, entry k is:
    
    argmin_i d(w_k, x_i)
    
    Parameters:
    
    model - a RNGModel.
    
    Returns:
    
    an array with K entries, where entry k is the index of the data point which is closest to the relational prototype for cluster k.

Copyright (C) 2015-2017 Benjamin Paaßen, AG Machine Learning, Centre of Excellence Cognitive Interaction Technology (CITEC), University of Bielefeld, licensed under the GPL v. 3: https://gitlab.ub.uni-bielefeld.de/bpaassen/relational_neural_gas . This documentation is licensed under the conditions of CC-BY-SA 4.0: https://creativecommons.org/licenses/by-sa/4.0/

Class RelationalNeuralGas

Method Summary

Methods inherited from class java.lang.Object

Method Detail

train

train

getLambda

getAssignments

classify

classify

getClusterMembers

getClusterMembers

getClusterMembers

getExamplars