at.tuwien.ifs.somtoolbox.layers
Class Unit

java.lang.Object
  extended by at.tuwien.ifs.somtoolbox.layers.InputContainer
      extended by at.tuwien.ifs.somtoolbox.layers.Unit
Direct Known Subclasses:
GrowingCellUnit

public class Unit
extends InputContainer

Represents a unit on a map. It has a position in terms of x and y coordinates and an n-dimensional weight vector. Data can be mapped onto a Unit. Labels can be assigned to a Unit to describe the mapped data. A Unit can also have an assigned map for use in hierarchical models.
TODO: The type of mappedSOM should be made more general than it is now. FIXME: similar to what should be done with GrowingLayer, we should make a Unit3D version out of this for 3D SOMs, to keep the memory fingerprint small, and avoid overloading many methods with 2D and 3D params, which makes it very hard to read

Version:
$Id: Unit.java 3621 2010-07-07 13:33:28Z mayer $
Author:
Michael Dittenbach

Nested Class Summary
static class Unit.FeatureWeightMode
          Types of feature weighting modes
 
Field Summary
private  ArrayList<InputDatum> batchSomNeighbourhood
           
private  Label[] bestcontextWeights
           
static String CONTEXT
           
private  Label[] contextGateLabels
           
private  int dim
           
private  double[] featureWeights
           
static String GATE
           
private  Label[] gateWeights
           
private static int INIT_INTERVAL_INTERPOLATE
           
private static int INIT_PCA
           
private static int INIT_RANDOM
           
private static int INIT_VECTOR
           
private  Label[] kaskiGateLabels
           
private  Label[] kaskiLabels
           
static String KEYWORDS
           
private  Label[] labels
           
static String LABELSOM
           
private  Layer layer
           
private  GrowingSOM mappedSOM
           
private  double quantizationError
           
private  double[] weightVector
           
private  int xPos
           
private  int yPos
           
private  int zPos
           
 
Constructor Summary
Unit(Layer l, int x, int y, double[] vec)
          Constructs a Unit on Layer specified by argument layer at position x/y with a given weight vector vec.
Unit(Layer l, int x, int y, int z, double[] vec)
          Constructs a Unit on Layer specified by argument layer at position x/y with a given weight vector vec.
Unit(Layer l, int x, int y, int z, int d, Random rand, boolean norm)
          Constructs a Unit on Layer specified by argument layer at position x/y with a randomly initialized weight vector of dimension d.
Unit(Layer l, int x, int y, int z, int d, Random rand, boolean norm, int initialisationMode)
           
Unit(Layer l, int x, int y, int d, Random rand, boolean norm)
          Constructs a Unit on Layer specified by argument layer at position x/y with a randomly initialized weight vector of dimension d.
Unit(Layer l, int x, int y, int d, Random rand, boolean norm, int initialisationMode)
           
 
Method Summary
 void addBatchSomNeighbour(InputDatum d)
           
 void addMappedInput(InputData data, boolean calcQE)
          Map all the input vectors contained in specified InputData object onto this unit.
 void addMappedInput(InputDatum datum, boolean calcQE)
          Adds a single input datum to the unit.
 void addMappedInput(String name, double dist, boolean calcQE)
          Convenience method to add an input datum specified by its name and distance.
 void calculateQuantizationError()
          Recalculates the quantization error for this unit.
 void clearBatchSomList()
           
 void clearLabels()
          Removes the labels of this unit.
 void clearMappedInput()
          Removes the mapped input data and sets this units quantization error to 0.
 void copyFeatureWeights(double[] featureWeights)
           
 Label[] getBestContextWeights()
           
 Label[] getContextGateLabels()
           
 int getDim()
           
 double[] getFeatureWeights()
           
 Label[] getGateWeights()
           
 Label[] getKaskiGateLabels()
           
 Label[] getKaskiLabels()
           
 Label[] getLabels()
           
 Label[] getLabels(String type)
          Returns an array of labels or null, if no labels are assigned to this unit.
 Layer getLayer()
          Returns the layer of units this unit is part of.
 String getMapIdString()
          Returns the map identification string of this unit's layer.
 int getMapLevel()
          Returns the level of this unit's layer in a hierarchy of maps.
 GrowingSOM getMappedSOM()
          Returns the map assigned to this unit or null otherwise.
 int getMapXSize()
          Returns the width of this unit's map.
 int getMapYSize()
          Returns the height of this unit's map.
 int getMapZSize()
          Returns the depth of this unit's map.
 String getUnitLabels()
           
 double[] getWeightVector()
          Returns the weight vector of this unit.
 void getWeightVectorFromBatchSomNeighbourhood()
           
 int getXPos()
          Returns the horizontal position of this unit on the map it is part of.
 int getYPos()
          Returns the vertical position of this unit on the map it is part of.
 int getZPos()
          Returns the depth position of this unit on the map it is part of.
 void initWeightVectorBySample(InputDatum datum)
          Sets this unit's weight vector to the vector of the input datum specified by argument datum.
 boolean isTopLeftUnit()
           
 String printCoordinates()
           
 String printCoordinatesSpaceSeparated()
           
 String printUnitDetails(InputData inputData, TemplateVector tv)
           
 void removeMappedInput(String label)
           
 void restoreBestContextWeightLabels(int nrbestcontext, String[] bestContextWeightUnitLabels)
           
 void restoreContextGateLabels(int nrContextGate, String[] contextGateUnitLabels)
           
 void restoreGateWeightLabels(int nrgateweights, String[] gateWeightUnitLabels)
           
 void restoreKaskiGateLabels(int nrKaskiGate, String[] kaskiGateUnitabels)
           
 void restoreKaskiLabels(int nrKaski, String[] kaskiUnitLabels, double[] kaskiUnitLabelsWgt)
           
 void restoreLabels(int nrUnitLabels, String[] unitLabels, double[] unitLabelsQe, double[] unitLabelsWgt)
          Restores the labels of a unit based on the information provided by the arguments.
 void restoreMappings(int nrVecsMapped, String[] mappedVecs, double[] mappedVecsDist)
          Restores the mapped input data of a unit based on the information provided by the arguments.
 void setContextGateLabels(Label[] context_gate_labels)
           
 void setFeatureWeights(double[] featureWeights)
           
 void setKaskiGateLabels(Label[] kaski_gate_labels)
           
 void setLabels(Label[] labels)
          Assigns labels to this unit.
 void setMappedSOM(GrowingSOM mappedSOM)
          Assigns a map to this unit.
(package private)  void setPositions(int x, int y, int z)
           
 void setWeightVector(double[] vector)
          Sets the weight vector of this unit.
 String toString()
           
 void updatePosition(int x, int y)
           
 void updatePosition(int x, int y, int z)
          Sets the coordinates of this unit on the map, if they have changed.
 
Methods inherited from class at.tuwien.ifs.somtoolbox.layers.InputContainer
addMappedInput, clearMappedInputs, getInputIndex, getMappedInputDistance, getMappedInputDistance, getMappedInputDistances, getMappedInputName, getMappedInputNames, getMappedInputNamesAsList, getNumberOfMappedInputs, isMapped
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Field Detail

KEYWORDS

public static final String KEYWORDS
See Also:
Constant Field Values

GATE

public static final String GATE
See Also:
Constant Field Values

CONTEXT

public static final String CONTEXT
See Also:
Constant Field Values

LABELSOM

public static final String LABELSOM
See Also:
Constant Field Values

INIT_RANDOM

private static final int INIT_RANDOM
See Also:
Constant Field Values

INIT_INTERVAL_INTERPOLATE

private static final int INIT_INTERVAL_INTERPOLATE
See Also:
Constant Field Values

INIT_VECTOR

private static final int INIT_VECTOR
See Also:
Constant Field Values

INIT_PCA

private static final int INIT_PCA
See Also:
Constant Field Values

dim

private int dim

labels

private Label[] labels

kaskiGateLabels

private Label[] kaskiGateLabels

kaskiLabels

private Label[] kaskiLabels

gateWeights

private Label[] gateWeights

bestcontextWeights

private Label[] bestcontextWeights

contextGateLabels

private Label[] contextGateLabels

layer

private Layer layer

mappedSOM

private GrowingSOM mappedSOM

quantizationError

private double quantizationError

weightVector

private double[] weightVector

featureWeights

private double[] featureWeights

xPos

private int xPos

yPos

private int yPos

zPos

private int zPos

batchSomNeighbourhood

private ArrayList<InputDatum> batchSomNeighbourhood
Constructor Detail

Unit

public Unit(Layer l,
            int x,
            int y,
            double[] vec)
Constructs a Unit on Layer specified by argument layer at position x/y with a given weight vector vec.

Parameters:
l - the layer that contains this Unit.
x - the horizontal position on the layer.
y - the vertical position on the layer.
vec - the weight vector.

Unit

public Unit(Layer l,
            int x,
            int y,
            int z,
            double[] vec)
Constructs a Unit on Layer specified by argument layer at position x/y with a given weight vector vec.

Parameters:
l - the layer that contains this Unit.
x - the horizontal position on the layer.
y - the vertical position on the layer.
z - the depth position on the layer.
vec - the weight vector.

Unit

public Unit(Layer l,
            int x,
            int y,
            int d,
            Random rand,
            boolean norm)
Constructs a Unit on Layer specified by argument layer at position x/y with a randomly initialized weight vector of dimension d. Argument norm determines whether the weight vector should be normalized or not. TODO: This might be change in the future due to unflexibility regarding hard coded normalization methods.

Parameters:
l - the layer that contains this Unit.
x - the horizontal position on the layer.
y - the vertical position on the layer.
d - the dimensionality of the weight vector.
rand - a random number generator provided by the caller.
norm - the type of normalization (see text above).

Unit

public Unit(Layer l,
            int x,
            int y,
            int z,
            int d,
            Random rand,
            boolean norm)
Constructs a Unit on Layer specified by argument layer at position x/y with a randomly initialized weight vector of dimension d. Argument norm determines whether the weight vector should be normalized or not. TODO: This might be change in the future due to unflexibility regarding hard coded normalization methods.

Parameters:
l - the layer that contains this Unit.
x - the horizontal position on the layer.
y - the vertical position on the layer.
z - the depth position on the layer.
d - the dimensionality of the weight vector.
rand - a random number generator provided by the caller.
norm - the type of normalization (see text above).

Unit

public Unit(Layer l,
            int x,
            int y,
            int d,
            Random rand,
            boolean norm,
            int initialisationMode)

Unit

public Unit(Layer l,
            int x,
            int y,
            int z,
            int d,
            Random rand,
            boolean norm,
            int initialisationMode)
Method Detail

addMappedInput

public void addMappedInput(InputDatum datum,
                           boolean calcQE)
Adds a single input datum to the unit. The method also calculates the distance between the unit's weight vector and the datum.

Parameters:
datum - the input datum to be added.
calcQE - determines if the quantization error should be recalculated.
See Also:
addMappedInput(String, double, boolean)

addMappedInput

public void addMappedInput(InputData data,
                           boolean calcQE)
Map all the input vectors contained in specified InputData object onto this unit.

Parameters:
data - The container for input vector
calcQE - determines if the quantization error should be recalculated.
See Also:
addMappedInput(InputDatum, boolean)

addMappedInput

public void addMappedInput(String name,
                           double dist,
                           boolean calcQE)
Convenience method to add an input datum specified by its name and distance. The quantization error is recalculated if argument calcQE is true.

Parameters:
name - the name of the input datum.
dist - the precalculated distance between input datum and weight vector
calcQE - determines if the quantization error should be recalculated.

removeMappedInput

public void removeMappedInput(String label)
Overrides:
removeMappedInput in class InputContainer

calculateQuantizationError

public void calculateQuantizationError()
Recalculates the quantization error for this unit.


clearLabels

public void clearLabels()
Removes the labels of this unit.


clearMappedInput

public void clearMappedInput()
Removes the mapped input data and sets this units quantization error to 0.


getLabels

public Label[] getLabels(String type)
Returns an array of labels or null, if no labels are assigned to this unit.

Returns:
an array of labels or null.

getLabels

public Label[] getLabels()

getKaskiGateLabels

public Label[] getKaskiGateLabels()

getKaskiLabels

public Label[] getKaskiLabels()

getGateWeights

public Label[] getGateWeights()

getBestContextWeights

public Label[] getBestContextWeights()

getContextGateLabels

public Label[] getContextGateLabels()

getLayer

public Layer getLayer()
Returns the layer of units this unit is part of.

Returns:
the layer of units this unit is part of.

getMapIdString

public String getMapIdString()
Returns the map identification string of this unit's layer.

Returns:
the map identification string of this unit's layer.

getMapLevel

public int getMapLevel()
Returns the level of this unit's layer in a hierarchy of maps.

Returns:
the level of this unit's layer in a hierarchy of maps.

getMappedSOM

public GrowingSOM getMappedSOM()
Returns the map assigned to this unit or null otherwise.

Returns:
the map assigned to this unit or null otherwise.

setMappedSOM

public void setMappedSOM(GrowingSOM mappedSOM)
Assigns a map to this unit.

Parameters:
mappedSOM - a map to be assigned to this unit.

getMapXSize

public int getMapXSize()
Returns the width of this unit's map.

Returns:
the width of this unit's map.

getMapYSize

public int getMapYSize()
Returns the height of this unit's map.

Returns:
the height of this unit's map.

getMapZSize

public int getMapZSize()
Returns the depth of this unit's map.

Returns:
the depth of this unit's map.

getWeightVector

public double[] getWeightVector()
Returns the weight vector of this unit.

Returns:
the weight vector of this unit.

setWeightVector

public void setWeightVector(double[] vector)
                     throws SOMToolboxException
Sets the weight vector of this unit.

Parameters:
vector - the weight vector.
Throws:
SOMToolboxException

getXPos

public int getXPos()
Returns the horizontal position of this unit on the map it is part of.

Returns:
the horizontal position of this unit on the map it is part of.

getYPos

public int getYPos()
Returns the vertical position of this unit on the map it is part of.

Returns:
the vertical position of this unit on the map it is part of.

getZPos

public int getZPos()
Returns the depth position of this unit on the map it is part of.

Returns:
the depth position of this unit on the map it is part of.

initWeightVectorBySample

public void initWeightVectorBySample(InputDatum datum)
Sets this unit's weight vector to the vector of the input datum specified by argument datum.

Parameters:
datum - the input datum.

restoreLabels

public void restoreLabels(int nrUnitLabels,
                          String[] unitLabels,
                          double[] unitLabelsQe,
                          double[] unitLabelsWgt)
Restores the labels of a unit based on the information provided by the arguments. The value of argument nrUnitLabels must be equal to the dimensionalities of the arrays specified in the other arguments. If this is not the case, no labels will be restored.

Parameters:
nrUnitLabels - the number of labels.
unitLabels - an array of strings containing the labels' names.
unitLabelsQe - an array of double values containing the qunatization errors for the single labels.
unitLabelsWgt - an array of double values containing the actual values for the single labels.

restoreContextGateLabels

public void restoreContextGateLabels(int nrContextGate,
                                     String[] contextGateUnitLabels)

restoreKaskiLabels

public void restoreKaskiLabels(int nrKaski,
                               String[] kaskiUnitLabels,
                               double[] kaskiUnitLabelsWgt)

restoreKaskiGateLabels

public void restoreKaskiGateLabels(int nrKaskiGate,
                                   String[] kaskiGateUnitabels)

restoreGateWeightLabels

public void restoreGateWeightLabels(int nrgateweights,
                                    String[] gateWeightUnitLabels)

restoreBestContextWeightLabels

public void restoreBestContextWeightLabels(int nrbestcontext,
                                           String[] bestContextWeightUnitLabels)

restoreMappings

public void restoreMappings(int nrVecsMapped,
                            String[] mappedVecs,
                            double[] mappedVecsDist)
Restores the mapped input data of a unit based on the information provided by the arguments. The value of argument nrVecsMapped must be equal to the dimensionalities of the arrays specified in the other arguments. If this is not the case, no input data will be restored. The quantization error will also be recalculated.

Parameters:
nrVecsMapped - the number of input data.
mappedVecs - an array of strings containing the data identifiers.
mappedVecsDist - an array of double values containing the distances between the weight vector and the respective input data.

setLabels

public void setLabels(Label[] labels)
Assigns labels to this unit.

Parameters:
labels - array of labels to be assigned to this unit.

setKaskiGateLabels

public void setKaskiGateLabels(Label[] kaski_gate_labels)

setContextGateLabels

public void setContextGateLabels(Label[] context_gate_labels)

updatePosition

public void updatePosition(int x,
                           int y,
                           int z)
Sets the coordinates of this unit on the map, if they have changed. This happens in architectures with growing map sizes during training.

Parameters:
x - the horizontal position on the map.
y - the vertical position on the map.
z - the height position on the map.

updatePosition

public void updatePosition(int x,
                           int y)

addBatchSomNeighbour

public void addBatchSomNeighbour(InputDatum d)

clearBatchSomList

public void clearBatchSomList()

getWeightVectorFromBatchSomNeighbourhood

public void getWeightVectorFromBatchSomNeighbourhood()

toString

public String toString()
Overrides:
toString in class Object

printCoordinates

public String printCoordinates()

printCoordinatesSpaceSeparated

public String printCoordinatesSpaceSeparated()

printUnitDetails

public String printUnitDetails(InputData inputData,
                               TemplateVector tv)

getFeatureWeights

public double[] getFeatureWeights()

setFeatureWeights

public void setFeatureWeights(double[] featureWeights)

copyFeatureWeights

public void copyFeatureWeights(double[] featureWeights)

getDim

public int getDim()

getUnitLabels

public String getUnitLabels()

setPositions

void setPositions(int x,
                  int y,
                  int z)

isTopLeftUnit

public boolean isTopLeftUnit()