Dimensionality reduction
=========================

Standalone dimensionality-reduction functions. Each one is also
exposed as a ``Dataset`` method of the same name. All four support a
``circular=True`` mode for angular features (e.g. dihedral angles),
which switches to a distance/kernel that correctly handles the
+-pi wrap-around instead of treating angles as plain linear numbers.

PCA
---

Principal Component Analysis: a fast, linear projection onto the
directions of maximum variance. Good default first pass, and the only
one of the four that scales comfortably to large datasets.

.. autofunction:: RepLikCompare.dimensionality_reduction.compute_pca.compute_pca

UMAP
----

A nonlinear, graph-based embedding that tends to preserve both local
neighborhoods and some global structure. Generally the best-looking
2D/3D embedding for exploratory visualization, at a higher
computational cost than PCA.

.. autofunction:: RepLikCompare.dimensionality_reduction.compute_umap.compute_umap

t-SNE
-----

Another nonlinear embedding, focused on preserving local
neighborhoods (at the expense of global distances/structure). Often
produces tighter, more visually separated clusters than UMAP, but
inter-cluster distances shouldn't be over-interpreted.

.. autofunction:: RepLikCompare.dimensionality_reduction.compute_tsne.compute_tsne

Kernel PCA
----------

A nonlinear generalization of PCA using the kernel trick (e.g. an RBF
kernel); a middle ground between plain PCA and UMAP/t-SNE.

.. autofunction:: RepLikCompare.dimensionality_reduction.compute_kpca.compute_kpca

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

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