Skip to content

Commit 0b355cc

Browse files
committed
Merge branch 'main' into v2_multimodel
2 parents 637c570 + 921989a commit 0b355cc

File tree

1 file changed

+74
-45
lines changed

1 file changed

+74
-45
lines changed

doc/v2/documentation_data_format.rst

Lines changed: 74 additions & 45 deletions
Original file line numberDiff line numberDiff line change
@@ -159,6 +159,19 @@ PEtab 2.0.0 is a major update of the PEtab format. The main changes are:
159159
clearer. The ``log10`` transformation has been removed, since this was mostly
160160
relevant for visualization purposes, and the same effect can be achieved by
161161
rescaling the parameters of the respective (natural) log-distributions.
162+
* The ``observableFormula`` field in the :ref:`v2_observables_table` must not
163+
contain any observable IDs. This was previously allowed, but it was not
164+
well-defined how to deal with placeholder parameters in this case.
165+
The ``noiseFormula`` field may contain only the observable ID of the
166+
respective observable itself, but no other observable IDs for the same
167+
reason.
168+
* Placeholders for measurement-specific parameters in ``observableFormula``
169+
and ``noiseFormula`` are now declared using the
170+
``observablePlaceholders`` and ``noisePlaceholders`` fields in the
171+
:ref:`v2_observables_table`. This replaces the previous
172+
``observableParameter${n}_${observableId}`` syntax. The new approach is more
173+
explicit and allows for more descriptive and shorter names for the
174+
placeholders.
162175
* The visualization table has been removed. The PEtab v1 visualization table
163176
was not well-defined and not widely used. Visualization is handled by the
164177
PEtab Python library which also provides documentation on the respective
@@ -494,24 +507,23 @@ Detailed field description
494507

495508
- ``observableParameters`` [NUMERIC, STRING OR NULL, OPTIONAL]
496509

497-
This field allows overriding or introducing condition-specific versions of
498-
output parameters defined in the observation model. The model can define
499-
observables (see below) containing place-holder parameters which can be
500-
replaced by condition-specific dynamic or constant parameters. Placeholder
501-
parameters must be named ``observableParameter${n}_${observableId}``
502-
with ``n`` ranging from 1 (not 0) to the number of placeholders for the given
503-
observable, without gaps.
504-
If the observable specified under ``observableId`` contains no placeholders,
505-
this field must be empty. If it contains ``n > 0`` placeholders, this field
506-
must hold ``n`` semicolon-separated numeric values or parameter names. No
507-
trailing semicolon must be added.
510+
Measurement-specific overrides for placeholder parameters declared in the
511+
observation model.
512+
513+
The :ref:`observables table <v2_observables_table>` allows marking some
514+
parameters as measurement-specific (see below). Their values for a given
515+
measurement are specified in this column. The values are separated by
516+
semicolons. The order and number of values must match the order and number of
517+
placeholders in the ``observablePlaceholders`` field of the corresponding
518+
observable in the observable table. The values may be
519+
either numeric values or the IDs of parameters from the
520+
:ref:`parameters table <v2_parameters_table>`.
508521

509522
Different lines for the same ``observableId`` may specify different
510523
parameters. This may be used to account for condition-specific or
511524
batch-specific parameters. This will translate into an extended estimation
512525
parameter vector.
513526

514-
All placeholders defined in the observation model must be overwritten here.
515527
If there are no placeholders used, this column may be omitted.
516528

517529
- ``noiseParameters`` [NUMERIC, STRING OR NULL, OPTIONAL]
@@ -591,15 +603,22 @@ Detailed field description
591603
* ``observableFormula`` [STRING]
592604

593605
Observation function as plain text formula expression.
594-
May contain any symbol defined in a model (including model
595-
time ``time``) or parameter table. In the simplest case, for SBML models,
596-
just a species ID or an ``AssignmentRule`` target. Additionally, any observable ID
597-
introduced in the observable table may be referenced, but circular definitions
598-
must be avoided.
599-
600-
May introduce new parameters of the form ``observableParameter${n}_${observableId}``,
601-
which are overridden by ``observableParameters`` in the measurement table
602-
(see description there).
606+
The expression may contain any symbol defined in a model,
607+
the mapping table or the parameter table.
608+
Often, this is just the ID of a state variable.
609+
Furthermore, any parameters introduced through the ``observablePlaceholders``
610+
field for the given observable may be used (see below).
611+
612+
* ``observablePlaceholders`` [LIST[PETAB_ID], OPTIONAL]
613+
614+
A semicolon-separated list of valid PEtab identifiers that have not been
615+
introduced elsewhere, marking them as placeholders for
616+
measurement-specific parameters.
617+
The actual values for these parameters are specified in the
618+
``observableParameters`` field of the measurement table.
619+
The ordering and number of values in ``observableParameters`` must match the
620+
ordering and number of placeholders in ``observablePlaceholders``.
621+
For an example, see the description of ``noisePlaceholders`` below.
603622

604623
* ``noiseFormula`` [NUMERIC|STRING]
605624

@@ -612,30 +631,40 @@ Detailed field description
612631
observable.
613632

614633
Alternatively, some formula expression can be provided to specify
615-
more complex noise models. The formula may reference any uniquely identifiable
616-
model entity with PEtab-compatible identifier or any observable ID
617-
specified in the observable table.
618-
619-
A noise model which accounts for relative and
620-
absolute contributions could, e.g., be defined as::
621-
622-
noiseParameter1_observable_pErk + noiseParameter2_observable_pErk * observable_pErk
623-
624-
with ``noiseParameter1_observable_pErk`` denoting the absolute and
625-
``noiseParameter2_observable_pErk`` the relative contribution for the
626-
observable ``observable_pErk`` corresponding to species ``pErk``.
627-
IDs of noise parameters
628-
that need to have different values for different measurements have the
629-
structure: ``noiseParameter${indexOfNoiseParameter}_${observableId}``
630-
to facilitate automatic recognition. The specific values or parameters are
631-
assigned in the ``noiseParameters`` field of the *measurement table*
632-
(see above). Any parameters named ``noiseParameter${1..n}_${observableId}``
633-
*must* be overwritten in the measurement table.
634-
635-
Noise formulae can also contain observable parameter overrides, which are
636-
described under ``observableFormula`` in this table. An example is when an
637-
observable formula contains an override, and a proportional noise model is
638-
used, which means the observable formula also appears in the noise formula.
634+
more complex noise models. The same rules as for ``observableFormula``
635+
apply here. In addition, the current observable ID may be used to refer to
636+
the ``observableFormula`` expression.
637+
In addition to the placeholders declared in ``observablePlaceholders``,
638+
placeholders for noise parameters that are declared in ``noisePlaceholders``
639+
may be used.
640+
641+
* ``noisePlaceholders`` [LIST[PETAB_ID], OPTIONAL]
642+
643+
A semicolon-delimited list of valid PEtab identifiers that have not been
644+
introduced elsewhere, marking them as placeholders for
645+
measurement-specific noise parameters.
646+
The actual values for these parameters are specified in the
647+
``noiseParameters`` field of the measurement table.
648+
The ordering and number of values in ``noiseParameters`` must match the
649+
ordering and number of placeholders in ``noisePlaceholders``.
650+
651+
For example, a noise model that accounts for measurement-specific relative
652+
and absolute contributions for some observable with the ID
653+
``observable_pErk`` could be defined as::
654+
655+
noise_offset_pErk + noise_scale_pErk * observable_pErk
656+
657+
with ``noise_offset_pErk`` denoting the absolute and
658+
``noise_scale_pErk`` the relative contribution.
659+
The corresponding ``noisePlaceholders`` would be::
660+
661+
noise_offset_pErk;noise_scale_pErk
662+
663+
and the ``noiseParameters`` in the measurement table could be, for example,
664+
``0.1;0.2`` resulting in::
665+
666+
noise_offset_pErk = 0.1
667+
noise_scale_pErk = 0.2
639668

640669
* ``noiseDistribution`` [STRING, OPTIONAL]
641670

0 commit comments

Comments
 (0)