com.chemaxon.clustering.sphex

Class SphereExclusion

java.lang.Object

com.chemaxon.clustering.sphex.SphereExclusion

@Beta
 @PublicAPI
public final class SphereExclusion
extends Object

Core functionality related to sphere exclusion clustering.

Licensing: this class is part of the JKlustor suite; it can be used with valid JKlustor license.

Please note that this class is marked with @Beta annotation, so it can be subject of incompatible changes or removal in later releases.

Method Summary

Modifier and Type	Method and Description
static IDBasedSingleLevelClustering	adaptiveSPHEX(int initialMinCC, int maxCC, DissimilarityInput di, ProgressObserver po) Sphere exclusion clustering with sphere radius inference.
static IDBasedSingleLevelClustering	fixedSPHEX(double radius, DissimilarityInput di, ProgressObserver po) Sphere exclusion clustering with defined sphere radius.
static Optional<int[]>	sphexCentroids(double r, int maxCC, DissimilarityInput di, ProgressObserver po) Identify SphereExclusion clustering based centroids for a given set.
static IDBasedSingleLevelClustering	sphexClassify(int[] centroids, DissimilarityInput di, ProgressObserver po) Classify input items into clusters determined by nearest centroids.

Methods inherited from class java.lang.Object

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

Method Detail

fixedSPHEX

public static IDBasedSingleLevelClustering fixedSPHEX(double radius,
                                                      DissimilarityInput di,
                                                      ProgressObserver po)
                                               throws CancellationException

Sphere exclusion clustering with defined sphere radius.

The returned clustring will reflect the given sphere radius, regardless of the found cluster count. If finer control is required over maximal cluster count then do centroid identification and classification steps separately.

Parameters:

radius - Sphere radius

di - input source

po - progress observer to update

Returns:

the clustering result

Throws:

CancellationException - if cancelled by the progress observer

IllegalArgumentException - on empty input or non positive radius

LicenseException - when appropriate license is not available

adaptiveSPHEX

public static IDBasedSingleLevelClustering adaptiveSPHEX(int initialMinCC,
                                                         int maxCC,
                                                         DissimilarityInput di,
                                                         ProgressObserver po)
                                                  throws CancellationException

Sphere exclusion clustering with sphere radius inference.

The returned cluster count is expected between the minimum and maximum expected value. This is aimed to be reached through optimization of sphere exclusion radius value. If minimum cluster count is greater than the represented input count its value will be lowered. Please note that it can not be guaranteed that resulting cluster count will fall between the given (or updated) limits.

Parameters:

initialMinCC - minimum expected cluster count inclusive

maxCC - maximum expected cluster count inclusive

di - input source

po - progress observer to update

Returns:

Input item ID based clustering; using centroids as representants. Note that the resulting cluster count can fall outside the expected cluster count range.

Throws:

CancellationException - if cancelled by the progress observer

IllegalArgumentException - on empty input, or when cluster counts are invalid

LicenseException - when appropriate license is not available

sphexCentroids

public static Optional<int[]> sphexCentroids(double r,
                                             int maxCC,
                                             DissimilarityInput di,
                                             ProgressObserver po)
                                      throws CancellationException

Identify SphereExclusion clustering based centroids for a given set.

Parameters:

r - Sphere radius to use.

maxCC - Maximal allowed cluster count. If the given parameters results in more identified centroids the algorithm immediately terminates and returns with an Optional.absent() value.

di - Input dissimilarity space

po - Associated progress observer

Returns:

A list of found centroid indexes if maximum cluster count is not exceeded

Throws:

CancellationException - When termination is due to cancel request from the progress observer

LicenseException - when appropriate license is not available

sphexClassify

public static IDBasedSingleLevelClustering sphexClassify(int[] centroids,
                                                         DissimilarityInput di,
                                                         ProgressObserver po)
                                                  throws CancellationException

Classify input items into clusters determined by nearest centroids.

Parameters:

centroids - Centroid indexes

di - Input dissimilarity space

po - Associated progress observer

Returns:

Input item ID based clustering; using centroids as representants

Throws:

CancellationException - When termination is due to cancel request from the progress observer * @throws chemaxon.license.LicenseException when appropriate license is not available