com.chemaxon.clustering.common

Class IDBasedHierarchicClusterBuidler

java.lang.Object

com.chemaxon.clustering.common.IDBasedHierarchicClusterBuidler

@Beta
 @PublicAPI
public final class IDBasedHierarchicClusterBuidler
extends Object

Builder for integer ID based hierarchic cluster building.

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.

Constructor Summary

Constructors

Constructor and Description
IDBasedHierarchicClusterBuidler(HierarchicClustering.Alignment alignemnt) New builder instance.

Method Summary

Modifier and Type	Method and Description
void	addChildCluster(int childClusterID, int parentClusterID) Add a cluster to another cluster as a child cluster.
int	addNewCluster() Allocate a new cluster.
void	addStructureToCluster(int structureID, int parentClusterID) Add a structure to a cluster as an immediate leaf.
IDBasedHierarchicClustering	build() Build the immutable clustering representation.
IDBasedHierarchicClustering	build(IDBasedAssignerBuilder assignerBuilder) Build an immutable snapshot of the clustering.
IDBasedClusterBuilderSpec	cluster(int representedClusterId) A spec for a clusterId.
int	clusterOf(int structureID) Look up immediate parent of a structure present in the clustering.
void	detachToRootCluster(int clusterID) Remove a cluster from its current parent cluster.
int[]	getAllLeaves(int clusterID) Return the IDs of all immediate and transitive leaves.
int[]	getChildClusters(int clusterID) Return the IDs of child cluster IDs.
int	getClusterRepresentant(int clusterID) Retrieve cluster representant ID.
int[]	getImmediateLeaves(int clusterID) Return the IDs of immediate leaves.
int	getParentClusterID(int clusterID) Looks up a clusters parent cluster ID.
int	getStructureImmediateParentCluster(int structureID) Look up structure's immediate parent cluster ID.
boolean	hasParent(int clusterID) Check if a cluster has parent cluster id set.
boolean	isClusterRepresentantSet(int clusterID) Check if cluster representant is present.
boolean	isEmpty() Check if the tree is empty.
boolean	isStructurePresent(int structureId) Check if a given structure ID is present in the clustering.
IDBasedClusterBuilderSpec	newCluster() Allocates a new cluster and returns a spec to it.
static IDBasedHierarchicClusterBuidler	newRootAlignedIdDBasedHierarchicClusterBuilder() Convenience method.
IDBasedClusterBuilderSpec	newRootCluster() Allocates a new cluster and returns a spec to it.
void	removeStructure(int structureID) Remove a structure from its current parent cluster.
void	setClusterPreferredLevel(int clusterID, double level) Set cluster level of preferred level assigner.
void	setClusterRepresentant(int structureID, int clusterID) Set cluster representant ID.
void	setLeafPreferredLevel(int leafID, double level) Set leaf level of preferred level assigner.
String	toDetailedString() Create a detailed multiline String representation of the builder state.
static String	toDetailedString(IDBasedHierarchicClustering c) Utility method to create a detailed string representation of a clustering.

Methods inherited from class java.lang.Object

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

Constructor Detail

IDBasedHierarchicClusterBuidler

public IDBasedHierarchicClusterBuidler(HierarchicClustering.Alignment alignemnt)

New builder instance.

Parameters:

alignemnt - Alignment of the clustering hierarchy

Throws:

LicenseException - when appropriate license is not available

Method Detail

newRootAlignedIdDBasedHierarchicClusterBuilder

public static IDBasedHierarchicClusterBuidler newRootAlignedIdDBasedHierarchicClusterBuilder()

Convenience method.

Returns:

new builder

addNewCluster

public int addNewCluster()

Allocate a new cluster.

Note that it is not necessary to call this method; clusters are added implicitly.

Returns:

ID of a new empty cluster, considered as root.

clusterOf

public int clusterOf(int structureID)

Look up immediate parent of a structure present in the clustering.

Opposed to HierarchicClustering.clusterOf(java.lang.Object) this method expects the given structure to be present in the current state of the clustering.

Parameters:

structureID - Structure ID to look up

Returns:

Immediate parent cluster index of the structure

Throws:

IllegalArgumentException - when the given structure is not part of the clustering

hasParent

public boolean hasParent(int clusterID)

Check if a cluster has parent cluster id set.

This method expects the given cluster to be part of the current state of the clusteing.

Parameters:

clusterID - ClusterID to look up

Returns:

True if a parent cluster id set, otherwise false

Throws:

IllegalArgumentException - when the given cluster is not part of the clustering

getImmediateLeaves

public int[] getImmediateLeaves(int clusterID)

Return the IDs of immediate leaves.

Parameters:

clusterID - Cluster ID

Returns:

A (possibly) empty list of immediate leaf IDs of the given cluster

Throws:

IllegalArgumentException - when the given cluster is not part of the clustering

getAllLeaves

public int[] getAllLeaves(int clusterID)

Return the IDs of all immediate and transitive leaves.

Parameters:

clusterID - Cluster ID

Returns:

A (possibly) empty list of immediate and transitive leaf IDs of the given cluster

Throws:

IllegalArgumentException - when the given cluster is not part of the clustering

getChildClusters

public int[] getChildClusters(int clusterID)

Return the IDs of child cluster IDs.

Parameters:

clusterID - Cluster DI

Returns:

A (possibly) empty list of immediate children IDs of the given cluster

Throws:

IllegalArgumentException - when the given cluster is not part of the clustering

getParentClusterID

public int getParentClusterID(int clusterID)

Looks up a clusters parent cluster ID.

Parameters:

clusterID - Cluster ID to look up

Returns:

ID of the parent cluster

Throws:

IllegalArgumentException - when the given cluster is not part of the clustering or it has no parent associated

isStructurePresent

public boolean isStructurePresent(int structureId)

Check if a given structure ID is present in the clustering.

Parameters:

structureId - Structure ID to check

Returns:

true when given structure is present in the clustering

removeStructure

public void removeStructure(int structureID)

Remove a structure from its current parent cluster.

This modification operation ensures valid and consistent state by throwing exception when given structure is not part of any cluster. Cluster representant references are also removed.

Parameters:

structureID - StructureID to remove

getStructureImmediateParentCluster

public int getStructureImmediateParentCluster(int structureID)

Look up structure's immediate parent cluster ID.

Parameters:

structureID - StructureID

Returns:

ClusterID of the immediate parent cluster.

Throws:

IllegalArgumentException - when given structure is not present

isEmpty

public boolean isEmpty()

Check if the tree is empty.

Returns:

True when no structures contained

detachToRootCluster

public void detachToRootCluster(int clusterID)

Remove a cluster from its current parent cluster.

This modification operation expects that the given cluster is a child of another cluster

Parameters:

clusterID - clusterID to remove

isClusterRepresentantSet

public boolean isClusterRepresentantSet(int clusterID)

Check if cluster representant is present.

Parameters:

clusterID - cluster ID

Returns:

true if cluster representant structure is set for the given cluster

Throws:

IllegalArgumentException - when given cluster is not assigned

getClusterRepresentant

public int getClusterRepresentant(int clusterID)

Retrieve cluster representant ID.

Parameters:

clusterID - cluster ID

Returns:

cluster representant structure index if set for the given cluster

Throws:

IllegalArgumentException - when given cluster has no cluster representant set

setClusterRepresentant

public void setClusterRepresentant(int structureID,
                                   int clusterID)

Set cluster representant ID.

Parameters:

structureID - Cluster representant structure ID

clusterID - Associated cluster

setClusterPreferredLevel

public void setClusterPreferredLevel(int clusterID,
                                     double level)

Set cluster level of preferred level assigner. Forwarded to IDBasedAssignerBuilder.setClusterLevel(int, double) of the optional IDBasedAssignerBuilder.

Parameters:

clusterID - Cluster ID

level - Level

setLeafPreferredLevel

public void setLeafPreferredLevel(int leafID,
                                  double level)

Set leaf level of preferred level assigner. Forward to IDBasedAssignerBuilder.setLeafLevel(int, double) of the optional IDBasedAssignerBuilder.

Parameters:

leafID - Leaf ID

level - Level

newCluster

public IDBasedClusterBuilderSpec newCluster()

Allocates a new cluster and returns a spec to it. This method delegates to addNewCluster() then returns a wrapper for further operations.

Returns:

Spec for the new cluster

newRootCluster

public IDBasedClusterBuilderSpec newRootCluster()

Allocates a new cluster and returns a spec to it. This method delegates to addNewCluster() then returns a wrapper for further operations.

Returns:

Spec for the new cluster

cluster

public IDBasedClusterBuilderSpec cluster(int representedClusterId)

A spec for a clusterId.

Parameters:

representedClusterId - Cluster ID to represent

Returns:

Spec for the given cluster

addStructureToCluster

public void addStructureToCluster(int structureID,
                                  int parentClusterID)

Add a structure to a cluster as an immediate leaf.

Parameters:

structureID - Structure ID to add

parentClusterID - Associated parent cluster

Throws:

IllegalArgumentException - when structure is already added to another cluster

addChildCluster

public void addChildCluster(int childClusterID,
                            int parentClusterID)

Add a cluster to another cluster as a child cluster.

Parameters:

childClusterID - Cluster ID to add as a child

parentClusterID - Associated parent cluster

Throws:

IllegalArgumentException - when structure is already added to another cluster

toDetailedString

public String toDetailedString()

Create a detailed multiline String representation of the builder state.

Returns:

Detailed multiline String representation of the current state

build

public IDBasedHierarchicClustering build(IDBasedAssignerBuilder assignerBuilder)

Build an immutable snapshot of the clustering.

Derive the preferred level assigner (HierarchicClustering.getPreferredAssigner()) from the given assigner builder.

Parameters:

assignerBuilder - Preferred level assignment source.

Returns:

A hierarchic clustering snapshot with a given suggested lebel assigner.

Throws:

IllegalStateException - when a preferred level info is set to any cluster or leaf

build

public IDBasedHierarchicClustering build()

Build the immutable clustering representation.

When any level info is previously set then it will be the preferred assigner. Otherwise the preferred level assigner (returned by HierarchicClustering.getPreferredAssigner()) will be the graph depth based level assigner HierarchicClustering.unitPathAssigner().

Returns:

An immutable clustering representation.

toDetailedString

public static String toDetailedString(IDBasedHierarchicClustering c)

Utility method to create a detailed string representation of a clustering.

Parameters:

c - Clustering to traverse

Returns:

Detailed multiline String representation