v2: Clarification MultiModel format

doc/v2/documentation_data_format.rst

@@ -154,7 +154,14 @@ PEtab 2.0.0 is a major update of the PEtab format. The main changes are:
   the PEtab format.
 * The admissible values for ``estimate`` in the :ref:`v2_parameters_table`
   are now ``true`` and ``false`` instead of ``1`` and ``0``.
-* 
+* Support for new parameter prior distributions in the
+  :ref:`v2_parameters_table`, and clarification that bounds truncate the
+  prior distributions.
+* The ``observableTransformation`` column of the :ref:`v2_observables_table`
+  has been combined with the ``noiseDistribution`` column to make its intent
+  clearer. The ``log10`` transformation has been removed, since this was mostly
+  relevant for visualization purposes, and the same effect can be achieved by
+  rescaling the parameters of the respective (natural) log-distributions.
 
 .. _v2_model:
 .. _v2_model_entities:
@@ -190,7 +197,7 @@ Conditions table
 The optional conditions table defines discrete changes to the simulated model. 
 These (sets of) changes typically represent interventions, perturbations, or 
 changes in the environment of the system of interest. These modifications are 
-referred to as experimental) *conditions*.
+referred to as (experimental) *conditions*.
 
 Conditions are applied at specific time points, which are defined in the
 :ref:`v2_experiments_table`. This allows for the specification of time
@@ -280,9 +287,6 @@ phases, following the logic of the event assignments in a single SBML event.
    * For subsequent time periods, the *current* values are taken from the
      simulation results at the end of the preceding time period.
 
-   * For problems involving multiple models, any variable not present in 
-     the currently simulated model will default to a value of zero.
-
 2. **Assignment of the evaluated ``targetValues`` to their targets**
 
    All evaluated ``targetValues`` are simultaneously assigned to their
@@ -619,15 +623,12 @@ Detailed field description
 * ``observableFormula`` [STRING]
 
   Observation function as plain text formula expression.
-  May contain any symbol defined any of the employed models (including model 
+  May contain any symbol defined in a model (including model 
   time ``time``) or parameter table. In the simplest case, for SBML models, 
   just a species ID or an ``AssignmentRule`` target. Additionally, any observable ID
   introduced in the observable table may be referenced, but circular definitions
   must be avoided.
 
-  In problems with multiple models, symbols not defined in the currently simulated 
-  model default to a value of zero.
-
   May introduce new parameters of the form ``observableParameter${n}_${observableId}``,
   which are overridden by ``observableParameters`` in the measurement table
   (see description there).
@@ -785,7 +786,7 @@ Detailed field description
 - ``parameterId`` [PETAB_ID, REQUIRED]
 
   The ``parameterId`` of the parameter described in this row. This has to match
-  the ID of a parameter specified any model, a parameter introduced
+  the ID of a parameter specified at least one model, a parameter introduced
   as override in the condition table, or a parameter occurring in the
   ``observableParameters`` or ``noiseParameters`` column of the measurement table
   (see above).
@@ -1103,7 +1104,7 @@ Detailed field description
 - ``modelEntityId`` [STRING or empty, REQUIRED]
 
   A globally unique identifier defined in any model, or empty if the entity is
-  not present any model. This does not have to be a valid PEtab identifier.
+  not present in any model. This does not have to be a valid PEtab identifier.
   Rows with empty ``modelEntityId`` serve as annotations only.
 
   For example, in SBML, local parameters may be referenced as
@@ -1145,14 +1146,51 @@ easy validation:
 Parameter estimation problems combining multiple models
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-Parameter estimation problems can involve multiple models, with a specific model
-assigned to each individual data point. However, all tables in a PEtab problem apply
-uniformly to all models. As a result:
-- Multiple models may need to be simulated for a single experiment.
-- Each model may be simulated for a distinct subset of experiments.
-- The number of conditions that must be simulated for an experiment may vary depending 
-  on the model used.
-- Each parameter in the parameter table hase the same value across all models.
+Purpose
+^^^^^^^
+PEtab supports defining multiple models within a single problem specification. This
+feature is designed to enable users to define experiment-specific model variants or
+submodels. Rather than implementing a single global, parameterized model, users can
+define multiple smaller, self-contained models that differ structurally as needed.
+
+This approach offers several benefits:
+
+- Simplified model definition for users, as each variant can be independently 
+specified.
+- Improved simulation performance for tool developers, as smaller models can be 
+simulated more efficiently.
+
+Scope and Application
+^^^^^^^^^^^^^^^^^^^^^
+While multiple models are intended to be applied to different experiments, model
+selection is specified at the level of individual data points in the 
+:ref:`v2_measurements_table`. This design enables:
+
+- Reuse of experiments across models.
+- Fine-grained model-to-data assignment.
+
+With the exception of the :ref:`v2_measurements_table`, all other PEtab tables apply
+uniformly to all models.
+
+This design has several implications:
+
+- A single experiment may require simulations using multiple models.
+- Each model may be associated with a distinct subset of experiments.
+- The number of conditions to be simulated for a model-specific instance
+of an experiment may vary across models.
+- Each parameter defined in the :ref:`v2_parameters_table` has a shared value across all 
+models.
+
+Validation Rules
+^^^^^^^^^^^^^^^^
+For any given model Only those experiments and observables that appear in the 
+same rows of the :ref:`v2_measurements_table` need to be valid. This means that all 
+symbols used in the corresponding ``observableFormula`` and all symbols assigned 
+in the associated condition definitions must be defined in the model.
+
+Conditions and observables that are not applied to a model do not need to be 
+valid for that model.
+
 
 .. _v2_objective_function: