Plotting
========

Standalone plotting functions. Each one is also exposed as a
``Dataset`` method of the same name, which additionally handles
column-name resolution (``sim_name_col``/``replica_col``) and optional
``sim_name``/``replica`` filtering before delegating to the function
below.

Scatter plots
--------------

``plot_scatter`` draws a single scatter plot of two features, with
optional coloring by system/replica, a KDE density overlay, and an
annotated correlation coefficient / regression line.

.. autofunction:: RepLikCompare.plotting.plot_scatter.plot_scatter

``plot_scatter_facet`` is the faceted version: one scatter sub-panel
per system (or any other grouping column) instead of a single global
plot, with optional local (per-facet) and/or global regression lines
so groups can be compared directly.

.. autofunction:: RepLikCompare.plotting.plot_scatter.plot_scatter_facet

Line plots (replica-averaged)
-------------------------------

``plot_lineplot_avg`` plots a feature against time/frame, averaged
across replicas of a system with a shaded spread band.

.. autofunction:: RepLikCompare.plotting.plot_lineplot_avg.plot_lineplot_avg

``plot_lineplot_facet`` is the faceted version, with one sub-panel per
system.

.. autofunction:: RepLikCompare.plotting.plot_lineplot_avg.plot_lineplot_facet

Distributions
--------------

``plot_distri_norm`` plots the distribution (histogram and/or KDE) of
a feature, grouped per system or per replica.

.. autofunction:: RepLikCompare.plotting.plot_distri_norm.plot_distri_norm

Circular distributions (von Mises)
-------------------------------------

``plot_vonmises`` is the circular equivalent of ``plot_distri_norm``
for angular features (e.g. dihedral angles): it fits a von Mises
kernel density instead of a linear KDE, so the density correctly wraps
around at +-pi.

.. autofunction:: RepLikCompare.plotting.plot_vonmises.plot_vonmises

Free-energy landscapes
-------------------------

``plot_free_energy`` plots a 2D free-energy landscape from two raw
feature series, estimated from their joint histogram via Boltzmann
inversion (:math:`F = -kT \ln p`).

.. autofunction:: RepLikCompare.plotting.plot_free_energy.plot_free_energy

``plot_free_energy_facet`` is the faceted version: instead of one
global landscape, it draws one *local* landscape per system (or other
grouping column), optionally sharing a common color scale so the
panels stay directly comparable.

.. autofunction:: RepLikCompare.plotting.plot_free_energy.plot_free_energy_facet

RMSD / RMSF
-----------

``plot_rmsd`` plots RMSD as a function of time/frame.

.. autofunction:: RepLikCompare.plotting.plot_rmsd.plot_rmsd

``plot_rmsf`` plots RMSF as a function of residue/atom index.

.. autofunction:: RepLikCompare.plotting.plot_rmsf.plot_rmsf

Contact maps
------------

``plot_contact_map`` draws a residue-residue (or atom-atom) contact
map as a heatmap.

.. autofunction:: RepLikCompare.plotting.plot_contact_map.plot_contact_map

Cluster timelines
------------------

``plot_cluster_timeline`` plots how the assigned cluster changes over
the course of a trajectory, and can optionally return a table of
cluster-to-cluster transitions.

.. autofunction:: RepLikCompare.plotting.plot_cluster_timeline.plot_cluster_timeline

Secondary-structure timelines
--------------------------------

``compute_secondary_structure_timeline`` plots secondary-structure
assignment (e.g. DSSP output) as a function of residue and time, one
row per residue.

.. autofunction:: RepLikCompare.plotting.compute_secondary_structure_timeline.compute_secondary_structure_timeline

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

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