Package com.chemaxon.clustering.common

Class IDBasedHierarchicClusterBuilder

java.lang.Object
com.chemaxon.clustering.common.IDBasedHierarchicClusterBuilder
@Beta @PublicApi public final class IDBasedHierarchicClusterBuilder 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 Details

    • IDBasedHierarchicClusterBuilder

      public IDBasedHierarchicClusterBuilder(HierarchicClustering.Alignment alignment)
      New builder instance.
      Parameters:
      alignment - Alignment of the clustering hierarchy
      Throws:
      LicenseException - when appropriate license is not available

  • Method Details

    • newRootAlignedIdDBasedHierarchicClusterBuilder

      public static IDBasedHierarchicClusterBuilder 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