Skip to content

v2: Clarification MultiModel format #622

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 8 commits into
base: main
Choose a base branch
from
Open

v2: Clarification MultiModel format #622

Show file tree
Hide file tree
Changes from 1 commit
Commits
Show all changes
8 commits
Select commit Hold shift + click to select a range
08e6bdd
update spec
FFroehlich Apr 22, 2025
975d5ae
Apply suggestions from code review
FFroehlich Apr 23, 2025
6216a5b
Merge branch 'main' into v2_multimodel
FFroehlich Apr 23, 2025
73d6b28
update invalid conditions/observables
FFroehlich May 22, 2025
0c23354
update multi-model description
FFroehlich May 22, 2025
a2fc132
Merge branch 'main' into v2_multimodel
FFroehlich May 22, 2025
1a1a93f
Apply suggestions from code review
FFroehlich May 23, 2025
628b088
remove missing assignments
FFroehlich May 23, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
138 changes: 61 additions & 77 deletions doc/v2/_static/petab_schema_v2.yaml
View file
Open in desktop
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Looks good, but a lot of diff in the file which makes it difficult to see the actual change.

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

briefly, removed the problems list/array and moved all properties to the highest level.

Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -142,4 +123,7 @@ properties:
required:
- format_version
- parameter_file
- problems
- model_files
- observable_files
- measurement_files

74 changes: 49 additions & 25 deletions doc/v2/documentation_data_format.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -153,6 +153,7 @@ 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``.
*

.. _v2_model:
.. _v2_model_entities:
Expand Down Expand Up @@ -185,10 +186,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
Expand Down Expand Up @@ -278,6 +279,9 @@ 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
Expand All @@ -295,6 +299,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.,
Expand Down Expand Up @@ -444,13 +451,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
Expand Down Expand Up @@ -533,6 +544,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
Expand Down Expand Up @@ -593,12 +612,15 @@ 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 any of the employed models (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
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Should this not rather throw an error?
If I for example there is in the observable formula a specie not present in the model, it feels like an error has been made by the user.

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yes, I considered that alternative. This specification allows reuse of observables across models, the user can always introduce model specific observables. We could provide different options for linting that are more or less strict.

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).
Expand Down Expand Up @@ -719,7 +741,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:

Expand Down Expand Up @@ -758,7 +780,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 any 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).
Expand Down Expand Up @@ -990,8 +1012,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 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
Expand Down Expand Up @@ -1033,12 +1055,14 @@ 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.

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.

.. _v2_objective_function:

Expand Down