Ensemble comparison
=====================

Tools to statistically compare distributions of a feature (or a
2-column joint feature) across systems and/or replicas. Each
``compute_*`` function is also exposed as a ``Dataset`` method of the
same name.

These tools group by ``Dataset.unique_replica_col`` rather than the
raw replica column, so comparisons stay correct even when replica
labels (e.g. plain numbers ``1``, ``2``, ``3``...) are reused
identically across systems -- see
:class:`~RepLikCompare.dataset.Dataset`.

Jensen-Shannon divergence
----------------------------

Compares two distributions via their Jensen-Shannon divergence, a
symmetric, bounded (``[0, ln(2)]``) measure well suited to answering
"are these two systems sampling different states?" -- with bootstrap
confidence intervals and an automatic, human-readable verdict.

.. autofunction:: RepLikCompare.EnsembleComparison.compute_jsd.compute_jsd

Wasserstein distance
------------------------

Compares two distributions via the (first-order) Wasserstein/
earth-mover's distance -- unbounded, expressed in the feature's native
units, and computed directly on the raw samples rather than a
histogram. Useful as a complement to the JSD when the *magnitude* of
the shift between distributions matters, not just whether it's
detectable.

.. autofunction:: RepLikCompare.EnsembleComparison.compute_wasserstein.compute_wasserstein

Convergence diagnostics
---------------------------

Checks whether a single trajectory has been run long enough for a
given feature to look converged -- a per-trajectory diagnostic,
answering "has this run converged?" rather than "do these two runs
agree?" (which is what ``compute_jsd``/``compute_wasserstein`` are
for).

.. autofunction:: RepLikCompare.EnsembleComparison.compute_convergence.compute_convergence

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

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