Add new parameter prior distributions

doc/v2/documentation_data_format.rst

@@ -149,11 +149,14 @@ PEtab 2.0.0 is a major update of the PEtab format. The main changes are:
   priors are outside the definition of the parameter estimation problem
   and were a source of confusion.
 * ``objectivePriorType`` and ``objectivePriorParameters`` in the
-  :ref:`v2_parameters_table` are renamed to ``prior`` and
+  :ref:`v2_parameters_table` are renamed to ``priorDistribution`` and
   ``priorParameters``, respectively. This change was made to simplify
   the PEtab format.
 * The admissible values for ``estimate`` in the :ref:`v2_parameters_table`
   are now ``true`` and ``false`` instead of ``1`` and ``0``.
+* Support for new parameter prior distributions in the
+  :ref:`v2_parameters_table`, and clarification that bounds truncate the
+  prior distributions.
 
 .. _v2_model:
 .. _v2_model_entities:
@@ -743,15 +746,15 @@ One row per parameter with arbitrary order of rows and columns:
 
 *(wrapped for readability)*
 
-+-----+----------------+----------------------------+
-| ... | [prior]        | [priorParameters]          |
-+=====+================+============================+
-| ... | *see below*    | *see below*                |
-+-----+----------------+----------------------------+
-| ... | normal         | 1000;100                   |
-+-----+----------------+----------------------------+
-| ... | ...            | ...                        |
-+-----+----------------+----------------------------+
++-----+-------------------------+----------------------------+
+| ... | [priorDistribution]     | [priorParameters]          |
++=====+=========================+============================+
+| ... | *see below*             | *see below*                |
++-----+-------------------------+----------------------------+
+| ... | normal                  | 1000;100                   |
++-----+-------------------------+----------------------------+
+| ... | ...                     | ...                        |
++-----+-------------------------+----------------------------+
 
 Additional columns may be added.
 
@@ -794,34 +797,119 @@ Detailed field description
   estimated (``true``) or set to a fixed value (``false``)
   (see ``nominalValue``).
 
-- ``prior`` [STRING, OPTIONAL]
+- ``priorDistribution`` [STRING, OPTIONAL]
 
-  Prior types used for the :ref:`MAP objective function and for Bayesian inference <v2_objective_function>`.
+  Prior types used for the
+  :ref:`MAP objective function and for Bayesian inference <v2_objective_function>`.
   It is valid to have no priors. However, if priors are specified for a subset
   of parameters, this defaults to the ``uniform`` prior (with ``priorParameters``
   set to ``lowerBound;upperBound``) for the other parameters.
 
-  Possible prior types are:
-
-    - *uniform*: flat/uninformative prior
-    - *normal*: Gaussian prior
-    - *laplace*: Laplace prior
-    - *logNormal*: exponentiated Gaussian prior
-    - *logLaplace*: exponentiated Laplace prior
+  Prior distributions are
+  `truncated <https://en.wikipedia.org/wiki/Truncated_distribution>`__
+  by the ``lowerBound`` and ``upperBound`` if
+  the prior's domain exceeds the parameter bounds. A non-truncated prior can
+  be created by setting the parameter bounds to  match the prior's domain
+  (e.g., ``0`` and ``inf`` for ``log-normal``). For supported prior distributions
+  see :ref:`prior distributions <v2_prior_distributions>`.
 
 - ``priorParameters`` [STRING, OPTIONAL]
 
-  Prior parameters used for the :ref:`MAP objective function and for Bayesian inference <v2_objective_function>`.
-  ``priorParameters`` is required if ``prior`` is non-empty.
+  Prior parameters used for the
+  :ref:`MAP objective function and for Bayesian inference <v2_objective_function>`.
+  ``priorParameters`` is required if ``priorDistribution`` is non-empty.
+
+  Only numeric values are supported (no parameter IDs). For available
+  parameters see :ref:`prior distributions <v2_prior_distributions>`.
+
+.. _v2_prior_distributions:
+
+Prior distributions
+~~~~~~~~~~~~~~~~~~~
 
-  So far, only numeric values will be supported, no parameter names.
-  Parameters for the different prior types are:
+Let :math:`x` denote the parameter value and :math:`\Gamma` the Gamma function,
+then the following prior distributions are supported:
+
+.. list-table::
+  :header-rows: 1
+  :widths: 10 15 20 5
+
+  * - ``priorDistribution``
+    - ``priorParameters``
+    - Probability density function (PDF)
+    - Domain
+  * - cauchy
+    - location (:math:`\mu`); scale (:math:`\sigma`)
+    - .. math::
+        \pi(x|\mu, \sigma) = \frac{1}{\pi \sigma \left( 1 + \left(\frac{x - \mu}{\sigma} \right)^2\right)}
+    - :math:`(-\infty, \infty)`
+
+  * - chisquare
+    - degrees of freedom (:math:`\nu`)
+    - .. math::
+        \pi(x|\nu) = \frac{x^{\nu/2-1}e^{-x/2}}{2^{\nu/2}\Gamma(\nu/2)}
+    - :math:`(0, \infty)`
+
+  * - exponential
+    - scale (:math:`\theta`)
+    - .. math::
+        \pi(x|\theta) = \frac{1}{\theta}e^{-x/\theta}
+    - :math:`(0, \infty)`
+
+  * - gamma
+    - shape (:math:`\alpha`); scale (:math:`\theta`)
+    - .. math::
+        \pi(x|\alpha, \theta) = \frac{x^{\alpha - 1}e^{-x/\theta}}{\Gamma(\alpha)\theta^{\alpha}}
+    - :math:`(-\infty, \infty)`
+
+  * - laplace
+    - location (:math:`\mu`); scale (:math:`\sigma`)
+    - .. math::
+        \pi(x|\mu, \sigma) = \frac{1}{2\sigma}\exp\left(- \frac{|x - \mu |}{\sigma}\right)
+    - :math:`(-\infty, \infty)`
+
+  * - log10-normal
+    - mean (:math:`\mu`); standard deviation (:math:`\sigma`)
+    - .. math::
+        \pi(x|\mu, \sigma) = \frac{1}{x \sqrt{2\pi}\sigma \log(10)} \exp\left(- \frac{\left(\log_{10}(x) - \mu\right)^2}{2\sigma^2}\right)
+    - :math:`(0, \infty)`
+
+  * - log-laplace
+    - location (:math:`\mu`); scale (:math:`\sigma`)
+    - .. math::
+        \pi(x|\mu, \sigma) = \frac{1}{2\sigma x} \exp\left( - \frac{|\log(x) - \mu|}{\sigma} \right)
+    - :math:`(0, \infty)`
+
+  * - log-normal
+    - mean (:math:`\mu`); standard deviation (:math:`\sigma`)
+    - .. math::
+        \pi(x|\mu, \sigma) = \frac{1}{x \sqrt{2\pi}\sigma} \exp\left(- \frac{\left(\log(x) - \mu\right)^2}{2\sigma^2}\right)
+    - :math:`(0, \infty)`
+
+  * - log-uniform
+    - lower bound (:math:`a`); upper bound (:math:`b`)
+    - .. math::
+        \pi(x|a, b) = \frac{1}{x\left( \log(b) - \log(a) \right)}
+    - :math:`[a, b]`
+
+  * - normal
+    - mean (:math:`\mu`); standard deviation (:math:`\sigma`)
+    - .. math::
+        \pi(x|\mu,\sigma) = \frac{1}{\sqrt{2\pi}\sigma}\exp\left(-\frac{(x-\mu)^2}{2\sigma^2}\right)
+    - :math:`(-\infty, \infty)`
+
+  * - rayleigh
+    - scale (:math:`\sigma`)
+    - .. math::
+        \pi(x|\sigma) = \frac{x}{\sigma^2}\exp\left(\frac{-x^2}{2\sigma^2}\right)
+    - :math:`(0, \infty)`
+
+  * - uniform
+    - lower bound (:math:`a`); upper bound (:math:`b`)
+    - .. math::
+        \pi(x|a, b) = \frac{1}{b - a}
+    - :math:`[a, b]`
 
-    - uniform: lower bound; upper bound
-    - normal: mean; standard deviation (**not** variance)
-    - laplace: location; scale
-    - logNormal: parameters of corresp. normal distribution (see: normal)
-    - logLaplace: parameters of corresp. Laplace distribution (see: laplace)
 
 .. _v2_visualization_table:
 
@@ -1056,7 +1144,7 @@ and `Bayesian inference <https://en.wikipedia.org/wiki/Bayesian_inference>`__.
 For MAP estimation and Bayesian inference, the prior
 distributions :math:`p(\theta)` of the model parameters :math:`\theta` are
 specified in the parameter table
-(``prior`` and ``priorParameters`` columns,
+(``priorDistribution`` and ``priorParameters`` columns,
 as described above),
 while for maximum likelihood estimation, the prior distributions are not
 specified. If priors are only specified