From 54694d1df214cbf6e6b47c74a15e549710189a16 Mon Sep 17 00:00:00 2001 From: Daniel Weindl Date: Thu, 24 Jul 2025 20:45:24 +0200 Subject: [PATCH 1/6] v2: Clarify model initialization Clarify that the parameter table is applied before initial assignments are executed. --- doc/v2/documentation_data_format.rst | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/doc/v2/documentation_data_format.rst b/doc/v2/documentation_data_format.rst index 43e292e8..6bd93b78 100644 --- a/doc/v2/documentation_data_format.rst +++ b/doc/v2/documentation_data_format.rst @@ -307,6 +307,12 @@ phases, following the logic of the event assignments in a single SBML event. * For the initial time period of an experiment, *current* values are determined by the initial conditions defined in the model. + For the all parameters that occur in the parameter table, the + respective externally provided values for any estimated parameters, + or ``nominalValue`` for any non-estimated parameters are used for model + initialization. Any model constructs that would override the initial + values of a model entity that occurs in the parameter table are ignored. + Constructs defining initial values of model entities (e.g., SBML's *initialAssignments*) are applied only once at the start of the first time period and are not re-evaluated in later time periods. The start From 92ff242c6887b44d9ba3e534ec3938420de944ca Mon Sep 17 00:00:00 2001 From: Daniel Weindl Date: Fri, 25 Jul 2025 16:17:59 +0200 Subject: [PATCH 2/6] retry --- doc/v2/documentation_data_format.rst | 42 ++++++++++++++++++++-------- 1 file changed, 30 insertions(+), 12 deletions(-) diff --git a/doc/v2/documentation_data_format.rst b/doc/v2/documentation_data_format.rst index 6bd93b78..c3de3eda 100644 --- a/doc/v2/documentation_data_format.rst +++ b/doc/v2/documentation_data_format.rst @@ -305,18 +305,8 @@ phases, following the logic of the event assignments in a single SBML event. variables in the respective expressions. * For the initial time period of an experiment, *current* values are - determined by the initial conditions defined in the model. - - For the all parameters that occur in the parameter table, the - respective externally provided values for any estimated parameters, - or ``nominalValue`` for any non-estimated parameters are used for model - initialization. Any model constructs that would override the initial - values of a model entity that occurs in the parameter table are ignored. - - Constructs defining initial values of model entities (e.g., SBML's - *initialAssignments*) are applied only once at the start of the first - time period and are not re-evaluated in later time periods. The start - time of the first time period is defined by the respective experiment. + determined by the initial conditions defined in the model and the current + values of parameter table parameters (see also :ref:`v2_initialization`). * For subsequent time periods, the *current* values are taken from the simulation results at the end of the preceding time period. @@ -813,6 +803,8 @@ One row per parameter with arbitrary order of rows and columns: Additional columns may be added. +See :ref:`v2_initialization` for details on how and when the values of +parameter table parameters are applied. Detailed field description ~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -1109,6 +1101,32 @@ Conditions and observables that are not applied to a model do not need to be valid for that model. +.. _v2_initialization: + +Initialization and parameter application +---------------------------------------- + +The following describes how the model is initialized and how other PEtab +parameter values are applied before the simulation starts. + +1. The model is initialized independently of any other PEtab constructs. + Model constructs defining initial values of model entities (e.g., SBML's + *initialAssignments*) are applied now. Any event trigger evaluation + is deferred until the first time point of the simulation (step 4 below). + The current time is the initial time of the model, or 0 if not specified. + +2. Parameters values for parameters that occur in the parameter table are + applied. For estimated parameters, the respective externally provided values + are applied and for non-estimated parameters, the nominal values + from the parameter table are applied. + +3. The time is set to the start time of the first period of the given + experiment (or 0 if there is no explicit experiment), and any + experiment-specific conditions provided for the first period are applied + (see :ref:`v2_reinitialization_semantics` for details). + +4. Simulation starts. + .. _v2_objective_function: Frequentist vs. Bayesian inference From 6892c393d34b3c223bd9a92a42fa37e3fb0fe5d1 Mon Sep 17 00:00:00 2001 From: Daniel Weindl Date: Tue, 19 Aug 2025 22:47:20 +0200 Subject: [PATCH 3/6] draft 2c --- doc/v2/documentation_data_format.rst | 107 ++++++++++++++++----------- 1 file changed, 64 insertions(+), 43 deletions(-) diff --git a/doc/v2/documentation_data_format.rst b/doc/v2/documentation_data_format.rst index c3de3eda..bb8ae58e 100644 --- a/doc/v2/documentation_data_format.rst +++ b/doc/v2/documentation_data_format.rst @@ -296,22 +296,19 @@ Detailed field description Detailed semantics ~~~~~~~~~~~~~~~~~~ -All changes defined in the condition table are applied in five consecutive -phases, following the logic of the event assignments in a single SBML event. +See :ref:`v2_initialization_semantics` for how the changes for the initial +period of an experiment are applied and how the model is initialized. +For any subsequent time period, the changes defined in the condition table +are applied in five consecutive phases: 1. **Evaluation of** ``targetValues`` ``targetValues`` are first evaluated using the *current* values of all variables in the respective expressions. - - * For the initial time period of an experiment, *current* values are - determined by the initial conditions defined in the model and the current - values of parameter table parameters (see also :ref:`v2_initialization`). - - * For subsequent time periods, the *current* values are taken from the - simulation results at the end of the preceding time period. - A special case is simulation time (``time``), - which is set to the start time of the current time period. + The *current* values are taken from the simulation results at the end of the + preceding time period. + A special case is simulation time (``time``), + which is set to the start time of the current time period. 2. **Assignment of the evaluated** ``targetValues`` **to their targets** @@ -319,26 +316,30 @@ phases, following the logic of the event assignments in a single SBML event. respective targets. It is invalid to apply multiple assignments to the same target at the same time. - * These assignments respect language specific interpretations of which - variables are *atomic* or *derived*/*algebraic*. Most notably, SBML - considers species amounts and compartment sizes but not - concentrations to be *atomic*. This means that any entry that has a - ``targetId`` that refers to a species with - ``hasOnlySubstanceUnits=false`` will have its ``targetValue`` - (interpreted as concentration) converted to amounts using the - **current** compartment size and then applied to the target's amount. - For further details, refer to SBML semantic test suite case `01779 - `_. + The interpretation of the assigned value depends on the type of the + model and the target entity. + For example, for an SBML model and a ``targetId`` referring to a species, + the ``targetValue`` will override the current amount of the species + if ``hasOnlySubstanceUnits=true`` (*amount-based species*), + or the current concentration if ``hasOnlySubstanceUnits=false`` + (*concentration-based species*). + + If the target is a compartment, the compartment size is set to the + evaluated value of the ``targetValue`` expression. + The value of a species in such a compartment is not changed by this + assignment. I.e., for an amount-based species, the amount of the species + will be preserved (the concentration may change accordingly), + and for a concentration-based species, the concentration will be preserved + (the amount may change accordingly). + Mind that this differs from the behavior of an SBML event assignment where + compartment size changes always preserve the amounts of species in that + compartment. 3. **Update of derived variables** After target values have been assigned, all derived variables (i.e., - algebraic entities such as SBML assignment rules or PySB expressions) are updated. - - * These updates follow language specific rules of which variables are - *atomic* or *derived*/*algebraic*. For example, SBML treats species - concentrations to be *derived*, meaning they are recomputed based on - (updated) species amounts and corresponding compartment sizes. + algebraic entities such as SBML assignment rules or PySB expressions) + are updated. 4. **Events and finalization** @@ -803,7 +804,7 @@ One row per parameter with arbitrary order of rows and columns: Additional columns may be added. -See :ref:`v2_initialization` for details on how and when the values of +See :ref:`v2_initialization_semantics` for details on how and when the values of parameter table parameters are applied. Detailed field description @@ -1101,31 +1102,51 @@ Conditions and observables that are not applied to a model do not need to be valid for that model. -.. _v2_initialization: +.. _v2_initialization_semantics: Initialization and parameter application ---------------------------------------- The following describes how the model is initialized and how other PEtab parameter values are applied before the simulation starts. +This procedure is executed for each model and experiment combination +defined in the PEtab problem. + +1. Pre-initialization + + 1. Parameters values for parameters that occur in the parameter table are + applied to the uninitialized model. + For estimated parameters, the respective externally provided values + are applied and for non-estimated parameters, the nominal values + from the parameter table are applied. + + 2. The time is set to the start time of the first period of the given + experiment (or 0 if there is no explicit experiment), and any + experiment-specific conditions provided for the first period are applied + (see :ref:`v2_reinitialization_semantics` for details). + Target value expressions for the first period must not refer to model + entities that are not also listed in the parameter table. + + This pre-initialization replaces any model-internal initial values + (or initialization constructs such as SBML's *initialAssignments*) + that would alter the initial time, the values of the parameters contained + in the parameter table or any target values from the condition table. + +2. Model initialization + + The model is initialized according to the model semantics, e.g., by + evaluating the initial assignments or applying the initial values of + state variables. -1. The model is initialized independently of any other PEtab constructs. - Model constructs defining initial values of model entities (e.g., SBML's - *initialAssignments*) are applied now. Any event trigger evaluation - is deferred until the first time point of the simulation (step 4 below). - The current time is the initial time of the model, or 0 if not specified. +3. Simulation -2. Parameters values for parameters that occur in the parameter table are - applied. For estimated parameters, the respective externally provided values - are applied and for non-estimated parameters, the nominal values - from the parameter table are applied. + Model simulation starts with evaluating any event triggers at the initial + time, applying pending event assignments, and evaluating the observables + at the initial time (Steps 4 and 5 in :ref:`v2_reinitialization_semantics`). -3. The time is set to the start time of the first period of the given - experiment (or 0 if there is no explicit experiment), and any - experiment-specific conditions provided for the first period are applied - (see :ref:`v2_reinitialization_semantics` for details). + For any subsequent experiment periods, the steps described in + :ref:`v2_reinitialization_semantics` are applied at their start times. -4. Simulation starts. .. _v2_objective_function: From aabcedf424abb0eeb193c3372eddb88e10fa01f0 Mon Sep 17 00:00:00 2001 From: Daniel Weindl Date: Wed, 20 Aug 2025 12:34:33 +0200 Subject: [PATCH 4/6] Update doc/v2/documentation_data_format.rst Co-authored-by: Dilan Pathirana <59329744+dilpath@users.noreply.github.com> --- doc/v2/documentation_data_format.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/v2/documentation_data_format.rst b/doc/v2/documentation_data_format.rst index bb8ae58e..a73fb305 100644 --- a/doc/v2/documentation_data_format.rst +++ b/doc/v2/documentation_data_format.rst @@ -1116,7 +1116,7 @@ defined in the PEtab problem. 1. Parameters values for parameters that occur in the parameter table are applied to the uninitialized model. - For estimated parameters, the respective externally provided values + For estimated parameters, the respective externally-provided values are applied and for non-estimated parameters, the nominal values from the parameter table are applied. From b2e8320ee1b7785efb6eaa484b9340788a881f04 Mon Sep 17 00:00:00 2001 From: Daniel Weindl Date: Wed, 20 Aug 2025 12:45:54 +0200 Subject: [PATCH 5/6] .. --- 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 a73fb305..b0617ef6 100644 --- a/doc/v2/documentation_data_format.rst +++ b/doc/v2/documentation_data_format.rst @@ -142,10 +142,10 @@ PEtab 2.0.0 is a major update of the PEtab format. The main changes are: **Figure 3: A comparison of simulations in PEtab v1 and v2.** * Support for math expressions in the condition table - (:ref:`v2_condition_table`). + (:ref:`v2_condition_table`, :ref:`v2_math_expressions`). * Clarification and specification of various previously underspecified aspects, including overriding values via the condition table - (:ref:`v2_math_expressions`). + (:ref:`v2_initialization_semantics`, :ref:`v2_reinitialization_semantics`). * Support for format :ref:`extensions `. * Observable IDs can now be used in observable and noise formulas (:ref:`v2_observable_table`). @@ -804,8 +804,8 @@ One row per parameter with arbitrary order of rows and columns: Additional columns may be added. -See :ref:`v2_initialization_semantics` for details on how and when the values of -parameter table parameters are applied. +See :ref:`v2_initialization_semantics` for details on how and when the values +of parameter table parameters are applied. Detailed field description ~~~~~~~~~~~~~~~~~~~~~~~~~~ From 546cfcda966e052406edd29d4cb76f1cc15dbaf9 Mon Sep 17 00:00:00 2001 From: Daniel Weindl Date: Tue, 26 Aug 2025 09:39:21 +0200 Subject: [PATCH 6/6] uninitialized --- doc/v2/documentation_data_format.rst | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/doc/v2/documentation_data_format.rst b/doc/v2/documentation_data_format.rst index 08e9585b..2f88795e 100644 --- a/doc/v2/documentation_data_format.rst +++ b/doc/v2/documentation_data_format.rst @@ -1110,6 +1110,10 @@ defined in the PEtab problem. 1. Parameters values for parameters that occur in the parameter table are applied to the uninitialized model. + *Uninitialized* means that no model-internal initial values have been + computed yet (e.g., in SBML models, no initial assignments have been + evaluated and no derived initial quantities such as concentrations have + been computed yet). For estimated parameters, the respective externally-provided values are applied and for non-estimated parameters, the nominal values from the parameter table are applied.