BaseFunction (S-Space Package 2.0.1 API)

java.lang.Object
- edu.ucla.sspace.clustering.criterion.BaseFunction

All Implemented Interfaces:

CriterionFunction

Direct Known Subclasses:

E1Function, G1Function, I1Function, I2Function
```
public abstract class BaseFunction
extends Object
implements CriterionFunction
```
This CriterionFunction implements the basic functionality needed for a majority of the functions available. It works by first gathering a handful of meta data for the data set, such as the cluster sizes, initial cluster assignments, and initial centroids. It then implements update and requires subclasses to implement functions for determining the change in the criterion score due to moving a data point.
Sub classes must implement getOldCentroidScore and getNewCentroidScore. The first function returns the score for the current datapoints cluster assignment when that data point is removed from the data point. The second function returns the score for an anternate cluster when the current data point is placed in that cluster.
This base class also provides two key methods for assisting with compute the above changes: modifiedMagnitudeSqrd and modifiedMagnitude. For both functions, the first method is cosidered to be the cluster centroid that is being modified and the second vector is the data point that is being added to the centroid, without actually affecting the cluster.

Author:

Keith Stevens

Field Summary

Fields
Modifier and Type	Field and Description
`protected int[]`	`assignments` The set of cluster assignments for each cluster.
`protected DoubleVector[]`	`centroids` The centroids representing each cluster.
`protected int[]`	`clusterSizes` The number of data points found in each cluster.
`protected double[]`	`costs` The cost computed for each cluster.
`protected List<DoubleVector>`	`matrix` The `Matrix` holding the data points.

Constructor Summary

Constructors
Constructor and Description

BaseFunction()
Constructs a new BaseFunction.

Constructors
Constructor and Description
`BaseFunction()` Constructs a new `BaseFunction`.

Method Summary

Methods
Modifier and Type	Method and Description
`int[]`	`assignments()` Returns the cluster assignment indices for each data point in the original matrix passed to {@link #setup(Matrix, int[] int) setup).
`DoubleVector[]`	`centroids()` Returns the final set of centroids computed for the dataset passed to `setup`.
`int[]`	`clusterSizes()` Returns the number of data points assigned to each cluster.
`protected abstract double`	`getNewCentroidScore(int newCentroidIndex, DoubleVector dataPoint)` Returns the new score for the cluster centroid indexed by `newCentroidIndex` when `dataPoint` is added to it.
`protected abstract double`	`getOldCentroidScore(DoubleVector vector, int oldCentroidIndex, int altClusterSize)` Returns the new score for the cluster centroid represented by `altCurrentCentroid` with the new `altClusterSize`.
`protected static double`	`modifiedMagnitude(DoubleVector c, DoubleVector v)` Returns the magnitude of `c` as if `v` was added to the the vector.
`protected static double`	`modifiedMagnitudeSqrd(DoubleVector c, DoubleVector v)` Returns the magnitude squared of `c` as if `v` was added to the vector.
`double`	`score()` Returns the score computed by this `CriterionFunction`.
`void`	`setup(Matrix m, int[] initialAssignments, int numClusters)` Creates the cluster centroids and any other meta data needed by this `CriterionFunction`.
`protected void`	`subSetup(Matrix m)` Setup any extra information needed before computing the cost values for each cluster.
`protected static DoubleVector`	`subtract(DoubleVector c, DoubleVector v)` Returns a `DoubleVector` that is equal to `c - v`.
`protected static double`	`subtractedMagnitude(DoubleVector c, DoubleVector v)` Returns the magnitude of `c` as if `v` was added to the the vector.
`protected static double`	`subtractedMagnitudeSqrd(DoubleVector c, DoubleVector v)` Returns the magnitude squared of `c` as if `v` was added to the vector.
`boolean`	`update(int currentVectorIndex)` Updates the clustering assignment for data point indexed by `currentVectorIndex`.
`protected void`	`updateScores(int newCentroidIndex, int oldCentroidIndex, DoubleVector vector)`

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

Methods inherited from interface edu.ucla.sspace.clustering.criterion.CriterionFunction
isMaximize

- Field Detail
  - matrix
```
protected List<DoubleVector> matrix
```
    The Matrix holding the data points.
  - assignments
```
protected int[] assignments
```
    The set of cluster assignments for each cluster.
  - centroids
```
protected DoubleVector[] centroids
```
    The centroids representing each cluster.
  - clusterSizes
```
protected int[] clusterSizes
```
    The number of data points found in each cluster.
  - costs
```
protected double[] costs
```
    The cost computed for each cluster. This is maintained seperatly so that update can modify only the two relevant clusters being modified.
- Constructor Detail
  - BaseFunction
```
public BaseFunction()
```
    Constructs a new BaseFunction.
- Method Detail
  - setup
```
public void setup(Matrix m,
         int[] initialAssignments,
         int numClusters)
```
    Creates the cluster centroids and any other meta data needed by this CriterionFunction.
    
    Specified by:
    
    setup in interface CriterionFunction
    
    Parameters:
    m - The Matrix holding data points. This will be used as read only.
    initialAssignments - The cluster assignments for each data point in m. This is used as read only and discarded.
  - subSetup
```
protected void subSetup(Matrix m)
```
    Setup any extra information needed before computing the cost values for each cluster.
  - update
```
public boolean update(int currentVectorIndex)
```
    Updates the clustering assignment for data point indexed by currentVectorIndex. This returns true if the data point is left in the same cluster and false if it was relocated to another data point.
    
    Specified by:
    
    update in interface CriterionFunction
  - getOldCentroidScore
```
protected abstract double getOldCentroidScore(DoubleVector vector,
                         int oldCentroidIndex,
                         int altClusterSize)
```
    Returns the new score for the cluster centroid represented by altCurrentCentroid with the new altClusterSize.
    
    Parameters:
    altCurrentCentroid - The current updated cluster centroid
    altClusterSize - The current updated cluster size
  - getNewCentroidScore
```
protected abstract double getNewCentroidScore(int newCentroidIndex,
                         DoubleVector dataPoint)
```
    Returns the new score for the cluster centroid indexed by newCentroidIndex when dataPoint is added to it. Implementations of this method should not actually add dataPoint to the centroid, but should instead use the helper functions provided to compute the new score.
    
    Parameters:
    newCentroidIndex - The index of the current alternate centroid
    dataPoint - The current data point that is being reassigned
  - updateScores
```
protected void updateScores(int newCentroidIndex,
                int oldCentroidIndex,
                DoubleVector vector)
```
  - subtract
```
protected static DoubleVector subtract(DoubleVector c,
                    DoubleVector v)
```
    Returns a DoubleVector that is equal to c - v. This method is used instead of the one in VectorMath so that a DenseDynamicMagnitudeVector can be used to represent the difference. This vector type is optimized for when many calls to magnitude are interleaved with updates to a few dimensions in the vector.
  - assignments
```
public int[] assignments()
```
    Returns the cluster assignment indices for each data point in the original matrix passed to {@link #setup(Matrix, int[] int) setup).
    
    Specified by:
    
    assignments in interface CriterionFunction
  - centroids
```
public DoubleVector[] centroids()
```
    Returns the final set of centroids computed for the dataset passed to setup.
    
    Specified by:
    
    centroids in interface CriterionFunction
  - clusterSizes
```
public int[] clusterSizes()
```
    Returns the number of data points assigned to each cluster.
    
    Specified by:
    
    clusterSizes in interface CriterionFunction
  - score
```
public double score()
```
    Returns the score computed by this CriterionFunction.
    
    Specified by:
    
    score in interface CriterionFunction
  - modifiedMagnitudeSqrd
```
protected static double modifiedMagnitudeSqrd(DoubleVector c,
                           DoubleVector v)
```
    Returns the magnitude squared of c as if v was added to the vector. We do this because it would be more costly, garbage collection wise, to create a new vector for each alternate cluster and then throw away all but one of them.
  - modifiedMagnitude
```
protected static double modifiedMagnitude(DoubleVector c,
                       DoubleVector v)
```
    Returns the magnitude of c as if v was added to the the vector. We do this because it would be more costly, garbage collection wise, to create a new vector for each alternate cluster and * vector.
  - subtractedMagnitudeSqrd
```
protected static double subtractedMagnitudeSqrd(DoubleVector c,
                             DoubleVector v)
```
    Returns the magnitude squared of c as if v was added to the vector. We do this because it would be more costly, garbage collection wise, to create a new vector for each alternate cluster and then throw away all but one of them.
  - subtractedMagnitude
```
protected static double subtractedMagnitude(DoubleVector c,
                         DoubleVector v)
```
    Returns the magnitude of c as if v was added to the the vector. We do this because it would be more costly, garbage collection wise, to create a new vector for each alternate cluster and * vector.

Class BaseFunction

Field Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Methods inherited from interface edu.ucla.sspace.clustering.criterion.CriterionFunction

Field Detail

matrix

assignments

centroids

clusterSizes

costs

Constructor Detail

BaseFunction

Method Detail

setup

subSetup

update

getOldCentroidScore

getNewCentroidScore

updateScores

subtract

assignments

centroids

clusterSizes

score

modifiedMagnitudeSqrd

modifiedMagnitude

subtractedMagnitudeSqrd

subtractedMagnitude