edu.ucla.sspace.clustering

Class ClusteringByCommittee

java.lang.Object

edu.ucla.sspace.clustering.ClusteringByCommittee

All Implemented Interfaces:

Clustering

public class ClusteringByCommittee
extends Object
implements Clustering

An implementation of the Clustering by Committee (CBC) algorithm. This implementation is based on the Pantel's thesis:

• Patrick Pantel. 2003. Clustering by Committee. Ph.D. Dissertation. Department of Computing Science, University of Alberta, Canada. available here.

This class offers five parameters for configuring how the clustering occurs

Property: "edu.ucla.sspace.clustering.ClusteringByCommittee.averageLinkMergeThreshold"
Default: ".25"

The property to specify during the Phase II.1 when to stop the agglomerative clustering of the nearest neighbors. This property specifies a double threshold where clusters whose the average-link similarity falls below the value will not be merged (i.e. stay two clusters).

Property: "edu.ucla.sspace.clustering.ClusteringByCommittee.maxCommitteeSimilarity"
Default: ".35"

The property to specify during Phase II.3 what is the maximum similarity between two committees above which a new committee will not be included. This property corresponds to θ-1 in the CBC papers. This property specifies a double.

Property: "edu.ucla.sspace.clustering.ClusteringByCommittee.residueSimilarityThreshold"
Default: ".25"

The property for specifying the similarity threshold in Phase II.5 where if an element has a similarity less than this threshold to all existing committees, the element is marked as "residue" and recursively clustered. This property corresponds to the θ-2 parameter in the original papers. The property is specified as a double.

Property: "edu.ucla.sspace.clustering.ClusteringByCommittee.useHardClustering"
Default: true

Specifies whether CBC should use a hard (single class) or soft (multi-class) cluster labeling. The default behavior is to use hard clustering.

Property: "edu.ucla.sspace.clustering.ClusteringByCommittee.softClusteringThreshold"
Default: ".25"

If soft clustering is enabled, specifies a double the threshold used during soft clustering where a point will not be labeled with the committees who are more similar than this value. If hard clustering is enabled the value of this property has no effect. See Phrase III of the CBC algorithm for more details.

This class is thread-safe.

Author:

David Jurgens

Field Summary

Fields

Modifier and Type	Field and Description
static String	AVERGAGE_LINK_MERGE_THRESHOLD_PROPERTY The property to specify during the Phase II.1 when to stop the agglomerative clustering of the nearest neighbors.
static String	COMMITTEE_SIMILARITY_THRESHOLD_PROPERTY The property to specify during Phase II.3 what is the maximum similarity between two committees above which a new committee will not be included.
static String	DEFAULT_AVERGAGE_LINK_MERGE_THRESHOLD The default value of the "edu.ucla.sspace.clustering.ClusteringByCommittee.averageLinkMergeThreshold" property.
static String	DEFAULT_COMMITTEE_SIMILARITY_THRESHOLD The default value of the "edu.ucla.sspace.clustering.ClusteringByCommittee.maxCommitteeSimilarity" property.
static String	DEFAULT_RESIDUE_SIMILARITY_THRESHOLD The default value of the "edu.ucla.sspace.clustering.ClusteringByCommittee.residueSimilarityThreshold" property.
static String	DEFAULT_SOFT_CLUSTERING_SIMILARITY_THRESHOLD The default value of the "edu.ucla.sspace.clustering.ClusteringByCommittee.softClusteringThreshold" property.
static String	HARD_CLUSTERING_PROPERTY Specifies whether CBC should use a hard (single class) or soft (multi-class) cluster labeling.
static String	RESIDUE_SIMILARITY_THRESHOLD_PROPERTY The property for specifying the similarity threshold in Phase II.5 where if an element has a similarity less than this threshold to all existing committees, the element is marked as "residue" and recursively clustered.
static String	SOFT_CLUSTERING_SIMILARITY_THRESHOLD_PROPERTY The property for specifying a double the threshold used during soft clustering where a point will not be labeled with the committees who are more similar than this value.

Constructor Summary

Constructors

Constructor and Description
ClusteringByCommittee() Creates a new ClusteringByCommittee instance

Method Summary

Methods

Modifier and Type	Method and Description
static List<edu.ucla.sspace.clustering.ClusteringByCommittee.CandidateCommittee>	buildCommitteesForRow(Collection<Integer> rows, SparseMatrix sm, double avgLinkMergeThresh) Builds a set of candidate committees from the clusters formed by the average-link clustering of the provided rows.
Assignments	cluster(Matrix m, int numClusters, Properties props) Ignores the provided number of clusters and clusters the rows of the provided matrix using the CBC algorithm.
Assignments	cluster(Matrix m, Properties props) Clusters the rows of m according to the CBC algorithm, using props to specify the configurable parameters of the algorithm.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

AVERGAGE_LINK_MERGE_THRESHOLD_PROPERTY

public static final String AVERGAGE_LINK_MERGE_THRESHOLD_PROPERTY

The property to specify during the Phase II.1 when to stop the agglomerative clustering of the nearest neighbors. This property specifies a double threshold where clusters whose the average-link similarity falls below the value will not be merged (i.e. stay two clusters).

See Also:

Constant Field Values

DEFAULT_AVERGAGE_LINK_MERGE_THRESHOLD

public static final String DEFAULT_AVERGAGE_LINK_MERGE_THRESHOLD

The default value of the "edu.ucla.sspace.clustering.ClusteringByCommittee.averageLinkMergeThreshold" property.

See Also:

Constant Field Values

COMMITTEE_SIMILARITY_THRESHOLD_PROPERTY

public static final String COMMITTEE_SIMILARITY_THRESHOLD_PROPERTY

The property to specify during Phase II.3 what is the maximum similarity between two committees above which a new committee will not be included. This property corresponds to θ-1 in the CBC papers. This property specifies a double.

See Also:

Constant Field Values

DEFAULT_COMMITTEE_SIMILARITY_THRESHOLD

public static final String DEFAULT_COMMITTEE_SIMILARITY_THRESHOLD

The default value of the "edu.ucla.sspace.clustering.ClusteringByCommittee.maxCommitteeSimilarity" property.

See Also:

Constant Field Values

RESIDUE_SIMILARITY_THRESHOLD_PROPERTY

public static final String RESIDUE_SIMILARITY_THRESHOLD_PROPERTY

The property for specifying the similarity threshold in Phase II.5 where if an element has a similarity less than this threshold to all existing committees, the element is marked as "residue" and recursively clustered. This property corresponds to the θ-2 parameter in the original papers. The property is specified as a double.

See Also:

Constant Field Values

DEFAULT_RESIDUE_SIMILARITY_THRESHOLD

public static final String DEFAULT_RESIDUE_SIMILARITY_THRESHOLD

The default value of the "edu.ucla.sspace.clustering.ClusteringByCommittee.residueSimilarityThreshold" property.

See Also:

Constant Field Values

SOFT_CLUSTERING_SIMILARITY_THRESHOLD_PROPERTY

public static final String SOFT_CLUSTERING_SIMILARITY_THRESHOLD_PROPERTY

The property for specifying a double the threshold used during soft clustering where a point will not be labeled with the committees who are more similar than this value. See Phrase III of the CBC algorithm for more details.

See Also:

Constant Field Values

DEFAULT_SOFT_CLUSTERING_SIMILARITY_THRESHOLD

public static final String DEFAULT_SOFT_CLUSTERING_SIMILARITY_THRESHOLD

The default value of the "edu.ucla.sspace.clustering.ClusteringByCommittee.softClusteringThreshold" property.

See Also:

Constant Field Values

HARD_CLUSTERING_PROPERTY

public static final String HARD_CLUSTERING_PROPERTY

Specifies whether CBC should use a hard (single class) or soft (multi-class) cluster labeling. The default is to use hard clustering.

See Also:

Constant Field Values

Constructor Detail

ClusteringByCommittee

public ClusteringByCommittee()

Creates a new ClusteringByCommittee instance

Method Detail

cluster

public Assignments cluster(Matrix m,
                  int numClusters,
                  Properties props)

Ignores the provided number of clusters and clusters the rows of the provided matrix using the CBC algorithm. This method is equivalent to calling cluster(Matrix,Properties) without specifying the number of clusters.

Specified by:

cluster in interface Clustering

Parameters:

m - the Matrix whose row data points are to be clustered

numClusters - the number of clusters to generate

props - the properties to use for any parameters each clustering algorithm may need

Returns:

an array of Assignment instances that indicate zero or more clusters to which each row belongs.

Throws:

IllegalArgumentException - if m is not an instance of SparseMatrix.

cluster

public Assignments cluster(Matrix m,
                  Properties props)

Clusters the rows of m according to the CBC algorithm, using props to specify the configurable parameters of the algorithm.

Specified by:

cluster in interface Clustering

Parameters:

m - the Matrix whose row data points are to be clustered

props - the properties to use for any parameters each clustering algorithm may need

Returns:

an array of Assignment instances that indicate zero or more clusters to which each row belongs.

Throws:

IllegalArgumentException - if m is not an instance of SparseMatrix.

buildCommitteesForRow

public static List<edu.ucla.sspace.clustering.ClusteringByCommittee.CandidateCommittee> buildCommitteesForRow(Collection<Integer> rows,
                                                                                              SparseMatrix sm,
                                                                                              double avgLinkMergeThresh)

Builds a set of candidate committees from the clusters formed by the average-link clustering of the provided rows.

Parameters:

avgLinkMergThresh - the parameter used by HAC to determine when to stop merging clusters on the basis of their dissimilarity