Core concepts

docs/concepts/estimators.rst

@@ -0,0 +1,61 @@
+===============================
+Absolute Free Energy Estimators
+===============================
+
+Relative free energy calculations produce :math:`\Delta\Delta G` (differences between two ligands). To compare these with experiment,
+or to rank ligands by affinity, we need absolute :math:`\Delta G` for each ligand.
+
+This requires an **estimator**: a method that takes the network of relative free energies and produces absolute values.
+
+
+Maximum Likelihood Estimation (MLE)
+-----------------------------------
+
+The Maximum Likelihood Estimation (MLE) [1]_ method is the **default** estimator used in cinnabar to obtain absolute
+free energies (:math:`\Delta G`) from a network of relative free energies (:math:`\Delta\Delta G`).
+
+
+The Core Idea
+~~~~~~~~~~~~~~
+To place every ligand on a common absolute scale, we need to find a set of :math:`\Delta G` values that best explain all
+relative differences (:math:`\Delta\Delta G`) simultaneously. The MLE method does this by asking:
+
+ What set of :math:`\Delta G` values makes the observed data most likely, given the reported uncertainties?
+
+This framing naturally integrates all edges and cycles in the graph simultaneously.
+
+The Likelihood Function
+~~~~~~~~~~~~~~~~~~~~~~~
+
+Suppose we have a network with two ligands ``i`` and ``j``, with observed relative free energy :math:`\Delta\Delta G_{ij}` and
+uncertainty :math:`\sigma_{ij}`. The model assumes each measurement is normally distributed:
+
+.. math::
+
+   \Delta\Delta G_{ij} \approx \mathcal{N}(\Delta G_j - \Delta G_i, \sigma_{ij}^2)
+
+The **likelihood** is the product of probabilities for all edges in the graph. The MLE procedure finds the set of :math:`\Delta G`
+values that maximises this likelihood (or equivalently, minimises the negative log-likelihood).
+
+Uncertainty Propagation
+~~~~~~~~~~~~~~~~~~~~~~~
+
+Input uncertainties (:math:`\sigma_{ij}`) are explicitly included in the likelihood function. This means more precise edges
+(smaller uncertainty) have greater weight in determining the solution. However, this does mean that high confidence but low
+accuracy edges can impact the entire network and so robust uncertainty estimates on input data are crucial.
+
+
+Centering of Results
+~~~~~~~~~~~~~~~~~~~~
+
+The absolute :math:`\Delta G` scale is arbitrary: adding a constant to all :math:`\Delta G` values does not change any relative differences :math:`\Delta\Delta G`.
+As a result, the MLE solution is typically centred around zero (or another chosen reference). To compare with experimental
+values, an experimental shift must be applied. By default ``cinnabar`` will align the mean of predicted and
+experimental :math:`\Delta G` in the plotting functions.
+
+
+References
+~~~~~~~~~~~
+
+.. [1] Xu, H., 2019. Optimal measurement network of pairwise differences. Journal of Chemical Information and Modeling, 59(11), pp.4720-4728.
+

docs/concepts/femap.rst

@@ -0,0 +1,56 @@
+============================
+The ``FEMap`` Data Structure
+============================
+
+The :class:`.FEMap` is the **core abstraction in cinnabar**.
+It provides a unified representation of free energy data, connecting the inputs from relative binding free energy
+calculations with the **analyses** and **visualisations** that cinnabar enables.
+
+Why a Graph?
+------------
+
+Relative free energy calculations are inherently **relational**: they compare two ligands at a time, producing a free
+energy difference (:math:`\Delta\Delta G`) with an associated uncertainty. If we want to reason about a whole series of ligands, which
+may be connected by multiple pairwise comparisons, we need to connect these edges in a logical way.
+
+A **graph** is a natural way to represent this data, where:
+
+- **Nodes** represent individual ligands.
+- **Edges** represent pairwise free energy differences (:math:`\Delta\Delta G`) between ligands.
+- **Absolute values** (:math:`\Delta G` experimental or calculated) can bet atached to nodes as attributes.
+
+This graph representation is powerful: it allows integration of relative and absolute data, and it provides the
+foundation for robust statistical analysis and visualization.
+
+
+From Relative to Absolute
+~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Although we calculate relative free energies directly, many applications require absolute binding free energies for
+each ligand in order to rank the ligands for prioritization.
+
+The :class:`.FEMap` provides convenience methods to support this transformation via a maximum likelihood estimation (MLE) [1]_
+method by default. These methods take advantage of the entire network of relative free energies to infer absolute values.
+Thus they require a graph which is at least weakly connected, that is there is a path between any two ligands in the graph.
+A graph structure lends itself naturally to this type of analysis and the ``FEMap`` provides utilities to check and
+visualise the connectivity of the network.
+
+
+Redundancy and Consistency
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+One of the strengths of a graph representation is that it can handle redundant data.
+If multiple calculations connect the same ligands (e.g. forward and reverse transformations, repeats), they can easily be
+incorperated into a directed graph structure, however not all estimators maybe able to take advantage of this information.
+
+Cycles in the network provide consistency checks: if the sum of :math:`\Delta\Delta G` around a cycle is far from zero, that highlights systematic errors or poorly converged calculations.
+
+Thus, the ``FEMap`` is not just a container, but also a tool for identifying inconsistencies in the underlying data.
+
+
+References
+~~~~~~~~~~~
+
+.. [1] Xu, H., 2019. Optimal measurement network of pairwise differences. Journal of Chemical Information and Modeling, 59(11), pp.4720-4728.
+
+

docs/concepts/index.rst

@@ -0,0 +1,13 @@
+Core Concepts
+=============
+
+This section covers the core concepts of the software, offering a deep dive into the key abstractions, data structures and theory that underpin its functionality.
+For detailed step-by-step tutorials on using the software, please refer to the tutorials section.
+
+
+.. toctree::
+   :maxdepth: 1
+
+   femap
+   estimators
+   plotting

docs/concepts/plotting.rst

@@ -0,0 +1,66 @@
+=======================
+Plotting Best Practices
+=======================
+
+Visualisation plays a crucial role in assessing the accuracy of binding free energy calculations. The same
+raw data can be represented in many different ways, and the choice of plot or analysis metric determines which aspects of performance are
+highlighted. This page explains the plot types available in ``cinnabar``, and the best practices they follow. For more
+detailed information we recommend reading the companion article [1]_.
+
+Edgewise :math:`\Delta\Delta G` Plots
+-------------------------------------
+
+Edgewise relative free energy plots allow direct comparison of calculated and experimental :math:`\Delta\Delta G` values.
+These plots are best for method developers, as they show how well individual transformations
+are predicted and highlight outliers.
+
+Best practices:
+
+- **Only error statistics (RMSE, MUE)** are shown by default. Correlation measures (:math:`R^{2}`, :math:`\rho`) are not meaningful, as the direction of a relative transformation is arbitrary.
+- **Error bars** are shown on to represent uncertainty in both calculated and experimental values.
+- **Statistics uncertainty estimates** are bootstrapped (1000 samples with replacement) to provide 95% confidence intervals.
+
+
+Absolute :math:`\Delta G` Plots
+-------------------------------
+
+Absolute free energy plots compare calculated and experimental :math:`\Delta G` values for each ligand. Absolute
+:math:`\Delta G` predictions can be obtained from a connected network of relative free energies. They therefore accumulate errors from multipule aspects of the calculation, including
+edge accuracy, uncertainty quantification, perutration network design and estimator, giving a complete picture of protocol performance.
+These plots are then useful for both method developers and users, as they show how well the overall ranking of ligands is predicted.
+
+Best practices:
+
+- **Both error (RMSE, MUE) and correlation** (:math:`R^{2}`, :math:`\rho`) statistics are shown by default, as absolute data are directional and correlation is meaningful.
+- **Error bars** are shown on to represent uncertainty in both calculated and experimental values.
+- **Statistics uncertainty estimates** are bootstrapped (1000 samples with replacement) to provide 95% confidence intervals.
+- **Mean centering** is applied by default to align the mean of calculated and experimental values, as the absolute scale is arbitrary.
+
+Pairwise (all-to-all) :math:`\Delta\Delta G` Plots
+--------------------------------------------------
+
+Pairwise or all-to-all relative free energy plots compare all possible pairwise :math:`\Delta\Delta G` values between ligands in a dataset.
+These are generated by calculating pairwise differences from the estimated absolute :math:`\Delta G` values.
+These plots are especially useful for method developers because they remove the influence of perturbation network design:
+every method is compared on the same set of pairwise values, even if the underlying networks differ.
+
+Best practices:
+
+- Follow the same guidelines as for edgewise plots (error statistics only, with uncertainties represented).
+- Use these plots for fair, network-independent comparisons between methods.
+
+
+Summary of Best Practices
+-------------------------
+
+- Use :math:`\Delta\Delta G` plots for edge-level diagnostics.
+- Use absolute :math:`\Delta G` plots for global performance and ranking.
+- Always represent uncertainties, both at the individual estimate level and on reported statistics (e.g. RMSE).
+- When comparing across methods, use all-to-all pairwise :math:`\Delta\Delta G` to enable fair comparisons.
+
+
+References
+~~~~~~~~~~~
+
+.. [1] Hahn, D.F., Bayly, C.I., Boby, M.L., Macdonald, H.E.B., Chodera, J.D., Gapsys, V., Mey, A.S., Mobley, D.L., Benito, L.P., Schindler, C.E. and Tresadern, G., 2022. Best practices for constructing, preparing, and evaluating protein-ligand binding affinity benchmarks [article v1. 0]. Living journal of computational molecular science, 4(1), p.1497.
+

docs/index.rst

@@ -30,7 +30,7 @@ Contents
    :maxdepth: 1
 
    installation
-   getting_started
+   concepts/index
 
 
 Reference