From 8d57edfea1db1de45ae3efb02440c14540329dc7 Mon Sep 17 00:00:00 2001 From: sebapersson Date: Tue, 25 Mar 2025 12:26:13 +0000 Subject: [PATCH 1/5] Remove initializationPrior and rename objectivePrior --- doc/v2/documentation_data_format.rst | 52 +++++++++------------------- 1 file changed, 17 insertions(+), 35 deletions(-) diff --git a/doc/v2/documentation_data_format.rst b/doc/v2/documentation_data_format.rst index 8758e1a9..ee181012 100644 --- a/doc/v2/documentation_data_format.rst +++ b/doc/v2/documentation_data_format.rst @@ -723,15 +723,15 @@ One row per parameter with arbitrary order of rows and columns: *(wrapped for readability)* -+-----+---------------------------+---------------------------------+----------------------+----------------------------+ -| ... | [initializationPriorType] | [initializationPriorParameters] | [objectivePriorType] | [objectivePriorParameters] | -+=====+===========================+=================================+======================+============================+ -| ... | *see below* | *see below* | *see below* | *see below* | -+-----+---------------------------+---------------------------------+----------------------+----------------------------+ -| ... | | | normal | 1000;100 | -+-----+---------------------------+---------------------------------+----------------------+----------------------------+ -| ... | ... | ... | ... | ... | -+-----+---------------------------+---------------------------------+----------------------+----------------------------+ ++-----+----------------+----------------------------+ +| ... | [prior] | [priorParameters] | ++=====+================+============================+ +| ... | *see below* | *see below* | ++-----+----------------+----------------------------+ +| ... | normal | 1000;100 | ++-----+----------------+----------------------------+ +| ... | ... | ... | ++-----+----------------+----------------------------+ Additional columns may be added. @@ -793,16 +793,11 @@ Detailed field description 1 or 0, depending on, if the parameter is estimated (1) or set to a fixed value(0) (see ``nominalValue``). -- ``initializationPriorType`` [STRING, OPTIONAL] +- ``prior`` [STRING, OPTIONAL] - Prior types used for sampling of initial points for estimation. Sampled - points are clipped to lie inside the parameter boundaries specified by - ``lowerBound`` and ``upperBound``. Defaults to ``parameterScaleUniform``. - - This is a hint for the optimization algorithm to start the optimization - process or for re-sampling random points. The initialization prior does not - change the objective function itself. Optimizers may choose to ignore this - information. + Prior types used for the objective function during estimation or inference. + If priors are specified for a subset of parameters, defaults to + ``parameterScaleUniform`` for any unspecified parameter. Possible prior types are: @@ -816,13 +811,10 @@ Detailed field description - *parameterScaleNormal*: Gaussian prior on original parameter scale - *parameterScaleLaplace*: Laplace prior on original parameter scale -- ``initializationPriorParameters`` [STRING, OPTIONAL] +- ``priorParameters`` [STRING, OPTIONAL] - Prior parameters used for sampling of initial points for estimation, - separated by a semicolon. Defaults to ``lowerBound;upperBound``. - The parameters are expected to be in linear scale except for the - ``parameterScale`` priors, where the prior parameters are expected to be - in parameter scale. + Prior parameters used for the objective function during estimation. + Defaults to ``lowerBound;upperBound``. So far, only numeric values will be supported, no parameter names. Parameters for the different prior types are: @@ -836,16 +828,6 @@ Detailed field description - parameterScaleNormal: mean; standard deviation (**not** variance) - parameterScaleLaplace: location; scale -- ``objectivePriorType`` [STRING, OPTIONAL] - - Prior types used for the objective function during estimation. - For possible values, see ``initializationPriorType``. - -- ``objectivePriorParameters`` [STRING, OPTIONAL] - - Prior parameters used for the objective function during estimation. - For more detailed documentation, see ``initializationPriorParameters``. - .. _v2_visualization_table: Visualization table @@ -1079,7 +1061,7 @@ and `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 -(``objectivePriorType`` and ``objectivePriorParameters`` columns, +(``prior`` and ``priorParameters`` columns, as described above), while for maximum likelihood estimation, the prior distributions are not specified. If priors are only specified From 15107a235567a5ae95932d86b7deba15cfb5b51e Mon Sep 17 00:00:00 2001 From: Sebastian Persson <46872750+sebapersson@users.noreply.github.com> Date: Tue, 25 Mar 2025 12:48:21 +0000 Subject: [PATCH 2/5] Apply suggestions from code review Co-authored-by: Daniel Weindl --- doc/v2/documentation_data_format.rst | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/doc/v2/documentation_data_format.rst b/doc/v2/documentation_data_format.rst index ee181012..0c5e0c61 100644 --- a/doc/v2/documentation_data_format.rst +++ b/doc/v2/documentation_data_format.rst @@ -795,8 +795,8 @@ Detailed field description - ``prior`` [STRING, OPTIONAL] - Prior types used for the objective function during estimation or inference. - If priors are specified for a subset of parameters, defaults to + Prior types used for used for the :ref:`MAP objective function and for Bayesian inference <_v2_objective_function>`. + If priors are specified for a subset of parameters, this defaults to ``parameterScaleUniform`` for any unspecified parameter. Possible prior types are: @@ -813,8 +813,8 @@ Detailed field description - ``priorParameters`` [STRING, OPTIONAL] - Prior parameters used for the objective function during estimation. - Defaults to ``lowerBound;upperBound``. + Prior parameters used for the :ref:`MAP objective function and for Bayesian inference <_v2_objective_function>`. + ``priorParameters`` is required if ``prior`` is non-empty. If ``prior`` is specified for any other parameter, and ``prior`` is empty for the given parameter, this defaults to ``lowerBound;upperBound``. So far, only numeric values will be supported, no parameter names. Parameters for the different prior types are: From 098313e8c7b20ff7038c593a4441352caa29726a Mon Sep 17 00:00:00 2001 From: Daniel Weindl Date: Tue, 25 Mar 2025 14:05:49 +0100 Subject: [PATCH 3/5] Apply suggestions from code review --- doc/v2/documentation_data_format.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/doc/v2/documentation_data_format.rst b/doc/v2/documentation_data_format.rst index 0c5e0c61..a5581d93 100644 --- a/doc/v2/documentation_data_format.rst +++ b/doc/v2/documentation_data_format.rst @@ -795,7 +795,7 @@ Detailed field description - ``prior`` [STRING, OPTIONAL] - Prior types used for used for the :ref:`MAP objective function and for Bayesian inference <_v2_objective_function>`. + Prior types used for used for the :ref:`MAP objective function and for Bayesian inference `. If priors are specified for a subset of parameters, this defaults to ``parameterScaleUniform`` for any unspecified parameter. @@ -813,7 +813,7 @@ Detailed field description - ``priorParameters`` [STRING, OPTIONAL] - Prior parameters used for the :ref:`MAP objective function and for Bayesian inference <_v2_objective_function>`. + Prior parameters used for the :ref:`MAP objective function and for Bayesian inference `. ``priorParameters`` is required if ``prior`` is non-empty. If ``prior`` is specified for any other parameter, and ``prior`` is empty for the given parameter, this defaults to ``lowerBound;upperBound``. So far, only numeric values will be supported, no parameter names. From eda159a6c972a74377fdf153ab2529c159647d24 Mon Sep 17 00:00:00 2001 From: Sebastian Persson <46872750+sebapersson@users.noreply.github.com> Date: Tue, 25 Mar 2025 16:25:16 +0000 Subject: [PATCH 4/5] Apply suggestions from code review Co-authored-by: Dilan Pathirana <59329744+dilpath@users.noreply.github.com> --- doc/v2/documentation_data_format.rst | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) diff --git a/doc/v2/documentation_data_format.rst b/doc/v2/documentation_data_format.rst index a5581d93..8912bc76 100644 --- a/doc/v2/documentation_data_format.rst +++ b/doc/v2/documentation_data_format.rst @@ -795,9 +795,10 @@ Detailed field description - ``prior`` [STRING, OPTIONAL] - Prior types used for used for the :ref:`MAP objective function and for Bayesian inference `. - If priors are specified for a subset of parameters, this defaults to - ``parameterScaleUniform`` for any unspecified parameter. + Prior types used for the :ref:`MAP objective function and for Bayesian inference `. + 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: @@ -814,7 +815,7 @@ Detailed field description - ``priorParameters`` [STRING, OPTIONAL] Prior parameters used for the :ref:`MAP objective function and for Bayesian inference `. - ``priorParameters`` is required if ``prior`` is non-empty. If ``prior`` is specified for any other parameter, and ``prior`` is empty for the given parameter, this defaults to ``lowerBound;upperBound``. + ``priorParameters`` is required if ``prior`` is non-empty. So far, only numeric values will be supported, no parameter names. Parameters for the different prior types are: From 3e2953862a11143443408cdfd0505c5770f836ab Mon Sep 17 00:00:00 2001 From: sebapersson Date: Tue, 25 Mar 2025 20:16:05 +0000 Subject: [PATCH 5/5] Add brief change information --- doc/v2/documentation_data_format.rst | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/doc/v2/documentation_data_format.rst b/doc/v2/documentation_data_format.rst index 60f91314..9fc43c14 100644 --- a/doc/v2/documentation_data_format.rst +++ b/doc/v2/documentation_data_format.rst @@ -143,6 +143,14 @@ PEtab 2.0.0 is a major update of the PEtab format. The main changes are: parameter priors was not well-defined. To obtain the same effect, the model parameters can be transformed in the model file. +* The ``initializationPriorType`` and ``initializationPriorParameters`` + columns of the :ref:`v2_parameters_table` are removed. Initialization + 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 + ``priorParameters``, respectively. This change was made to simplify + the PEtab format. .. _v2_model: .. _v2_model_entities: