Package 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 Details

    • fixedSPHEX

      @Deprecated(forRemoval=true) @SubjectToRemoval(date=JUL_01_2025) public static IDBasedSingleLevelClustering fixedSPHEX(double radius, DissimilarityInput di, ProgressObserver po) throws CancellationException
      Deprecated, for removal: This API element is subject to removal in a future version.
      Use fixedSPHEX(double, DissimilarityInput, PhasedProgressObserver) instead.
      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

    • fixedSPHEX

      public static IDBasedSingleLevelClustering fixedSPHEX(double radius, DissimilarityInput di, PhasedProgressObserver ppo) 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
      ppo - 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

      @Deprecated(forRemoval=true) @SubjectToRemoval(date=JUL_01_2025) public static IDBasedSingleLevelClustering adaptiveSPHEX(int initialMinCC, int maxCC, DissimilarityInput di, ProgressObserver po) throws CancellationException
      Deprecated, for removal: This API element is subject to removal in a future version.
      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

    • adaptiveSPHEX

      public static IDBasedSingleLevelClustering adaptiveSPHEX(int initialMinCC, int maxCC, DissimilarityInput di, PhasedProgressObserver ppo) 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
      ppo - 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