
 Usage

This class takes as input an optional vtkTable on port
LEARN_PARAMETERS specifying initial set(s) of cluster values
of the following form:

             K     | Col1            |  ...    | ColN

  &mdash;&mdash;&mdash;&ndash;+&mdash;&mdash;&mdash;&mdash;&mdash;&ndash;+&mdash;&mdash;&mdash;+&mdash;&mdash;&mdash;&mdash;&mdash;
             M     |clustCoord(1, 1) |  ...    | clustCoord
  (1, N)
             M     |clustCoord(2, 1) |  ...    | clustCoord
  (2, N)
             .     |       .         |   .     |        .
             .     |       .         |   .     |        .
             .     |       .         |   .     |        .
             M     |clustCoord(M, 1) |  ...    | clustCoord
  (M, N)
             L     |clustCoord(1, 1) |  ...    | clustCoord
  (1, N)
             L     |clustCoord(2, 1) |  ...    | clustCoord
  (2, N)
             .     |       .         |   .     |        .
             .     |       .         |   .     |        .
             .     |       .         |   .     |        .
             L     |clustCoord(L, 1) |  ...    | clustCoord
  (L, N)

Because the desired value of K is often not known in advance
and the results of the algorithm are dependent on the
initial cluster centers, we provide a mechanism for the user
to test multiple runs or sets of cluster centers within a
single call to the Learn phase. The first column of the
table identifies the number of clusters K in the particular
run (the entries in this column should be of type
vtkIdType), while the remaining columns are a subset of the
columns contained in the table on port INPUT_DATA. We
require that all user specified clusters be of the same
dimension N and consequently, that the LEARN_PARAMETERS
table have N+1 columns. Due to this restriction, only one
request can be processed for each call to the Learn phase
and subsequent requests are silently ignored. Note that, if
the first column of the LEARN_PARAMETERS table is not of
type vtkIdType, then the table will be ignored and a single
run will be performed using the first
DefaultNumberOfClusters input data observations as initial
cluster centers.
When the user does not supply an initial set of clusters,
then the first DefaultNumberOfClusters input data
observations are used as initial cluster centers and a
single run is performed.
This class provides the following functionalities, depending
on the mode it is executed in: Learn: calculates new cluster
centers for each run. The output metadata on port
OUTPUT_MODEL is a multiblock dataset containing at a minimum
one vtkTable with columns specifying the following for each
run: the run ID, number of clusters, number of iterations
required for convergence, total error associated with the
cluster (sum of squared Euclidean distance from each
observation to its nearest cluster center), the cardinality
of the cluster, and the new cluster coordinates.
*Derive: An additional vtkTable is stored in the multiblock
dataset output on port OUTPUT_MODEL. This table contains
columns that store for each run: the runID, number of
clusters, total error for all clusters in the run, local
rank, and global rank. The local rank is computed by
comparing squared Euclidean errors of all runs with the same
number of clusters. The global rank is computed analagously
across all runs.
Assess: This requires a multiblock dataset (as computed from
Learn and Derive) on input port INPUT_MODEL and tabular data
on input port INPUT_DATA that contains column names matching
those of the tables on input port INPUT_MODEL. The assess
mode reports the closest cluster center and associated
squared Euclidean distance of each observation in port
INPUT_DATA's table to the cluster centers for each run in
the multiblock dataset provided on port INPUT_MODEL.
The code can handle a wide variety of data types as it
operates on vtkAbstractArrays and is not limited to
vtkDataArrays. A default distance functor that computes the
sum of the squares of the Euclidean distance between two
objects is provided (vtkKMeansDistanceFunctor). The default
distance functor can be overridden to use alternative
distance metrics.
.SECTION Thanks Thanks to Janine Bennett, David Thompson,
and Philippe Pebay of Sandia National Laboratories for
implementing this class.
To create an instance of class vtkKMeansStatistics, simply
invoke its constructor as follows

    obj = vtkKMeansStatistics



 Methods

The class vtkKMeansStatistics has several methods that can
be used. They are listed below. Note that the documentation
is translated automatically from the VTK sources, and may
not be completely intelligible. When in doubt, consult the
VTK website. In the methods listed below, obj is an instance
of the vtkKMeansStatistics class.

* string = obj.GetClassName ()
* int = obj.IsA (string name)
* vtkKMeansStatistics = obj.NewInstance ()
* vtkKMeansStatistics = obj.SafeDownCast (vtkObject o)
* obj.SetDistanceFunctor (vtkKMeansDistanceFunctor ) - Set
  the DistanceFunctor.
* vtkKMeansDistanceFunctor = obj.GetDistanceFunctor () - Set
  the DistanceFunctor.
* obj.SetDefaultNumberOfClusters (int ) - Set/get the
  DefaultNumberOfClusters, used when no initial cluster
  coordinates are specified.
* int = obj.GetDefaultNumberOfClusters () - Set/get the
  DefaultNumberOfClusters, used when no initial cluster
  coordinates are specified.
* obj.SetKValuesArrayName (string ) - Set/get the
  KValuesArrayName.
* string = obj.GetKValuesArrayName () - Set/get the
  KValuesArrayName.
* obj.SetMaxNumIterations (int ) - Set/get the
  MaxNumIterations used to terminate iterations on cluster
  center coordinates when the relative tolerance can not be
  met.
* int = obj.GetMaxNumIterations () - Set/get the
  MaxNumIterations used to terminate iterations on cluster
  center coordinates when the relative tolerance can not be
  met.
* obj.SetTolerance (double ) - Set/get the relative
  Tolerance used to terminate iterations on cluster center
  coordinates.
* double = obj.GetTolerance () - Set/get the relative
  Tolerance used to terminate iterations on cluster center
  coordinates.
* obj.Aggregate (vtkDataObjectCollection , vtkDataObject ) -
  Given a collection of models, calculate aggregate model
  NB: not implemented


* FreeMat_Documentation
* Visualization_Toolkit_Infovis_Classes
* Generated on Thu Jul 25 2013 17:18:33 for FreeMat by
  doxygen_ 1.8.1.1

