v2: Clarification MultiModel format

doc/v2/_static/petab_schema_v2.yaml

@@ -22,96 +22,77 @@ properties:
       File name (absolute or relative) or URL to PEtab parameter table
       containing parameters of all models listed in `problems`. A single
       table may be split into multiple files and described as an array here.
-  problems:
-    type: array
-    description: |
-      One or multiple PEtab problems (sets of model, condition, observable
-      and measurement files). If different model and data files are
-      independent, they can be specified as separate PEtab problems, which
-      may allow more efficient handling. Files in one problem cannot refer
-      to models entities or data specified inside another problem.
-    items:
 
-      type: object
-      description: |
-        A set of PEtab model, observable and measurement
-        files and optional condition, experiment, and visualization files.
-
-      properties:
-
-        model_files:
-          type: object
-          description: One or multiple models
-
-          # the model ID
-          patternProperties:
-            "^[a-zA-Z_]\\w*$":
-              type: object
-              properties:
-                location:
-                  type: string
-                  description: Model file name or URL
-                language:
-                  type: string
-                  description: |
-                    Model language, e.g., 'sbml', 'cellml', 'bngl', 'pysb'
-              required:
-                - location
-                - language
-          additionalProperties: false
-
-        measurement_files:
-          type: array
-          description: List of PEtab measurement files.
-
-          items:
+  model_files:
+    type: object
+    description: One or multiple models
+
+    # the model ID
+    patternProperties:
+      "^[a-zA-Z_]\\w*$":
+        type: object
+        properties:
+          location:
             type: string
-            description: PEtab measurement file name or URL.
+            description: Model file name or URL
+          language:
+            type: string
+            description: |
+              Model language, e.g., 'sbml', 'cellml', 'bngl', 'pysb'
+        required:
+          - location
+          - language
+    additionalProperties: false
 
-        condition_files:
-          type: array
-          description: List of PEtab condition files.
+  measurement_files:
+    type: array
+    description: List of PEtab measurement files.
 
-          items:
-            type: string
-            description: PEtab condition file name or URL.
+    items:
+      type: string
+      description: PEtab measurement file name or URL.
+
+  condition_files:
+    type: array
+    description: List of PEtab condition files.
 
-        experiment_files:
-          type: array
-          description: List of PEtab experiment files
+    items:
+      type: string
+      description: PEtab condition file name or URL.
 
-          items:
-            type: string
-            description: PEtab experiment file name or URL.
+  experiment_files:
+    type: array
+    description: List of PEtab experiment files
 
-        observable_files:
-          type: array
-          description: List of PEtab observable files.
+    items:
+      type: string
+      description: PEtab experiment file name or URL.
 
-          items:
-            type: string
-            description: PEtab observable file name or URL.
+  observable_files:
+    type: array
+    description: List of PEtab observable files.
+
+    items:
+      type: string
+      description: PEtab observable file name or URL.
 
-        visualization_files:
-          type: array
-          description: List of PEtab visualization files.
+  visualization_files:
+    type: array
+    description: List of PEtab visualization files.
 
-          items:
-            type: string
-            description: PEtab visualization file name or URL.
+    items:
+      type: string
+      description: PEtab visualization file name or URL.
 
-        mapping_files:
-          type: array
-          description: List of PEtab mapping files.
+  mapping_files:
+    type: array
+    description: List of PEtab mapping files.
 
-          items:
-            type: string
-            description: PEtab mapping file name or URL.
+    items:
+      type: string
+      description: PEtab mapping file name or URL.
 
       required:
-        - model_files
-        - observable_files
-        - measurement_files
 
   extensions:
     type: object
@@ -142,4 +123,7 @@ properties:
 required:
   - format_version
   - parameter_file
-  - problems
+  - model_files
+  - observable_files
+  - measurement_files
+

doc/v2/documentation_data_format.rst

@@ -53,7 +53,7 @@ text-based files in `Tab-Separated Values (TSV)
 <https://www.iana.org/assignments/media-types/text/tab-separated-values>`_
 format (Figure 2), including:
 
-- A :ref:`model <v2_model>` file specifying the base model
+- One or multiple (optional) :ref:`model <v2_model>` file(s) specifying the base model(s)
   [SBML, CELLML, BNGL, PYSB, ...].
 
 - A :ref:`measurement file <v2_measurements_table>` containing experimental
@@ -194,10 +194,10 @@ PEtab distinguishes between three types of entities:
 Conditions table
 ----------------
 
-The optional conditions table defines discrete changes to the 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*.
+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*.
 
 Conditions are applied at specific time points, which are defined in the
 :ref:`v2_experiments_table`. This allows for the specification of time
@@ -304,6 +304,9 @@ phases, following the logic of the event assignments in a single SBML event.
      For further details, refer to SBML semantic test suite case `01779
      <https://github.com/sbmlteam/sbml-test-suite/blob/7ab011efe471877987b5d6dcba8cc19a6ff71254/cases/semantic/01779/01779-model.m>`_.
 
+   * For problems involving multiple models, any assignment to targets not
+     present in the currently simulated model will be ignored.
+
 3. **Update of derived variables**
 
    After target values have been assigned, all derived variables (i.e.,
@@ -456,13 +459,17 @@ order:
 Additional (non-standard) columns may be added. If the additional plotting
 functionality of PEtab should be used, such columns could be
 
-+-----+-------------+---------------+
-| ... | [datasetId] | [replicateId] |
-+=====+=============+===============+
-| ... | [datasetId] | [replicateId] |
-+-----+-------------+---------------+
-| ... | ...         | ...           |
-+-----+-------------+---------------+
++-----+-------------+---------------+-----------+
+| ... | [datasetId] | [replicateId] | [modelId] |
++=====+=============+===============+===========+
+| ... | [datasetId] | [replicateId] | [modelId] |
++-----+-------------+---------------+-----------+
+| ... |             |               |           |
++-----+-------------+---------------+-----------+
+| ... |             |               |           |
++-----+-------------+---------------+-----------+
+| ... | ...         | ...           |           |
++-----+-------------+---------------+-----------+
 
 where ``datasetId`` is a necessary column to use particular plotting
 functionality, and ``replicateId`` is optional, which can be used to group
@@ -548,6 +555,14 @@ Detailed field description
   The replicateId can be used to discern replicates with the same
   ``datasetId``, which is helpful for plotting e.g. error bars.
 
+- ``modelId`` [PETAB_ID, OPTIONAL, REFERENCES(yaml.models.model_id)]
+
+  The modelId specifies which model to simulate for each data point. modelIds
+  are defined by the keys of the models dict in the PEtab problem YAML file.
+  This column is required when multiple models are defined in the PEtab problem. 
+  For problems with a single model, this column is ignored, and the same model
+  is used for all simulations.
+
 .. _v2_observables_table:
 
 Observables table
@@ -608,9 +623,9 @@ Detailed field description
 * ``observableFormula`` [STRING]
 
   Observation function as plain text formula expression.
-  May contain any symbol defined in the SBML model (including model time ``time``)
-  or parameter table. In the simplest case just an SBML species ID
-  or an ``AssignmentRule`` target. Additionally, any observable ID
+  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.
 
@@ -732,7 +747,7 @@ and *must not* include:
 - "Parameters" that are not *constant* entities (e.g., in an SBML model,
   the targets of *AssignmentRules* or *EventAssignments*)
 - Any parameters that do not have valid PEtab IDs
-  (e.g., SBML *local* parameters)
+  (e.g., SBML *local* parameters that are not mapped in the mapping table)
 
 it *may* include:
 
@@ -771,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 in the SBML 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).
@@ -1088,8 +1103,8 @@ Detailed field description
 
 - ``modelEntityId`` [STRING or empty, REQUIRED]
 
-  A globally unique identifier defined in the model, or empty if the entity is
-  not present in the model. This does not have to be a valid PEtab identifier.
+  A globally unique identifier defined in any model, or empty if the entity is
+  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
@@ -1131,11 +1146,50 @@ easy validation:
 Parameter estimation problems combining multiple models
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-Parameter estimation problems can comprise multiple models. For now, PEtab
-allows one to specify multiple models with corresponding condition and
-measurement tables, and one joint parameter table. This means that the parameter
-namespace is global. Therefore, parameters with the same ID in different models
-will be considered identical.
+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: