weka.clusterers

## Class AbstractClusterer

- java.lang.Object
- - weka.clusterers.AbstractClusterer

- All Implemented Interfaces:
    java.io.Serializable, java.lang.Cloneable, Clusterer, CapabilitiesHandler, CapabilitiesIgnorer, CommandlineRunnable, OptionHandler, RevisionHandler
  Direct Known Subclasses:
    AbstractDensityBasedClusterer, HierarchicalClusterer, RandomizableClusterer, RandomizableSingleClustererEnhancer, SingleClustererEnhancer

      public abstract class AbstractClusterer
      extends java.lang.Object
      implements Clusterer, java.lang.Cloneable, java.io.Serializable, CapabilitiesHandler, RevisionHandler, OptionHandler, CapabilitiesIgnorer, CommandlineRunnable

  Abstract clusterer.
  Version:
    $Revision: 12201 $
  Author:
    Mark Hall (mhall@cs.waikato.ac.nz)
  See Also:
    Serialized Form

- - ### Constructor Summary

    Constructors
    Constructor and Description
    `AbstractClusterer()`

  - ### Method Summary

    All Methods Static Methods Instance Methods Abstract Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `abstract void` | `buildClusterer(Instances data)` Generates a clusterer.
    `int` | `clusterInstance(Instance instance)` Classifies a given instance.
    `java.lang.String` | `debugTipText()` Returns the tip text for this property
    `double[]` | `distributionForInstance(Instance instance)` Predicts the cluster memberships for a given instance.
    `java.lang.String` | `doNotCheckCapabilitiesTipText()` Returns the tip text for this property
    `static Clusterer` | `forName(java.lang.String clustererName, java.lang.String[] options)` Creates a new instance of a clusterer given it's class name and (optional) arguments to pass to it's setOptions method.
    `Capabilities` | `getCapabilities()` Returns the Capabilities of this clusterer.
    `boolean` | `getDebug()` Get whether debugging is turned on.
    `boolean` | `getDoNotCheckCapabilities()` Get whether capabilities checking is turned off.
    `java.lang.String[]` | `getOptions()` Gets the current settings of the clusterer.
    `java.lang.String` | `getRevision()` Returns the revision string.
    `java.util.Enumeration<Option>` | `listOptions()` Returns an enumeration describing the available options.
    `static Clusterer[]` | `makeCopies(Clusterer model, int num)` Creates copies of the current clusterer.
    `static Clusterer` | `makeCopy(Clusterer model)` Creates a deep copy of the given clusterer using serialization.
    `abstract int` | `numberOfClusters()` Returns the number of clusters.
    `void` | `postExecution()` Perform any teardown stuff that might need to happen after execution.
    `void` | `preExecution()` Perform any setup stuff that might need to happen before commandline execution.
    `void` | `run(java.lang.Object toRun, java.lang.String[] options)` Execute the supplied object.
    `static void` | `runClusterer(Clusterer clusterer, java.lang.String[] options)` runs the clusterer instance with the given options.
    `void` | `setDebug(boolean debug)` Set debugging mode.
    `void` | `setDoNotCheckCapabilities(boolean doNotCheckCapabilities)` Set whether not to check capabilities.
    `void` | `setOptions(java.lang.String[] options)` Parses a given list of options.

    - ### Methods inherited from class java.lang.Object

      `equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- - ### Constructor Detail

    - #### AbstractClusterer

          public AbstractClusterer()

  - ### Method Detail

    - #### buildClusterer

          public abstract void buildClusterer(Instances data)
                                       throws java.lang.Exception

      Generates a clusterer. Has to initialize all fields of the clusterer that are not being set via options.
      Specified by:
        `buildClusterer` in interface `Clusterer`
      Parameters:
        `data` - set of instances serving as training data
      Throws:
        `java.lang.Exception` - if the clusterer has not been generated successfully

    - #### clusterInstance

          public int clusterInstance(Instance instance)
                              throws java.lang.Exception

      Classifies a given instance. Either this or distributionForInstance() needs to be implemented by subclasses.
      Specified by:
        `clusterInstance` in interface `Clusterer`
      Parameters:
        `instance` - the instance to be assigned to a cluster
      Returns:
        the number of the assigned cluster as an integer
      Throws:
        `java.lang.Exception` - if instance could not be clustered successfully

    - #### distributionForInstance

          public double[] distributionForInstance(Instance instance)
                                           throws java.lang.Exception

      Predicts the cluster memberships for a given instance. Either this or clusterInstance() needs to be implemented by subclasses.
      Specified by:
        `distributionForInstance` in interface `Clusterer`
      Parameters:
        `instance` - the instance to be assigned a cluster.
      Returns:
        an array containing the estimated membership probabilities of the test instance in each cluster (this should sum to at most 1)
      Throws:
        `java.lang.Exception` - if distribution could not be computed successfully

    - #### numberOfClusters

          public abstract int numberOfClusters()
                                        throws java.lang.Exception

      Returns the number of clusters.
      Specified by:
        `numberOfClusters` in interface `Clusterer`
      Returns:
        the number of clusters generated for a training dataset.
      Throws:
        `java.lang.Exception` - if number of clusters could not be returned successfully

    - #### listOptions

          public java.util.Enumeration<Option> listOptions()

      Returns an enumeration describing the available options.
      Specified by:
        `listOptions` in interface `OptionHandler`
      Returns:
        an enumeration of all the available options.

    - #### setOptions

          public void setOptions(java.lang.String[] options)
                          throws java.lang.Exception

      Parses a given list of options. Valid options are:

      -D
      If set, clusterer is run in debug mode and may output additional info to the console.

      -do-not-check-capabilities
      If set, clusterer capabilities are not checked before clusterer is built (use with caution).

      Specified by:
        `setOptions` in interface `OptionHandler`
      Parameters:
        `options` - the list of options as an array of strings
      Throws:
        `java.lang.Exception` - if an option is not supported

    - #### setDebug

          public void setDebug(boolean debug)

      Set debugging mode.
      Parameters:
        `debug` - true if debug output should be printed

    - #### getDebug

          public boolean getDebug()

      Get whether debugging is turned on.
      Returns:
        true if debugging output is on

    - #### debugTipText

          public java.lang.String debugTipText()

      Returns the tip text for this property
      Returns:
        tip text for this property suitable for displaying in the explorer/experimenter gui

    - #### setDoNotCheckCapabilities

          public void setDoNotCheckCapabilities(boolean doNotCheckCapabilities)

      Set whether not to check capabilities.
      Specified by:
        `setDoNotCheckCapabilities` in interface `CapabilitiesIgnorer`
      Parameters:
        `doNotCheckCapabilities` - true if capabilities are not to be checked.

    - #### getDoNotCheckCapabilities

          public boolean getDoNotCheckCapabilities()

      Get whether capabilities checking is turned off.
      Specified by:
        `getDoNotCheckCapabilities` in interface `CapabilitiesIgnorer`
      Returns:
        true if capabilities checking is turned off.

    - #### doNotCheckCapabilitiesTipText

          public java.lang.String doNotCheckCapabilitiesTipText()

      Returns the tip text for this property
      Returns:
        tip text for this property suitable for displaying in the explorer/experimenter gui

    - #### getOptions

          public java.lang.String[] getOptions()

      Gets the current settings of the clusterer.
      Specified by:
        `getOptions` in interface `OptionHandler`
      Returns:
        an array of strings suitable for passing to setOptions

    - #### forName

          public static Clusterer forName(java.lang.String clustererName,
                                          java.lang.String[] options)
                                   throws java.lang.Exception

      Creates a new instance of a clusterer given it's class name and (optional) arguments to pass to it's setOptions method. If the clusterer implements OptionHandler and the options parameter is non-null, the clusterer will have it's options set.
      Parameters:
        `clustererName` - the fully qualified class name of the clusterer
        `options` - an array of options suitable for passing to setOptions. May be null.
      Returns:
        the newly created search object, ready for use.
      Throws:
        `java.lang.Exception` - if the clusterer class name is invalid, or the options supplied are not acceptable to the clusterer.

    - #### makeCopy

          public static Clusterer makeCopy(Clusterer model)
                                    throws java.lang.Exception

      Creates a deep copy of the given clusterer using serialization.
      Parameters:
        `model` - the clusterer to copy
      Returns:
        a deep copy of the clusterer
      Throws:
        `java.lang.Exception` - if an error occurs

    - #### makeCopies

          public static Clusterer[] makeCopies(Clusterer model,
                                               int num)
                                        throws java.lang.Exception

      Creates copies of the current clusterer. Note that this method now uses Serialization to perform a deep copy, so the Clusterer object must be fully Serializable. Any currently built model will now be copied as well.
      Parameters:
        `model` - an example clusterer to copy
        `num` - the number of clusterer copies to create.
      Returns:
        an array of clusterers.
      Throws:
        `java.lang.Exception` - if an error occurs

    - #### getCapabilities

          public Capabilities getCapabilities()

      Returns the Capabilities of this clusterer. Derived clusterers have to override this method to enable capabilities.
      Specified by:
        `getCapabilities` in interface `Clusterer`
      Specified by:
        `getCapabilities` in interface `CapabilitiesHandler`
      Returns:
        the capabilities of this object
      See Also:
        `Capabilities`

    - #### getRevision

          public java.lang.String getRevision()

      Returns the revision string.
      Specified by:
        `getRevision` in interface `RevisionHandler`
      Returns:
        the revision

    - #### runClusterer

          public static void runClusterer(Clusterer clusterer,
                                          java.lang.String[] options)

      runs the clusterer instance with the given options.
      Parameters:
        `clusterer` - the clusterer to run
        `options` - the commandline options

    - #### preExecution

          public void preExecution()
                            throws java.lang.Exception

      Perform any setup stuff that might need to happen before commandline execution. Subclasses should override if they need to do something here
      Specified by:
        `preExecution` in interface `CommandlineRunnable`
      Throws:
        `java.lang.Exception` - if a problem occurs during setup

    - #### run

          public void run(java.lang.Object toRun,
                          java.lang.String[] options)
                   throws java.lang.Exception

      Execute the supplied object. Subclasses need to override this method.
      Specified by:
        `run` in interface `CommandlineRunnable`
      Parameters:
        `toRun` - the object to execute
        `options` - any options to pass to the object
      Throws:
        `java.lang.Exception` - if the object if a problem occurs

    - #### postExecution

          public void postExecution()
                             throws java.lang.Exception

      Perform any teardown stuff that might need to happen after execution. Subclasses should override if they need to do something here
      Specified by:
        `postExecution` in interface `CommandlineRunnable`
      Throws:
        `java.lang.Exception` - if a problem occurs during teardown