@@ -159,6 +159,19 @@ PEtab 2.0.0 is a major update of the PEtab format. The main changes are:
159
159
clearer. The ``log10 `` transformation has been removed, since this was mostly
160
160
relevant for visualization purposes, and the same effect can be achieved by
161
161
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.
162
175
* The visualization table has been removed. The PEtab v1 visualization table
163
176
was not well-defined and not widely used. Visualization is handled by the
164
177
PEtab Python library which also provides documentation on the respective
@@ -494,24 +507,23 @@ Detailed field description
494
507
495
508
- ``observableParameters `` [NUMERIC, STRING OR NULL, OPTIONAL]
496
509
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 >` .
508
521
509
522
Different lines for the same ``observableId `` may specify different
510
523
parameters. This may be used to account for condition-specific or
511
524
batch-specific parameters. This will translate into an extended estimation
512
525
parameter vector.
513
526
514
- All placeholders defined in the observation model must be overwritten here.
515
527
If there are no placeholders used, this column may be omitted.
516
528
517
529
- ``noiseParameters `` [NUMERIC, STRING OR NULL, OPTIONAL]
@@ -591,15 +603,22 @@ Detailed field description
591
603
* ``observableFormula `` [STRING]
592
604
593
605
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.
603
622
604
623
* ``noiseFormula `` [NUMERIC|STRING]
605
624
@@ -612,30 +631,40 @@ Detailed field description
612
631
observable.
613
632
614
633
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
639
668
640
669
* ``noiseDistribution `` [STRING, OPTIONAL]
641
670
0 commit comments