diff --git a/doc/v2/documentation_data_format.rst b/doc/v2/documentation_data_format.rst index 5141d29b..04810d50 100644 --- a/doc/v2/documentation_data_format.rst +++ b/doc/v2/documentation_data_format.rst @@ -514,17 +514,17 @@ order: *(wrapped for readability)* -+-----+----------------------------+----------------------------+ -| ... | [observableParameters] | [noiseParameters] | -+=====+============================+============================+ -| ... | LIST[parameterId\|NUMERIC] | LIST[parameterId\|NUMERIC] | -+-----+----------------------------+----------------------------+ -| ... | | | -+-----+----------------------------+----------------------------+ -| ... | | | -+-----+----------------------------+----------------------------+ -| ... | ... | ... | -+-----+----------------------------+----------------------------+ ++-----+----------------------------------------+----------------------------------------+ +| ... | [observableParameters] | [noiseParameters] | ++=====+========================================+========================================+ +| ... | LIST[parameterId\|NUMERIC\|inf\|-inf] | LIST[parameterId\|NUMERIC\|inf\|-inf] | ++-----+----------------------------------------+----------------------------------------+ +| ... | | | ++-----+----------------------------------------+----------------------------------------+ +| ... | | | ++-----+----------------------------------------+----------------------------------------+ +| ... | ... | ... | ++-----+----------------------------------------+----------------------------------------+ Additional (non-standard) columns may be added. @@ -567,7 +567,8 @@ Detailed field description the condition change is applied before the observable is evaluated (see :ref:`v2_reinitialization_semantics` for details). -- ``observableParameters`` [LIST[parameterId, NUMERIC], NULL, OPTIONAL] +- ``observableParameters`` [LIST[parameterId, NUMERIC, ``inf``, ``-inf``], + NULL, OPTIONAL] Measurement-specific overrides for placeholder parameters in the `observableFormula` declared in the @@ -582,8 +583,12 @@ Detailed field description observable in the observable table. I.e., if the observable table contains no observable placeholders for the given observable, this field must be empty. - The values may be either numeric values or the IDs of parameters from the - :ref:`parameter table `. + The values may be either numeric values, ``inf``, ``-inf``, or the IDs of + parameters from the :ref:`parameter table `. + + .. note:: + + Infinite values are valid as per :ref:`erratum E3 `. Different measurements for the same ``observableId`` may specify different values. This may be used to account for condition-specific or @@ -592,7 +597,8 @@ Detailed field description If none of the observables referenced in a given measurement table use any observable placeholders, this column may be omitted there. -- ``noiseParameters`` [LIST[parameterId, NUMERIC], NULL, OPTIONAL] +- ``noiseParameters`` [LIST[parameterId, NUMERIC, ``inf``, ``-inf``], + NULL, OPTIONAL] Measurement-specific overrides for placeholder parameters in the `noiseFormula` declared in the @@ -607,8 +613,12 @@ Detailed field description observable in the observable table. I.e., if the observable table contains no noise placeholders for the given observable, this field must be empty. - The values may be either numeric values or the IDs of parameters from the - :ref:`parameter table `. + The values may be either numeric values, ``inf``, ``-inf``, or the IDs of + parameters from the :ref:`parameter table `. + + .. note:: + + Infinite values are valid as per :ref:`erratum E3 `. Different measurements for the same ``observableId`` may specify different values. This may be used to account for condition-specific or @@ -861,15 +871,15 @@ it *may* include: One row per parameter with arbitrary order of rows and columns: -+-------------+-----------------+---------------+--------------+--------------+-------------+-----+ -| parameterId | [parameterName] | lowerBound | upperBound | nominalValue | estimate | ... | -+=============+=================+===============+==============+==============+=============+=====+ -| PETAB_ID | [STRING] | NUMERIC\|-inf | NUMERIC\|inf | NUMERIC | true\|false | ... | -+-------------+-----------------+---------------+--------------+--------------+-------------+-----+ -| k1 | | 1e-5 | 1e5 | 100 | true | ... | -+-------------+-----------------+---------------+--------------+--------------+-------------+-----+ -| ... | ... | ... | ... | ... | ... | ... | -+-------------+-----------------+---------------+--------------+--------------+-------------+-----+ ++-------------+-----------------+---------------+--------------+--------------------+-------------+-----+ +| parameterId | [parameterName] | lowerBound | upperBound | nominalValue | estimate | ... | ++=============+=================+===============+==============+====================+=============+=====+ +| PETAB_ID | [STRING] | NUMERIC\|-inf | NUMERIC\|inf | NUMERIC\|inf\|-inf | true\|false | ... | ++-------------+-----------------+---------------+--------------+--------------------+-------------+-----+ +| k1 | | 1e-5 | 1e5 | 100 | true | ... | ++-------------+-----------------+---------------+--------------+--------------------+-------------+-----+ +| ... | ... | ... | ... | ... | ... | ... | ++-------------+-----------------+---------------+--------------+--------------------+-------------+-----+ *(wrapped for readability)* @@ -919,12 +929,17 @@ Detailed field description ``inf`` indicates that the parameter is not bounded from above. Optional, if ``estimate==false``. -- ``nominalValue`` [NUMERIC] +- ``nominalValue`` [NUMERIC or ``inf`` or ``-inf``] Some parameter value to be used if the parameter is not subject to estimation (see ``estimate`` below). Optional, unless ``estimate==false``. + .. note:: + + Infinite nominal values are valid as per + :ref:`erratum E3 `. + - ``estimate`` [``true`` | ``false``] ``true`` or ``false`` (case-sensitive), depending on whether the parameter diff --git a/doc/v2/errata.rst b/doc/v2/errata.rst index b9f6f4ff..a0f4fcb7 100644 --- a/doc/v2/errata.rst +++ b/doc/v2/errata.rst @@ -40,7 +40,7 @@ parameter bounds to the prior's domain (e.g., ``0`` and ``inf`` for * ``lowerBound`` may be ``-inf``, ``upperBound`` may be ``inf``. ``inf`` as lower bound and ``-inf`` as upper bound remain invalid. - ``nominalValue`` remains ``NUMERIC``, i.e., finite. + ``nominalValue`` is addressed by :ref:`erratum E3 `. * If priors are specified for any parameter, the default ``uniform(lowerBound, upperBound)`` prior for the remaining parameters is improper for infinite bounds. Therefore, in this case, a proper prior @@ -72,3 +72,39 @@ contrast, defines the prior only for the estimated parameters. * The default ``uniform(lowerBound, upperBound)`` prior applies only to estimated parameters, and only if priors are specified for any estimated parameter. + +.. _v2_errata_e3: + +E3: Infinite parameter values +----------------------------- + +:Type: technical +:Affects: :ref:`v2_parameter_table`, :ref:`v2_measurement_table` +:Discussion: `#685 `__, + `#687 `__ + +**Problem:** +``nominalValue`` was specified as ``NUMERIC``, which excludes infinite +values. At the same time, the list of changes from PEtab 1 states that the +effect of the removed ``parameterScale`` column can be obtained by +transforming the model parameters in the model file. This does not hold for +fixed parameters on the boundary of their domain: in PEtab 1, a parameter +``k1`` with ``parameterScale=log`` can be fixed to ``nominalValue=0`` +(nominal values are on linear scale). For a model reparameterized in terms of +``log_k1``, the corresponding nominal value is ``-inf``. + +The same applies to numeric values in ``observableParameters`` and +``noiseParameters`` in the measurement table, which were specified as +``NUMERIC``. Since these entries may also reference parameters from the +parameter table, an infinite value could be given via a parameter, but not +directly. + +**Resolution:** + +* ``nominalValue`` may be ``inf`` or ``-inf``. ``NaN`` remains invalid. +* Numeric values in ``observableParameters`` and ``noiseParameters`` may be + ``inf`` or ``-inf``. ``NaN`` remains invalid. +* For parameters with ``estimate==false``, infinite nominal values are applied + as specified. +* For parameters with ``estimate==true``, ``nominalValue`` does not affect the + problem definition, so infinite values have no further implications.