Package weka.clusterers

# Class AbstractClusterer

java.lang.Object
weka.clusterers.AbstractClusterer

All Implemented Interfaces:
  `Serializable`, `Cloneable`, `Clusterer`, `CapabilitiesHandler`, `CapabilitiesIgnorer`, `CommandlineRunnable`, `OptionHandler`, `RevisionHandler`

Direct Known Subclasses:
  `AbstractDensityBasedClusterer`, `HierarchicalClusterer`, `RandomizableClusterer`, `RandomizableSingleClustererEnhancer`, `SingleClustererEnhancer`

public abstract class AbstractClusterer extends Object implements Clusterer, Cloneable, Serializable, CapabilitiesHandler, RevisionHandler, OptionHandler, CapabilitiesIgnorer, CommandlineRunnable
Abstract clusterer.

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

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `AbstractClusterer()`

- ## Method Summary

  Modifier and Type
  Method
  Description
  `abstract void`
  `buildClusterer(Instances data)`
  Generates a clusterer.
  `int`
  `clusterInstance(Instance instance)`
  Classifies a given instance.
  `String`
  `debugTipText()`
  Returns the tip text for this property
  `double[]`
  `distributionForInstance(Instance instance)`
  Predicts the cluster memberships for a given instance.
  `String`
  `doNotCheckCapabilitiesTipText()`
  Returns the tip text for this property
  `static Clusterer`
  `forName(String clustererName, 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.
  `String[]`
  `getOptions()`
  Gets the current settings of the clusterer.
  `String`
  `getRevision()`
  Returns the revision string.
  `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(Object toRun, String[] options)`
  Execute the supplied object.
  `static void`
  `runClusterer(Clusterer clusterer, 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(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 Details

  - ### AbstractClusterer

    public AbstractClusterer()

- ## Method Details

  - ### buildClusterer

    public abstract void buildClusterer(Instances data) throws 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:
      `Exception` - if the clusterer has not been generated successfully

  - ### clusterInstance

    public int clusterInstance(Instance instance) throws 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:
      `Exception` - if instance could not be clustered successfully

  - ### distributionForInstance

    public double[] distributionForInstance(Instance instance) throws 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:
      `Exception` - if distribution could not be computed successfully

  - ### numberOfClusters

    public abstract int numberOfClusters() throws Exception
    Returns the number of clusters.
    Specified by:
      `numberOfClusters` in interface `Clusterer`
    Returns:
      the number of clusters generated for a training dataset.
    Throws:
      `Exception` - if number of clusters could not be returned successfully

  - ### listOptions

    public 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(String[] options) throws 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:
      `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 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 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 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(String clustererName, String[] options) throws 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:
      `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 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:
      `Exception` - if an error occurs

  - ### makeCopies

    public static Clusterer[] makeCopies(Clusterer model, int num) throws 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:
      `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 `CapabilitiesHandler`
    Specified by:
      `getCapabilities` in interface `Clusterer`
    Returns:
      the capabilities of this object
    See Also:
      - `Capabilities`

  - ### getRevision

    public String getRevision()
    Returns the revision string.
    Specified by:
      `getRevision` in interface `RevisionHandler`
    Returns:
      the revision

  - ### runClusterer

    public static void runClusterer(Clusterer clusterer, 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 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:
      `Exception` - if a problem occurs during setup

  - ### run

    public void run(Object toRun, String[] options) throws 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:
      `Exception` - if the object if a problem occurs

  - ### postExecution

    public void postExecution() throws 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:
      `Exception` - if a problem occurs during teardown