Clustering
==========

Standalone clustering functions. Each one is also exposed as a
``Dataset`` method of the same name. They all take a set of numeric
``feature_cols`` and return ``(new_df, figures)``, where ``new_df`` is
the input dataframe with an added ``cluster`` column.

KMeans
------

Partitions the data into ``k`` clusters by minimizing within-cluster
variance, with an automatic search over ``k`` via the silhouette score
when ``k`` isn't given explicitly.

.. autofunction:: RepLikCompare.clustering.compute_cluster_kmean.compute_cluster_kmean

Gaussian Mixture Model
-----------------------

Soft, probabilistic clustering that fits a mixture of Gaussians to the
data; the number of components can be selected automatically via AIC
or BIC.

.. autofunction:: RepLikCompare.clustering.compute_cluster_GMM.compute_cluster_GMM

DBSCAN
------

Density-based clustering that finds clusters of arbitrary shape and
flags low-density points as noise, without needing to choose a number
of clusters in advance.

.. autofunction:: RepLikCompare.clustering.compute_cluster_dbscan.compute_cluster_dbscan

HDBSCAN
-------

Hierarchical variant of DBSCAN that adapts to clusters of varying
density and only requires a minimum cluster size, rather than a fixed
neighborhood radius (``eps``).

.. autofunction:: RepLikCompare.clustering.compute_cluster_hdbscan.compute_cluster_hdbscan

Hierarchical (agglomerative) clustering
-----------------------------------------

Builds a dendrogram by iteratively merging the closest clusters, then
cuts it at a chosen number of clusters; useful when the nested/
hierarchical relationship between clusters matters, not just the final
partition.

.. autofunction:: RepLikCompare.clustering.hierarchical_clustering.hierarchical_clustering

Cluster representatives
------------------------

Given an already-computed cluster column, picks one representative
frame per cluster -- the point closest to the cluster's centroid or
medoid -- so downstream analysis (e.g. visual inspection) can work with
a single frame per state instead of the whole cluster.

.. autofunction:: RepLikCompare.clustering.assign_cluster_representative.assign_cluster_representative

Notebook example
-----------------

.. TODO: link a dedicated "clustering" mini-notebook here once available.