Features and concepts
=====================

Algorithm overview
------------------

CLASSIX compresses the clustering problem before it performs the final merge.
Instead of comparing every sample with every other sample, it sorts the data and
creates aggregation groups around starting points. The merge step then works on
those group representatives rather than on all samples directly.

This produces three useful levels of structure:

``data points``
    The original samples supplied by the user.

``groups``
    Local neighborhoods formed during aggregation. Each group has a starting
    point that represents it.

``clusters``
    Final connected components formed by merging groups.

Because the intermediate groups are retained, CLASSIX can explain a result in
terms of the starting point that captured a sample and the graph of groups that
connects samples inside a cluster.

Distance metrics
----------------

``metric='euclidean'``
    The default metric for continuous numerical data. Euclidean clustering
    supports PCA sorting, norm sorting, distance merging, and density merging.

``metric='manhattan'``
    Uses L1 distance. The implementation shifts data to the non-negative
    orthant and uses sum-based sorting to prune candidate comparisons.

``metric='tanimoto'``
    Uses Tanimoto distance, ``1 - similarity``. This is useful for non-negative
    binary, count, or fingerprint-like vectors.

Sorting options
---------------

Sorting is most relevant for Euclidean clustering:

``sorting='pca'``
    Sort samples by their first principal component. This is the default and is
    a strong general-purpose choice.

``sorting='norm-mean'``
    Mean-center the data and sort by Euclidean norm.

``sorting='norm-orthant'``
    Shift the data to the non-negative orthant and sort by Euclidean norm.

``sorting=None``
    Disable sorting and aggregate the raw order.

For ``metric='manhattan'``, CLASSIX uses sum-based sorting automatically. For
``metric='tanimoto'``, row sums are used internally for efficient candidate
pruning.

Merging options
---------------

``group_merging='distance'``
    Merge groups when their starting points are within
    ``mergeScale * radius``. This is the default and the fastest general-purpose
    strategy.

``group_merging='density'``
    Merge Euclidean groups using an intersection-density criterion. This can be
    useful when local density structure is important.

``group_merging=None``
    Skip the merge step and return aggregation groups as clusters.

Outlier and small-cluster handling
----------------------------------

The ``minPts`` parameter defines the minimum valid cluster size. Clusters with
fewer samples are treated as small clusters and are reassigned to nearby valid
clusters when possible. If ``post_alloc=False`` is used with a supported merge
path, filtered samples can be labeled ``-1`` instead.

Explanation tools
-----------------

The ``CLASSIX.explain`` method can be used in three modes:

* ``clx.explain(X)`` prints a global summary of the fitted clustering.
* ``clx.explain(X, index1=i)`` explains the group and cluster containing one
  sample.
* ``clx.explain(X, index1=i, index2=j)`` explains whether two samples are in the
  same cluster and, when available, prints a path through connected groups.

For two-dimensional data, or for higher-dimensional data projected to two
principal components, ``plot=True`` visualizes the explanation.

Cython acceleration
-------------------

CLASSIX can use compiled Cython extensions for the core aggregation and merging
steps. The public Python API is the same whether Cython is enabled or not. Use
``classix.cython_is_available(verbose=True)`` to check which implementation is
active, and set ``classix.__enable_cython__ = False`` before constructing an
estimator if you need to force the pure-Python path for debugging or comparison.