at.tuwien.ifs.somtoolbox.layers
Class GrowingLayer

java.lang.Object
  extended by at.tuwien.ifs.somtoolbox.layers.GrowingLayer
All Implemented Interfaces:
Layer
Direct Known Subclasses:
MnemonicGrowingLayer, ToroidLayer

public class GrowingLayer
extends Object
implements Layer

Implementation of a growing Self-Organizing Map layer that can also be static in size. Layer growth is based on the quantization errors of the units and the distance to their respective neighboring units.

Version:
$Id: GrowingLayer.java 3978 2010-12-16 14:36:44Z mayer $
Author:
Michael Dittenbach, Rudolf Mayer

Nested Class Summary
static class GrowingLayer.Flip
           
static class GrowingLayer.Rotation
           
(package private)  class GrowingLayer.UpdaterThread
           
 
Nested classes/interfaces inherited from interface at.tuwien.ifs.somtoolbox.layers.Layer
Layer.GridLayout, Layer.GridTopology
 
Field Summary
private  Hashtable<Integer,Point2D[][]> binAssignmentCache
           
private  String commonVectorLabelPrefix
           
private static double CUTOFF_SIGMA
           
private  InputData data
           
protected  int dim
           
private  CountDownLatch doneSignal
           
private  ExecutorService e
           
protected  Layer.GridLayout gridLayout
           
protected  Layer.GridTopology gridTopology
           
private  int identifier
           
private  int interruptEvery
           
private  int level
           
(package private)  double[] maxFeatureValues
           
protected  DistanceMetric metric
           
private  String metricName
           
protected  AbstractWeightedMetric metricWeighted
           
(package private)  double[] minFeatureValues
           
private  boolean normalized
           
private  int notEmptyUnits
          Stores the number of units that are not empty, i.e.
private  QualityMeasure qualityMeasure
           
private  Random rand
           
private  Random randSkipProbability
           
private  Cuboid[] ranges
           
private  Hashtable<Integer,ArrayList<ComponentRegionCount>> regionAssignmentCache
           
private  String revision
           
static int[] ROTATIONS
           
(package private)  int skippedNonSelected
           
private  Unit superUnit
           
private static int THREAD_COUNT
           
private  int threadsUsed
           
private  TrainingInterruptionListener til
           
(package private)  int trainedNonSelected
           
 cern.colt.matrix.DoubleMatrix2D unitDistanceMatrix
           
protected  Unit[][][] units
           
private  AdaptiveCoordinatesVirtualLayer virtualLayer
           
protected  int xSize
           
protected  int ySize
           
protected  int zSize
           
 
Constructor Summary
GrowingLayer(int xSize, int ySize, int zSize, String metricName, int dim, boolean normalized, boolean usePCA, long seed, InputData data)
          Convenience constructor for top layer map of GHSOM or a single map.
GrowingLayer(int xSize, int ySize, String metricName, int dim, boolean normalized, boolean usePCA, long seed, InputData data)
          Convenience constructor for top layer map of GHSOM or a single map.
GrowingLayer(int id, Unit su, int xSize, int ySize, int zSize, String metricName, int dim, boolean normalized, boolean usePCA, long seed, InputData data)
          Constructor for a new, untrained layer.
GrowingLayer(int id, Unit su, int xSize, int ySize, int zSize, String metricName, int dim, double[][][][] vectors, long seed)
          Constructor for an already trained layer as specified by 2-dimensional array of d-dimensional weight vectors as argument vectors.
GrowingLayer(int id, Unit su, int xSize, int ySize, String metricName, int dim, boolean normalized, boolean usePCA, long seed, InputData data)
          Constructor for a new, untrained layer.
GrowingLayer(int id, Unit su, int xSize, int ySize, String metricName, int dim, double[][][] vectors, long seed)
          Constructor for an already trained layer as specified by 2-dimensional array of d-dimensional weight vectors as argument vectors.
 
Method Summary
protected static double[][][][] addDimension(int x, int y, double[][][] vec)
           
 void calculateQuantizationErrorForUnits()
          Calculates the quantization error for all units of the layer.
static void checkRotation(int rotation)
           
 void clearLabels()
          Removes all labels from the units.
 void clearMappedInput()
          Removes all mapped input data from the units.
 Object clone()
          Clone might not be fully functional!
 InputCorrections computeUnitFeatureWeights(InputCorrections corrections, InputData data, Unit.FeatureWeightMode mode)
          Implementation of general weighting as in Nünrberger/Detyniecki, 'Weighted Self-Organizing Maps: Incorporating User Feedback'
 boolean equalWeights(GrowingLayer otherLayer)
          Checks whether this and the given GrowingLayer are equal in their weight (model) vectors.
 void flip(GrowingLayer.Flip flip)
          Flip the layer.
 Unit[][] get2DUnits()
          Returns all units with depth 0 of the layer
 String[] getAllMappedDataNames()
           
 String[] getAllMappedDataNames(boolean sort)
          Returns all mapped inputs from all the units of the layer in an array.
 ArrayList<String> getAllMappedDataNamesAsList()
           
 ArrayList<GrowingSOM> getAllSubMaps()
           
 Unit[] getAllUnits()
          Returns all units of the layer in an array.
 int[][] getBinAssignment(int component, int bins)
           
 Point2D[][] getBinCentres(int bins)
           
 Point2D[] getBinCentres(int[][] binAssignment, int bins)
           
 ArrayList<ComponentLine2D> getBinCentresAsList(int bins)
           
 double getBinDeviation(int[][] binAssignment, int bins)
           
 String getCommonVectorLabelPrefix()
           
 double[][] getComponentPlane(int component)
          Returns a component plane of the component specified by the argument component.
 double[][] getComponentPlane(int component, int z)
          Returns a component plane of the component specified by the argument component.
 double[][][] getComponentPlane3D(int component)
           
 InputData getData()
           
 double[] getDeviation(int bins)
           
 int getDim()
          Returns the dimensionality of the weight vectors.
private  int getDimension(int x, int y, int z, double[][][][] vectors)
          Needed for mnemonic (sparse) SOMs to find out the vector dimension, by finding the first non-null vector in the array
private  Unit getErrorUnit(QualityMeasure qm, String methodName)
          Returns the unit having the highest quantization error.
 double[][] getExtremes()
           
private  String[] getFirstNLabels(int n, ArrayList<InputNameDistance> items)
           
 Layer.GridLayout getGridLayout()
           
 Layer.GridTopology getGridTopology()
           
 int getIdentifier()
          Returns the ID of the layer.
 String getIdString()
          Returns the identification string of the map layer.
private  double[] getInputVector(String query, SOMLibTemplateVector templateVector)
           
 int getLevel()
          Returns the level of the map layer in a hierarchical model.
 double getMapDistance(int x1, int y1, int x2, int y2)
           
 double getMapDistance(int x1, int y1, int z1, int x2, int y2, int z2)
          Returns the distance between two units on the map grid.
 double getMapDistance(Unit u1, Unit u2)
          Returns the distance between two units on the map grid.
 double getMapDistanceSq(int x1, int y1, int z1, int x2, int y2, int z2)
           
 double getMapDistanceSq(Unit u1, Unit u2)
           
 DistanceMetric getMetric()
          Calculates and returns the mean quantization error of the map based on the quantization errors of the single units.
protected  Unit getMostDissimilarNeighbor(Unit u)
          Returns the neighboring unit of a unit specified by argument u with the most distant weight vector.
 ArrayList<Unit> getNeighbouringUnits(int x, int y)
           
 ArrayList<Unit> getNeighbouringUnits(int x, int y, double radius)
          Convenience method for getNeighbouringUnits(int, int, int, double)
private  ArrayList<Unit> getNeighbouringUnits(int x, int y, int z)
           
 ArrayList<Unit> getNeighbouringUnits(int x, int y, int z, double radius)
          Gets neighbours within a certain radius; uses getMapDistance(int, int, int, int, int, int) for map distance computation
protected  ArrayList<Unit> getNeighbouringUnits(Unit u)
          Get direct neighbours of the given unit.
protected  ArrayList<Unit> getNeighbouringUnits(Unit u, double radius)
          Convenience method for getNeighbouringUnits(int, int, int, double)
 String[] getNNearestInputs(String datumlabel, int n, InputData data)
           
 String[] getNNearestInputs(Unit u, int n)
           
static int getNO_CPUS()
           
 int getNumberOfMappedInputs()
          Returns the total number of Inputs mapped on all units in the map layer.
 int getNumberOfNotEmptyUnits()
          Calculates and returns the number of units that are not empty, i.e.
 ArrayList<ComponentRegionCount> getNumberOfRegions(int bins)
           
private  int getNumberOfRegions(int[][] regionAssignement)
           
 QualityMeasure getQualityMeasure()
          Returns the quality information.
private  int[][] getRegionAssignement(int[][] binAssignement, int numberOfBins)
           
 String getRevision()
          Returns the revision string of this layer.
 Unit getSuperUnit()
          Returns the superordinate unit, or null if none exists.
 Unit getUnit(int x, int y)
          Returns the Unit at the position specified by the x and y arguments.
 Unit getUnit(int x, int y, int z)
          Returns the Unit at the position specified by the x and y arguments.
 int getUnitCount()
           
 cern.colt.matrix.DoubleMatrix2D getUnitDistanceMatrix()
          Computes a distance matrix between all Units in the Layer
 Unit getUnitForDatum(String name)
          Returns the unit onto which the datum specified by its name by argument name is mapped.
 Unit getUnitForIndex(int index)
           
 int getUnitIndex(int x, int y)
          Returns the index of given unit coordinates.
 Unit[][][] getUnits()
          Returns all units of the layer in a 3D array.
 AdaptiveCoordinatesVirtualLayer getVirtualLayer()
           
 Unit getWinner(InputDatum input)
          Returns the winner unit for a given input datum specified by argument input.
 Unit getWinner(InputDatum input, AbstractWeightedMetric metric)
          Returns the winner for a given unit, using a weighted distance metric.
 Unit getWinner(InputDatum input, DistanceMetric metric)
          Returns the winner unit for a given input datum specified by argument input.
 Unit getWinnerFromQuery(String query, SOMLibTemplateVector templateVector)
          Return the winning unit for the given query.
 Unit[] getWinners(InputDatum input, int num)
           
 Unit[] getWinners(InputDatum input, int num, DistanceMetric metric)
          Returns a number of best-matching units sorted by distance (ascending) for a given input datum.
 UnitDistance[] getWinnersAndDistances(InputDatum input, int num)
          Returns a number of best-matching units and distances sorted by distance (ascending) for a given input datum.
 Unit[] getWinnersFromQuery(String query, int num, SOMLibTemplateVector templateVector)
           
 String[] getWinningInputDataFromQuery(String query, int num, SOMLibTemplateVector templateVector)
           
 int getXSize()
          Returns the width of the map layer.
 int getYSize()
          Returns the height of the map layer.
 int getZSize()
          Returns the depth of the map layer.
 boolean hasMappedInput(int x, int y)
           
 boolean hasNeighbours(int x, int y)
           
 boolean hasNeighbours(int x, int y, int z)
           
private  void initCPURanges()
           
private  void insertRowColumn(Unit a, Unit b, ProgressListener listener)
          Inserts a row or column of units between units specified by argument a and b.
 boolean isEdgeColumn(int x)
           
 boolean isEdgeRow(int y)
           
 boolean isValidUnitLocation(int x, int y)
           
 boolean isValidUnitLocation(Point pos)
           
private  void mapCompleteDataAfterTraining(InputData data)
          Maps data onto layer without recalculating the quantization error after every single input datum.
FIXME: add multi-threading
 void mapData(InputData data)
          Maps input data onto layer.
 Unit mapDatum(InputDatum datum)
          Maps a single input datum onto the layer and returns the winning unit.
 double maxNeighbourhoodRadius()
          Computes the maximum value the neighbourhood radius can take, that is in the diagonal from one corner to the other.
 double neighbourhoodFeatureWeight(double dist, int maxDist)
           
private  void printInfo(double targetQualityValue, String[] qmNameMethod, QualityMeasure qm)
           
 String printSize()
           
 String printUnitIndices()
           
private  void processRegionRecursive(int[][] binAssignment, int[][] regionAssignment, int x, int y)
           
 void rotate(GrowingLayer.Rotation rotation)
          Clockwise rotate the layer by the given degrees.
 void rotate(int rotation)
           
 void setCommonVectorLabelPrefix(String commonVectorLabelPrefix)
           
 void setGridLayout(Layer.GridLayout gridLayout)
           
 void setGridTopology(Layer.GridTopology gridTopology)
           
static void setNO_CPUS(int no_cpus)
           
 void setQualityMeasure(String qualityMeasureName)
           
 void setTrainingInterruptionListener(TrainingInterruptionListener t, int i)
          Assigns an object that implements the TrainingInterruptionListener interface to perform actions in certain intervals during training determined by argument i.
private  boolean specialClassMode(SOMProperties trainingProps)
           
 QualityMeasure train(InputData data, double initialLearnrate, double initialSigma, int numIterations, double tau, double targetQualityValue, String qualityMeasureName, SOMProperties trainingProps)
          Trains the layer with the input data.
 QualityMeasure train(InputData data, double iniLearnrate, double iniSigma, int numIterations, double tau, String qualityMeasureName, SOMProperties trainingProps)
          Trains the layer with the input data.
 QualityMeasure train(InputData data, double initialLearnrate, double initialSigma, int numIterations, int startIteration, double tau, double targetQualityValue, String qualityMeasureName, SOMProperties trainingProps)
          Trains the layer with the input data.
 QualityMeasure train(InputData data, double iniLearnrate, double iniSigma, int numIterations, int startIteration, double tau, String qualityMeasureName, SOMProperties trainingProps)
          Trains the layer with the input data.
private  void trainNormal(InputData data, int numIterations, int startIteration, SOMProperties trainingProps, double initialLearnrate, double initialSigma, double expParam, double expParam2, ProgressListener progressWriter)
           
private  void trainSpecial(InputData data, int numIterations, int startIteration, SOMProperties trainingProps, double initialLearnrate, double initialSigma, double expParam, double expParam2, SOMLibClassInformation classInfo, double minProbability, ProgressListener progressWriter)
           
private  void updateUnits(Unit winner, InputDatum input, double learnrate, double sigma)
           
private  void updateUnitsInArea(Unit winner, double learnrate, double opt1, double[] inputVector, Cuboid range)
           
private  void updateUnitsInArea(Unit winner, double learnrate, double opt1, double[] inputVector, int startX, int endX, int startY, int endY, int startZ, int endZ)
           
private  void updateUnitsNoBorder(Unit winner, InputDatum input, double learnrate, double sigma)
          Updates the weight vectors of the all map units with respect to the input datum and the according winner unit.
protected  void updateUnitsNormal(Unit winner, InputDatum input, double learnrate, double sigma)
          Updates the weight vectors of the all map units with respect to the input datum and the according winner unit.
 
Methods inherited from class java.lang.Object
equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

CUTOFF_SIGMA

private static final double CUTOFF_SIGMA
See Also:
Constant Field Values

ROTATIONS

public static final int[] ROTATIONS

dim

protected int dim

identifier

private int identifier

interruptEvery

private int interruptEvery

level

private int level

metric

protected DistanceMetric metric

metricWeighted

protected AbstractWeightedMetric metricWeighted

metricName

private String metricName

normalized

private boolean normalized

qualityMeasure

private QualityMeasure qualityMeasure

rand

private Random rand

randSkipProbability

private Random randSkipProbability

revision

private final String revision
See Also:
Constant Field Values

superUnit

private Unit superUnit

til

private TrainingInterruptionListener til

units

protected Unit[][][] units

xSize

protected int xSize

ySize

protected int ySize

zSize

protected int zSize

minFeatureValues

double[] minFeatureValues

maxFeatureValues

double[] maxFeatureValues

gridLayout

protected Layer.GridLayout gridLayout

gridTopology

protected Layer.GridTopology gridTopology

binAssignmentCache

private Hashtable<Integer,Point2D[][]> binAssignmentCache

regionAssignmentCache

private Hashtable<Integer,ArrayList<ComponentRegionCount>> regionAssignmentCache

THREAD_COUNT

private static int THREAD_COUNT

doneSignal

private CountDownLatch doneSignal

e

private ExecutorService e

ranges

private Cuboid[] ranges

threadsUsed

private final int threadsUsed

notEmptyUnits

private int notEmptyUnits
Stores the number of units that are not empty, i.e. that have at least one input mapped. This field should not be used directly, but only via getNumberOfNotEmptyUnits(), as the calculation of the value is only performed by that method and stored for future access.


data

private InputData data

skippedNonSelected

int skippedNonSelected

trainedNonSelected

int trainedNonSelected

commonVectorLabelPrefix

private String commonVectorLabelPrefix

unitDistanceMatrix

public cern.colt.matrix.DoubleMatrix2D unitDistanceMatrix

virtualLayer

private AdaptiveCoordinatesVirtualLayer virtualLayer
Constructor Detail

GrowingLayer

public GrowingLayer(int xSize,
                    int ySize,
                    String metricName,
                    int dim,
                    boolean normalized,
                    boolean usePCA,
                    long seed,
                    InputData data)
Convenience constructor for top layer map of GHSOM or a single map. The identifier of the map is set to 1 and the superordinate unit is set to null.

Parameters:
xSize - the number of columns.
ySize - the number of rows.
metricName - the name of the distance metric to use.
dim - the dimensionality of the weight vectors.
normalized - the type of normalization that is applied to the weight vectors of newly created units. This is usually Normalization.NONE or Normalization.UNIT_LEN.
seed - the random seed for creation of the units' weight vectors.
See Also:
Normalisation

GrowingLayer

public GrowingLayer(int xSize,
                    int ySize,
                    int zSize,
                    String metricName,
                    int dim,
                    boolean normalized,
                    boolean usePCA,
                    long seed,
                    InputData data)
Convenience constructor for top layer map of GHSOM or a single map. The identifier of the map is set to 1 and the superordinate unit is set to null.

Parameters:
xSize - the number of columns.
ySize - the number of rows.
zSize - the depth
metricName - the name of the distance metric to use.
dim - the dimensionality of the weight vectors.
normalized - the type of normalization that is applied to the weight vectors of newly created units. This is usually Normalization.NONE or Normalization.UNIT_LEN.
seed - the random seed for creation of the units' weight vectors.
See Also:
Normalisation

GrowingLayer

public GrowingLayer(int id,
                    Unit su,
                    int xSize,
                    int ySize,
                    String metricName,
                    int dim,
                    boolean normalized,
                    boolean usePCA,
                    long seed,
                    InputData data)
Constructor for a new, untrained layer.

Parameters:
id - the unique id of the layer in a hierarchy.
su - the pointer to the corresponding unit in the upper layer map.
xSize - the number of units in horizontal direction.
ySize - the number of units in vertical direction.
metricName - the name of the distance metric to use.
dim - the dimensionality of the weight vectors.
normalized - the type of normalization that is applied to the weight vectors of newly created units. This is usually Normalization.NONE or Normalization.UNIT_LEN.
seed - the random seed for creation of the units' weight vectors.
See Also:
Normalisation

GrowingLayer

public GrowingLayer(int id,
                    Unit su,
                    int xSize,
                    int ySize,
                    int zSize,
                    String metricName,
                    int dim,
                    boolean normalized,
                    boolean usePCA,
                    long seed,
                    InputData data)
Constructor for a new, untrained layer.

Parameters:
id - the unique id of the layer in a hierarchy.
su - the pointer to the corresponding unit in the upper layer map.
xSize - the number of units in horizontal direction.
ySize - the number of units in vertical direction.
zSize - the number of units in depth
metricName - the name of the distance metric to use.
dim - the dimensionality of the weight vectors.
normalized - the type of normalization that is applied to the weight vectors of newly created units. This is usually Normalization.NONE or Normalization.UNIT_LEN.
seed - the random seed for creation of the units' weight vectors.
See Also:
Normalisation

GrowingLayer

public GrowingLayer(int id,
                    Unit su,
                    int xSize,
                    int ySize,
                    String metricName,
                    int dim,
                    double[][][] vectors,
                    long seed)
             throws SOMToolboxException
Constructor for an already trained layer as specified by 2-dimensional array of d-dimensional weight vectors as argument vectors.

Parameters:
xSize - the number of columns.
ySize - the number of rows.
metricName - the name of the distance metric to use.
dim - the dimensionality of the weight vectors.
vectors - the three dimensional array of d dimensional weight vectors.
seed - the random seed for creation of the units' weight vectors.
Throws:
SOMToolboxException - if arguments x, y and d do not correspond to the dimensions of argument vectors.

GrowingLayer

public GrowingLayer(int id,
                    Unit su,
                    int xSize,
                    int ySize,
                    int zSize,
                    String metricName,
                    int dim,
                    double[][][][] vectors,
                    long seed)
             throws SOMToolboxException
Constructor for an already trained layer as specified by 2-dimensional array of d-dimensional weight vectors as argument vectors.

Parameters:
xSize - the number of columns.
ySize - the number of rows.
zSize - the depth
metricName - the name of the distance metric to use.
dim - the dimensionality of the weight vectors.
vectors - the two dimensional array of d dimensional weight vectors.
seed - the random seed for creation of the units' weight vectors.
Throws:
SOMToolboxException - if arguments x, y and d do not correspond to the dimensions of argument vectors.
Method Detail

addDimension

protected static double[][][][] addDimension(int x,
                                             int y,
                                             double[][][] vec)

equalWeights

public boolean equalWeights(GrowingLayer otherLayer)
Checks whether this and the given GrowingLayer are equal in their weight (model) vectors. Other information, such as mapping of vectors, labels, is not considered. This method can e.g. be utilised to check if two layers have been trained equally.


getDimension

private int getDimension(int x,
                         int y,
                         int z,
                         double[][][][] vectors)
Needed for mnemonic (sparse) SOMs to find out the vector dimension, by finding the first non-null vector in the array

Returns:
the vector dimension, or 0 if all vectors are null

calculateQuantizationErrorForUnits

public void calculateQuantizationErrorForUnits()
Calculates the quantization error for all units of the layer.


clearLabels

public void clearLabels()
Removes all labels from the units.


clearMappedInput

public void clearMappedInput()
Removes all mapped input data from the units.


getAllUnits

public Unit[] getAllUnits()
Returns all units of the layer in an array.

Specified by:
getAllUnits in interface Layer
Returns:
all units of the layer in an array.

getAllSubMaps

public ArrayList<GrowingSOM> getAllSubMaps()

get2DUnits

public Unit[][] get2DUnits()
Returns all units with depth 0 of the layer

Returns:
returns all units with depth 0 of the layer

getUnits

public Unit[][][] getUnits()
Returns all units of the layer in a 3D array.

Returns:
all units of the layer in a 3D array.

hasMappedInput

public boolean hasMappedInput(int x,
                              int y)

getAllMappedDataNames

public String[] getAllMappedDataNames(boolean sort)
Returns all mapped inputs from all the units of the layer in an array.

Parameters:
sort - indicates whether the labels should be sorted (alphabetically)
Returns:
all units of the layer in an array.

getAllMappedDataNamesAsList

public ArrayList<String> getAllMappedDataNamesAsList()

getAllMappedDataNames

public String[] getAllMappedDataNames()

getComponentPlane3D

public double[][][] getComponentPlane3D(int component)

getComponentPlane

public double[][] getComponentPlane(int component)
Description copied from interface: Layer
Returns a component plane of the component specified by the argument component. Returns null, if the argument component is out of range.

Specified by:
getComponentPlane in interface Layer
Parameters:
component - the index of the component.
Returns:
a double matrix containing the values of the weight vectors' respective components, or null if argument component is invalid.

getComponentPlane

public double[][] getComponentPlane(int component,
                                    int z)
Description copied from interface: Layer
Returns a component plane of the component specified by the argument component. Returns null, if the argument component is out of range.

Specified by:
getComponentPlane in interface Layer
Parameters:
component - the index of the component.
z - TODO
Returns:
a double matrix containing the values of the weight vectors' respective components, or null if argument component is invalid.

getExtremes

public double[][] getExtremes()
                       throws LayerAccessException
Throws:
LayerAccessException

getBinAssignment

public int[][] getBinAssignment(int component,
                                int bins)

getBinCentres

public Point2D[] getBinCentres(int[][] binAssignment,
                               int bins)

getBinCentres

public Point2D[][] getBinCentres(int bins)

getBinCentresAsList

public ArrayList<ComponentLine2D> getBinCentresAsList(int bins)

getBinDeviation

public double getBinDeviation(int[][] binAssignment,
                              int bins)

getDeviation

public double[] getDeviation(int bins)

getRegionAssignement

private int[][] getRegionAssignement(int[][] binAssignement,
                                     int numberOfBins)
                              throws LayerAccessException
Throws:
LayerAccessException

processRegionRecursive

private void processRegionRecursive(int[][] binAssignment,
                                    int[][] regionAssignment,
                                    int x,
                                    int y)
                             throws LayerAccessException
Throws:
LayerAccessException

getNumberOfRegions

private int getNumberOfRegions(int[][] regionAssignement)

getNumberOfRegions

public ArrayList<ComponentRegionCount> getNumberOfRegions(int bins)
                                                   throws LayerAccessException
Throws:
LayerAccessException

getDim

public int getDim()
Returns the dimensionality of the weight vectors.

Returns:
the dimensionality of the weight vectors.

getErrorUnit

private Unit getErrorUnit(QualityMeasure qm,
                          String methodName)
Returns the unit having the highest quantization error.

Returns:
the unit having the highest quantization error.

getIdentifier

public int getIdentifier()
Returns the ID of the layer.

Returns:
the ID of the layer.

getIdString

public String getIdString()
Description copied from interface: Layer
Returns the identification string of the map layer.

Specified by:
getIdString in interface Layer
Returns:
the identification string of the map layer.

getLevel

public int getLevel()
Description copied from interface: Layer
Returns the level of the map layer in a hierarchical model.

Specified by:
getLevel in interface Layer
Returns:
the level of the map layer in a hierarchical model.

getMapDistance

public double getMapDistance(int x1,
                             int y1,
                             int x2,
                             int y2)

getMapDistance

public double getMapDistance(int x1,
                             int y1,
                             int z1,
                             int x2,
                             int y2,
                             int z2)
Description copied from interface: Layer
Returns the distance between two units on the map grid.

Specified by:
getMapDistance in interface Layer
Parameters:
x1 - the horizontal position of the first unit.
y1 - the vertical position of the first unit.
z1 - the height position of the first unit.
x2 - the horizontal position of the second unit.
y2 - the vertical position of the second unit.
z2 - the height position of the second unit.
Returns:
the distance between two units.

getMapDistance

public double getMapDistance(Unit u1,
                             Unit u2)
Description copied from interface: Layer
Returns the distance between two units on the map grid.

Specified by:
getMapDistance in interface Layer
Parameters:
u1 - the first unit.
u2 - the second unit.
Returns:
the distance between two units.

getMapDistanceSq

public double getMapDistanceSq(int x1,
                               int y1,
                               int z1,
                               int x2,
                               int y2,
                               int z2)

getMapDistanceSq

public double getMapDistanceSq(Unit u1,
                               Unit u2)

getMetric

public DistanceMetric getMetric()
Calculates and returns the mean quantization error of the map based on the quantization errors of the single units.

Specified by:
getMetric in interface Layer
Returns:
the mean quantization error of the map, or 0 if no data is mapped.

getMostDissimilarNeighbor

protected Unit getMostDissimilarNeighbor(Unit u)
Returns the neighboring unit of a unit specified by argument u with the most distant weight vector.

Parameters:
u - the unit for which the most dissimilar neighbor should be determined.
Returns:
the neighboring unit with the most distant weight vector.

getQualityMeasure

public QualityMeasure getQualityMeasure()
Description copied from interface: Layer
Returns the quality information.

Specified by:
getQualityMeasure in interface Layer
Returns:
the quality information, or null if not existent.

getRevision

public String getRevision()
Description copied from interface: Layer
Returns the revision string of this layer. This string should be written to output files to be able to trace back the implementation revision based on the CVS revision a map was trained with.

Specified by:
getRevision in interface Layer
Returns:
the revision string of this layer.

getSuperUnit

public Unit getSuperUnit()
Returns the superordinate unit, or null if none exists.

Returns:
the superordinate unit, or null if none exists.

getUnit

public Unit getUnit(int x,
                    int y)
             throws LayerAccessException
Description copied from interface: Layer
Returns the Unit at the position specified by the x and y arguments. A LayerAccessException is thrown, if the coordinates are invalid.

Specified by:
getUnit in interface Layer
Parameters:
x - the horizontal position on the map layer.
y - the vertical position on the map layer.
Returns:
the unit at the specified position.
Throws:
LayerAccessException - if the coordinates are out of range.

getUnit

public Unit getUnit(int x,
                    int y,
                    int z)
             throws LayerAccessException
Description copied from interface: Layer
Returns the Unit at the position specified by the x and y arguments. A LayerAccessException is thrown, if the coordinates are invalid.

Specified by:
getUnit in interface Layer
Parameters:
x - the horizontal position on the map layer.
y - the vertical position on the map layer.
z - TODO
Returns:
the unit at the specified position.
Throws:
LayerAccessException - if the coordinates are out of range.

getUnitIndex

public int getUnitIndex(int x,
                        int y)
Returns the index of given unit coordinates. The index is equivalent to the index of the unit in question in the array returned by getAllUnits().


getUnitForIndex

public Unit getUnitForIndex(int index)
                     throws LayerAccessException
Throws:
LayerAccessException

getUnitForDatum

public Unit getUnitForDatum(String name)
Description copied from interface: Layer
Returns the unit onto which the datum specified by its name by argument name is mapped.

Specified by:
getUnitForDatum in interface Layer
Parameters:
name - the name of the input datum to be searched for.
Returns:
the unit onto which the datum is mapped, or null if the datum is not found on the map.

getWinner

public Unit getWinner(InputDatum input,
                      DistanceMetric metric)
Returns the winner unit for a given input datum specified by argument input.

Parameters:
input - the input datum for which the winner unit will be searched.
metric - the metric to be used.
Returns:
the winner unit.

getWinner

public Unit getWinner(InputDatum input,
                      AbstractWeightedMetric metric)
Returns the winner for a given unit, using a weighted distance metric. Used for semi-supervised/active learning & correcting input locations.


getWinner

public Unit getWinner(InputDatum input)
Returns the winner unit for a given input datum specified by argument input.

Parameters:
input - the input datum for which the winner unit will be searched.
Returns:
the winner unit.

getWinnerFromQuery

public Unit getWinnerFromQuery(String query,
                               SOMLibTemplateVector templateVector)
Return the winning unit for the given query.


getWinnersFromQuery

public Unit[] getWinnersFromQuery(String query,
                                  int num,
                                  SOMLibTemplateVector templateVector)

getWinningInputDataFromQuery

public String[] getWinningInputDataFromQuery(String query,
                                             int num,
                                             SOMLibTemplateVector templateVector)

getInputVector

private double[] getInputVector(String query,
                                SOMLibTemplateVector templateVector)

getWinners

public Unit[] getWinners(InputDatum input,
                         int num,
                         DistanceMetric metric)
Returns a number of best-matching units sorted by distance (ascending) for a given input datum. If the number of best-matching units is greater than the total number of units on the map, all units of the map are returned (appropriately ranked).

Parameters:
input - the input datum for which the best-matching units will be searched.
num - the number of best-matching units.
Returns:
an array of Unit containing best-matching units sorted ascending by distance from the input datum.

getWinners

public Unit[] getWinners(InputDatum input,
                         int num)

getWinnersAndDistances

public UnitDistance[] getWinnersAndDistances(InputDatum input,
                                             int num)
Returns a number of best-matching units and distances sorted by distance (ascending) for a given input datum. If the number of best-matching units is greater than the total number of units on the map, all units of the map are returned (appropriately ranked).

Parameters:
input - the input datum for which the winner unit will be searched.
num - the number of best-matching units.
Returns:
the Vector containing an array of Unit (elementAt(0)) and array of double (elementAt(1)) containing best-matching units sorted ascending by distance from the input datum.

getXSize

public int getXSize()
Description copied from interface: Layer
Returns the width of the map layer.

Specified by:
getXSize in interface Layer
Returns:
the width of the map layer.

getYSize

public int getYSize()
Description copied from interface: Layer
Returns the height of the map layer.

Specified by:
getYSize in interface Layer
Returns:
the height of the map layer.

getZSize

public int getZSize()
Description copied from interface: Layer
Returns the depth of the map layer.

Specified by:
getZSize in interface Layer
Returns:
the depth of the map layer.

getUnitCount

public int getUnitCount()

hasNeighbours

public boolean hasNeighbours(int x,
                             int y)
                      throws LayerAccessException
Throws:
LayerAccessException

hasNeighbours

public boolean hasNeighbours(int x,
                             int y,
                             int z)
                      throws LayerAccessException
Throws:
LayerAccessException

isEdgeColumn

public boolean isEdgeColumn(int x)
                     throws LayerAccessException
Throws:
LayerAccessException

isEdgeRow

public boolean isEdgeRow(int y)
                  throws LayerAccessException
Throws:
LayerAccessException

insertRowColumn

private void insertRowColumn(Unit a,
                             Unit b,
                             ProgressListener listener)
Inserts a row or column of units between units specified by argument a and b.

Parameters:
a - a unit on the layer.
b - a unit on the layer.

mapCompleteDataAfterTraining

private void mapCompleteDataAfterTraining(InputData data)
Maps data onto layer without recalculating the quantization error after every single input datum.
FIXME: add multi-threading

Parameters:
data - input data to be mapped onto layer.

mapData

public void mapData(InputData data)
Maps input data onto layer. Quantization errors of units are updated automatically. This is slow for a large number of input data.

Parameters:
data - input data to be mapped onto layer.

mapDatum

public Unit mapDatum(InputDatum datum)
Maps a single input datum onto the layer and returns the winning unit.

Parameters:
datum - input datum to be mapped onto the layer.
Returns:
the winner unit.

setTrainingInterruptionListener

public void setTrainingInterruptionListener(TrainingInterruptionListener t,
                                            int i)
Assigns an object that implements the TrainingInterruptionListener interface to perform actions in certain intervals during training determined by argument i.

Parameters:
t - the listening object.
i - the number of training cycles after which the training process is interrupted.

train

public QualityMeasure train(InputData data,
                            double iniLearnrate,
                            double iniSigma,
                            int numIterations,
                            double tau,
                            String qualityMeasureName,
                            SOMProperties trainingProps)
Trains the layer with the input data. If the value of argument tau is 1, a fix-sized layer is trained, otherwise the layer grows until a certain quality criterion determined by tau and the mean quantization error of the data (which is automatically calculated) is reached. The process ends with all training data being mapped onto the growing SOM. The units' quantization errors are calculated.

Parameters:
data - input data to train the layer with.
iniLearnrate - initial value of learnrate.
iniSigma - initial sigma determining the neighborhood of the winner.
numIterations - the number of iterations until the mapping quality check.
tau - the fraction of the map's quantization error that determines the quality of the mapping.

train

public QualityMeasure train(InputData data,
                            double iniLearnrate,
                            double iniSigma,
                            int numIterations,
                            int startIteration,
                            double tau,
                            String qualityMeasureName,
                            SOMProperties trainingProps)
Trains the layer with the input data. If the value of argument tau is 1, a fix-sized layer is trained, otherwise the layer grows until a certain quality criterion determined by tau and the mean quantization error of the data (which is automatically calculated) is reached. The process ends with all training data being mapped onto the growing SOM. The units' quantization errors are calculated.

Parameters:
data - input data to train the layer with.
iniLearnrate - initial value of learnrate.
iniSigma - initial sigma determining the neighborhood of the winner.
numIterations - the number of iterations until the mapping quality check.
startIteration - start with iteration x -- important for Lernrate / Sigma calculation
tau - the fraction of the map's quantization error that determines the quality of the mapping.

train

public QualityMeasure train(InputData data,
                            double initialLearnrate,
                            double initialSigma,
                            int numIterations,
                            double tau,
                            double targetQualityValue,
                            String qualityMeasureName,
                            SOMProperties trainingProps)
Trains the layer with the input data. If the value of argument tau is 1, a fix-sized layer is trained, otherwise the layer grows until a certain quality criterion determined by tau and the mean quantization error specified by argument mqe0 is reached. The process ends with all training data being mapped onto the growing SOM. The units' quantization errors are calculated.

Parameters:
data - input data to train the layer with.
initialLearnrate - initial value of learnrate.
initialSigma - initial sigma determining the neighbourhood of the winner.
numIterations - the number of iterations until the mapping quality check.
tau - the fraction of the map's quantisation error that determines the quality of the mapping.
targetQualityValue - mean quantisation error determining the desired granularity of data representation. Used for layers in GHSOMs.

train

public QualityMeasure train(InputData data,
                            double initialLearnrate,
                            double initialSigma,
                            int numIterations,
                            int startIteration,
                            double tau,
                            double targetQualityValue,
                            String qualityMeasureName,
                            SOMProperties trainingProps)
Trains the layer with the input data. If the value of argument tau is 1, a fix-sized layer is trained, otherwise the layer grows until a certain quality criterion determined by tau and the mean quantization error specified by argument mqe0 is reached. The process ends with all training data being mapped onto the growing SOM. The units' quantization errors are calculated.

Parameters:
data - input data to train the layer with.
numIterations - the number of iterations until the mapping quality check.
startIteration - start with iteration x -- important for Learnrate / Sigma calculation
tau - the fraction of the map's quantisation error that determines the quality of the mapping.
targetQualityValue - mean quantisation error determining the desired granularity of data representation. Used for layers in GHSOMs.
initialLearnrate - initial value of learnrate.
initialSigma - initial sigma determining the neighbourhood of the winner.

trainSpecial

private void trainSpecial(InputData data,
                          int numIterations,
                          int startIteration,
                          SOMProperties trainingProps,
                          double initialLearnrate,
                          double initialSigma,
                          double expParam,
                          double expParam2,
                          SOMLibClassInformation classInfo,
                          double minProbability,
                          ProgressListener progressWriter)

trainNormal

private void trainNormal(InputData data,
                         int numIterations,
                         int startIteration,
                         SOMProperties trainingProps,
                         double initialLearnrate,
                         double initialSigma,
                         double expParam,
                         double expParam2,
                         ProgressListener progressWriter)

specialClassMode

private boolean specialClassMode(SOMProperties trainingProps)

initCPURanges

private void initCPURanges()

printInfo

private void printInfo(double targetQualityValue,
                       String[] qmNameMethod,
                       QualityMeasure qm)
                throws QualityMeasureNotFoundException
Throws:
QualityMeasureNotFoundException

updateUnits

private void updateUnits(Unit winner,
                         InputDatum input,
                         double learnrate,
                         double sigma)

updateUnitsNoBorder

private void updateUnitsNoBorder(Unit winner,
                                 InputDatum input,
                                 double learnrate,
                                 double sigma)
Updates the weight vectors of the all map units with respect to the input datum and the according winner unit. NO BORDER

Parameters:
winner - the winner unit.
input - the input datum.
learnrate - the learnrate.
sigma - the width of the Gaussian determining the neighborhood radius.

updateUnitsNormal

protected void updateUnitsNormal(Unit winner,
                                 InputDatum input,
                                 double learnrate,
                                 double sigma)
Updates the weight vectors of the all map units with respect to the input datum and the according winner unit.

Parameters:
winner - the winner unit.
input - the input datum.
learnrate - the learnrate.
sigma - the width of the Gaussian determining the neighborhood radius.

updateUnitsInArea

private void updateUnitsInArea(Unit winner,
                               double learnrate,
                               double opt1,
                               double[] inputVector,
                               Cuboid range)

updateUnitsInArea

private void updateUnitsInArea(Unit winner,
                               double learnrate,
                               double opt1,
                               double[] inputVector,
                               int startX,
                               int endX,
                               int startY,
                               int endY,
                               int startZ,
                               int endZ)

getNumberOfNotEmptyUnits

public int getNumberOfNotEmptyUnits()
                             throws LayerAccessException
Calculates and returns the number of units that are not empty, i.e. that have at least one input mapped.

Throws:
LayerAccessException

setQualityMeasure

public void setQualityMeasure(String qualityMeasureName)

getData

public InputData getData()

getNNearestInputs

public String[] getNNearestInputs(String datumlabel,
                                  int n,
                                  InputData data)
                           throws LayerAccessException,
                                  MetricException
Throws:
LayerAccessException
MetricException

getNNearestInputs

public String[] getNNearestInputs(Unit u,
                                  int n)
                           throws LayerAccessException
Throws:
LayerAccessException

getFirstNLabels

private String[] getFirstNLabels(int n,
                                 ArrayList<InputNameDistance> items)

getNeighbouringUnits

protected ArrayList<Unit> getNeighbouringUnits(Unit u)
                                        throws LayerAccessException
Get direct neighbours of the given unit. Direct neighbours are neighbours in the same column or row of the SOM, thus this method returns at most six neighbours (two for each of the x, y and z dimensions).

Throws:
LayerAccessException

getNeighbouringUnits

public ArrayList<Unit> getNeighbouringUnits(int x,
                                            int y)
                                     throws LayerAccessException
Throws:
LayerAccessException

getNeighbouringUnits

private ArrayList<Unit> getNeighbouringUnits(int x,
                                             int y,
                                             int z)
                                      throws LayerAccessException
Throws:
LayerAccessException

getNeighbouringUnits

protected ArrayList<Unit> getNeighbouringUnits(Unit u,
                                               double radius)
                                        throws LayerAccessException
Convenience method for getNeighbouringUnits(int, int, int, double)

Throws:
LayerAccessException

getNeighbouringUnits

public ArrayList<Unit> getNeighbouringUnits(int x,
                                            int y,
                                            double radius)
                                     throws LayerAccessException
Convenience method for getNeighbouringUnits(int, int, int, double)

Throws:
LayerAccessException

getNeighbouringUnits

public ArrayList<Unit> getNeighbouringUnits(int x,
                                            int y,
                                            int z,
                                            double radius)
                                     throws LayerAccessException
Gets neighbours within a certain radius; uses getMapDistance(int, int, int, int, int, int) for map distance computation

Throws:
LayerAccessException

getUnitDistanceMatrix

public cern.colt.matrix.DoubleMatrix2D getUnitDistanceMatrix()
Computes a distance matrix between all Units in the Layer


isValidUnitLocation

public boolean isValidUnitLocation(Point pos)

isValidUnitLocation

public boolean isValidUnitLocation(int x,
                                   int y)

getNumberOfMappedInputs

public int getNumberOfMappedInputs()
Description copied from interface: Layer
Returns the total number of Inputs mapped on all units in the map layer.

Specified by:
getNumberOfMappedInputs in interface Layer

computeUnitFeatureWeights

public InputCorrections computeUnitFeatureWeights(InputCorrections corrections,
                                                  InputData data,
                                                  Unit.FeatureWeightMode mode)
                                           throws SOMToolboxException
Implementation of general weighting as in Nünrberger/Detyniecki, 'Weighted Self-Organizing Maps: Incorporating User Feedback'

Throws:
SOMToolboxException

maxNeighbourhoodRadius

public double maxNeighbourhoodRadius()
Computes the maximum value the neighbourhood radius can take, that is in the diagonal from one corner to the other.
Computed as Mth.sqrt(xSize^2 + ySize^2), and rounded up to the next higher decimal place.


neighbourhoodFeatureWeight

public double neighbourhoodFeatureWeight(double dist,
                                         int maxDist)

getNO_CPUS

public static int getNO_CPUS()

setNO_CPUS

public static void setNO_CPUS(int no_cpus)

flip

public void flip(GrowingLayer.Flip flip)
Flip the layer.


rotate

public void rotate(int rotation)
            throws SOMToolboxException
Throws:
SOMToolboxException

rotate

public void rotate(GrowingLayer.Rotation rotation)
Clockwise rotate the layer by the given degrees.


checkRotation

public static void checkRotation(int rotation)
                          throws SOMToolboxException
Throws:
SOMToolboxException

printUnitIndices

public String printUnitIndices()

printSize

public String printSize()

setCommonVectorLabelPrefix

public void setCommonVectorLabelPrefix(String commonVectorLabelPrefix)

getCommonVectorLabelPrefix

public String getCommonVectorLabelPrefix()

getGridLayout

public Layer.GridLayout getGridLayout()
Specified by:
getGridLayout in interface Layer

getGridTopology

public Layer.GridTopology getGridTopology()
Specified by:
getGridTopology in interface Layer

setGridLayout

public void setGridLayout(Layer.GridLayout gridLayout)

setGridTopology

public void setGridTopology(Layer.GridTopology gridTopology)

clone

public Object clone()
             throws CloneNotSupportedException
Clone might not be fully functional!

Overrides:
clone in class Object
Throws:
CloneNotSupportedException
See Also:
Object.clone()

getVirtualLayer

public AdaptiveCoordinatesVirtualLayer getVirtualLayer()