clophfit.prenspire.thermo_plot
==============================

.. py:module:: clophfit.prenspire.thermo_plot

.. autoapi-nested-parse::

   Drawing helpers for the van't Hoff figure.

   The joint fit in :mod:`clophfit.prenspire.thermo` already handles both
   titration kinds correctly: a pH plate fits ``pKa(T)`` and a chloride
   plate fits ``pKd(T)`` and reports ``Kd`` on its native mM scale. These
   helpers put the *figure* on the same footing, so the curve drawn is the
   curve that was fitted.

   The two kinds differ in three places:

   - the model: Henderson-Hasselbalch for pH, Langmuir for a ligand;
   - the axis: pH is a linear, dimensionless scale, a ligand concentration
     spans decades and is drawn on a log axis;
   - the enthalpy sign: for a pH plate ``dH = +ln10 R b``, for a ligand
     ``d ln Kd / d(1/T) = -dH/R`` gives the opposite sign.



Classes
-------

.. autoapisummary::

   clophfit.prenspire.thermo_plot.VanthoffAxes


Functions
---------

.. autoapisummary::

   clophfit.prenspire.thermo_plot.vanthoff_curve
   clophfit.prenspire.thermo_plot.vanthoff_enthalpy
   clophfit.prenspire.thermo_plot.vanthoff_right_point
   clophfit.prenspire.thermo_plot.vanthoff_right_line
   clophfit.prenspire.thermo_plot.vanthoff_axes


Module Contents
---------------

.. py:class:: VanthoffAxes

   Bases: :py:obj:`NamedTuple`


   How one sample's van't Hoff row must be drawn.


   .. py:attribute:: left_x
      :type:  str

      Label of the left panel's titrant axis.


   .. py:attribute:: left_y
      :type:  str

      Label of the left panel's signal axis.


   .. py:attribute:: left_log
      :type:  bool

      Whether the left panel's titrant axis is logarithmic.


   .. py:attribute:: right_y
      :type:  str

      Label of the right panel's constant axis.


   .. py:attribute:: right_log
      :type:  bool

      Whether the right panel's constant axis is logarithmic.


.. py:function:: vanthoff_curve(model, temp, grid, plateaus)

   Draw the fitted model curve of one temperature, on its own titration's axis.

   :param model: The joint fit of the sample.
   :type model: VanthoffModel
   :param temp: Temperature label; the label the model carries.
   :type temp: str
   :param grid: Titrant values to evaluate the curve at.
   :type grid: np.ndarray
   :param plateaus: Fitted (S0, S1) of the band the curve is drawn for.
   :type plateaus: tuple[float, float]

   :returns: The modelled signal at every grid point.
   :rtype: np.ndarray


.. py:function:: vanthoff_enthalpy(model)

   Give the enthalpy of the equilibrium in J/mol, with the right sign.

   A pH plate fits ``pKa(T) = A + B (1/T - m)`` and ``pKa = -log10 Ka``,
   so ``dH = +ln10 R B``. A ligand plate fits ``pKd(T)``, and since
   ``d ln Kd / d(1/T) = -dH/R`` the same coefficient carries the opposite
   sign of enthalpy.


.. py:function:: vanthoff_right_point(model, temp)

   Give the constant of one temperature, as the right panel plots it.

   A pH plate's pKa is already the plotted quantity. A ligand plate's Kd
   is exponential in 1/T, so it is plotted on a log axis: the panel then
   shows the same Kd in mM that the table reports, read next to it.

   :param model: The joint fit of the sample.
   :type model: VanthoffModel
   :param temp: Temperature label.
   :type temp: str

   :returns: The plotted value and its standard error, on the plotted scale.
   :rtype: tuple[float, float]


.. py:function:: vanthoff_right_line(model, inv)

   Give the fitted constant along a range of inverse temperatures.

   The joint fit carries the constant as ``A + B (1/T - m)``: a pKa for a
   pH plate, a pKd for a ligand plate. A ligand's plotted constant is the
   Kd, so the line is the exponential of that.

   :param model: The joint fit of the sample.
   :type model: VanthoffModel
   :param inv: Inverse temperatures [1/K].
   :type inv: np.ndarray

   :returns: The constant at every inverse temperature, on the plotted scale.
   :rtype: np.ndarray


.. py:function:: vanthoff_axes(model)

   How one sample's van't Hoff row must be drawn.

   :param model: The joint fit of the sample.
   :type model: VanthoffModel

   :returns: The labels and the log-scale flags of the two panels.
   :rtype: VanthoffAxes