diff --git a/doc/v2/_static/petab_schema_v2.yaml b/doc/v2/_static/petab_schema_v2.yaml index 9cc0f7aa..b09421b2 100644 --- a/doc/v2/_static/petab_schema_v2.yaml +++ b/doc/v2/_static/petab_schema_v2.yaml @@ -34,8 +34,9 @@ properties: type: object description: | - A set of PEtab model, condition, observable and measurement - files and optional visualization files. + A set of PEtab model, observable and measurement + files and optional condition, experiment, and visualization files. + properties: model_files: @@ -75,6 +76,14 @@ properties: type: string description: PEtab condition file name or URL. + experiment_files: + type: array + description: List of PEtab experiment files + + items: + type: string + description: PEtab experiment file name or URL. + observable_files: type: array description: List of PEtab observable files. @@ -103,7 +112,6 @@ properties: - model_files - observable_files - measurement_files - - condition_files extensions: type: object diff --git a/doc/v2/documentation_data_format.rst b/doc/v2/documentation_data_format.rst index 3ed4df4d..8922f5b9 100644 --- a/doc/v2/documentation_data_format.rst +++ b/doc/v2/documentation_data_format.rst @@ -5,7 +5,6 @@ PEtab data format specification =============================== - Format version: 2.0.0 This document explains the PEtab data format. @@ -35,7 +34,7 @@ least redundant way. Furthermore, we wanted to establish an intuitive, modular, machine- and human-readable and -writable format that makes use of existing standards. -.. figure:: ../v1/gfx/petab_scope_and_files.png +.. figure:: gfx/petab_scope_and_files.png :alt: A common setup for data-based modeling studies and its representation in PEtab. :scale: 80% @@ -47,15 +46,18 @@ Overview The PEtab data format specifies a parameter estimation problem using a number of text-based files ( `Tab-Separated Values (TSV) `_) -(Figure 2), i.e. +(Figure 2), i.e.: - A model - A measurement file to fit the model to [TSV] -- A condition file specifying model inputs and condition-specific parameters +- (optional) A condition file specifying model inputs and condition-specific parameters [TSV] +- (optional) An experiments file, which describes a sequence of different + experimental conditions that are applied to the model [TSV] + - An observable file specifying the observation model [TSV] - A parameter file specifying estimateable parameters and related information @@ -73,7 +75,8 @@ of text-based files ( - (optional) A mapping file, which allows mapping PEtab entity IDs to entity IDs in the model, which might not have valid PEtab IDs themselves [TSV] -.. figure:: ../v1/gfx/petab_files.png + +.. figure:: gfx/petab_files.png :alt: Files constituting a PEtab problem **Figure 2: Files constituting a PEtab problem.** @@ -95,6 +98,18 @@ problem as such. - All model entities, column names and row names are case-sensitive - Fields in "[]" are optional and may be left empty. +- The following data types are used in descriptions below: + + - ``STRING``: Any string + - ``NUMERIC``: Any number excluding ``NaN`` / ``inf`` / ``-inf`` + - ``MATH_EXPRESSION``: A mathematical expression according to the + `PEtab math expression syntax `_. + - ``PETAB_ID``: A string that is a valid PEtab ID + - ``NON_ESTIMATED_ENTITY_ID``: A string that is a valid PEtab ID and refers + directly, or via the mapping table, to an entity that has some associated + numeric value (e.g. a model parameter, parameter table parameter, + or a species in the model) and is not listed in the + :ref:`parameters_table` (including ``estimate=0`` parameters). Changes from PEtab 1.0.0 @@ -102,11 +117,20 @@ Changes from PEtab 1.0.0 PEtab 2.0.0 is a major update of the PEtab format. The main changes are: -* Support for non-SBML models +* Support for non-SBML models (:ref:`model`) +* Changed condition table format (wide -> long) (:ref:`conditions_table`) +* ``simulationConditionId`` and ``preequilibrationConditionId`` in the + :ref:`measurements_table` are replaced by ``experimentId`` and a more + flexible way for defining experiments / time courses + (:ref:`experiments_table`) +* Support for math expressions in the condition table (:ref:`conditions_table`) * Clarification and specification of various previously underspecified aspects - (math expressions, overriding values in the condition table, etc.) + (:ref:`math_expressions`, overriding values in the condition table, etc.) * Support for extensions * Observable IDs are now allowed to be used in observable/noise formulas + (:ref:`observables_table`) + +.. _model: Model definition ---------------- @@ -114,88 +138,171 @@ Model definition PEtab 2.0.0 is agnostic of specific model formats. A model file is referenced in the PEtab problem description (YAML) via its file name or a URL. -Condition table ---------------- +.. _conditions_table: -The condition table specifies parameters, or initial values of species and -compartments for specific simulation conditions (generally corresponding to -different experimental conditions). +Conditions table +---------------- -This is specified as a tab-separated value file in the following way: +The conditions table specifies changes to parameters, initial or intermediate values of +species, and compartments, during specific time periods. The start and end of the time +period is defined in the :ref:`experiments_table`, where multiple conditions can be +combined to specify time courses or experiments that span multiple time periods. Any +changes applied to the model will remain in effect until they are changed by a condition +applied at a later time period. -+--------------+------------------+------------------------------------+-----+---------------------------------------+ -| conditionId | [conditionName] | modelEntityId1 | ... | modelEntityId${n} | -+==============+==================+====================================+=====+=======================================+ -| STRING | [STRING] | NUMERIC\|STRING | ... | NUMERIC\|STRING | -+--------------+------------------+------------------------------------+-----+---------------------------------------+ -| e.g. | | | | | -+--------------+------------------+------------------------------------+-----+---------------------------------------+ -| conditionId1 | [conditionName1] | 0.42 | ... | parameterId | -+--------------+------------------+------------------------------------+-----+---------------------------------------+ -| conditionId2 | ... | ... | ... | ... | -+--------------+------------------+------------------------------------+-----+---------------------------------------+ -| ... | ... | ... | ... | .. | -+--------------+------------------+------------------------------------+-----+---------------------------------------+ +This is specified as a tab-separated value file in the following way: + +**TODO: keep conditionName or not?** + ++--------------+------------------+-------------------------+-----------------+--------------------+ +| conditionId | [conditionName] | targetId | operationType | targetValue | ++==============+==================+=========================+=================+====================+ +| PETAB_ID | [STRING] | NON_ESTIMATED_ENTITY_ID | STRING | MATH_EXPRESSION | ++--------------+------------------+-------------------------+-----------------+--------------------+ +| e.g. | | | | | ++--------------+------------------+-------------------------+-----------------+--------------------+ +| conditionId1 | conditionName1 | modelEntityId1 | setCurrentValue | 0.42 | ++--------------+------------------+-------------------------+-----------------+--------------------+ +| conditionId1 | conditionName1 | modelEntityId2 | setCurrentValue | 0.42 | ++--------------+------------------+-------------------------+-----------------+--------------------+ +| conditionId2 | ... | modelEntityId1 | setCurrentValue | modelEntityId1 + 3 | ++--------------+------------------+-------------------------+-----------------+--------------------+ +| conditionId2 | ... | someSpecies | setCurrentValue | 8 | ++--------------+------------------+-------------------------+-----------------+--------------------+ +| ... | ... | ... | ... | ... | ++--------------+------------------+-------------------------+-----------------+--------------------+ + +Each line specifies one change in one target entity. Row- and column-ordering are arbitrary, although specifying ``conditionId`` first may improve human readability. -Additional columns are *not* allowed. - Detailed field description ~~~~~~~~~~~~~~~~~~~~~~~~~~ -- ``conditionId`` [STRING, NOT NULL] +- ``conditionId`` [PETAB_ID, REQUIRED] Unique identifier for the simulation/experimental condition, to be referenced - by the measurement table described below. Must consist only of upper and - lower case letters, digits and underscores, and must not start with a digit. + by the :ref:`experiments_table`. -- ``conditionName`` [STRING, OPTIONAL] +- ``conditionName`` [STRING, OPTIONAL] **TODO: remove** Condition names are arbitrary strings to describe the given condition. They may be used for reporting or visualization. -- ``${modelEntityId}`` - - Further columns may be the IDs of model entities that have globally unique - IDs, such as parameters, species or compartments defined in the model to set - condition-specific values. Only one column is allowed per ID. - Values for these entities may be provided either as numeric values, or as IDs - of globally unique entity IDs as defined in the model, the mapping table or - the parameter table. - - Any non-``NaN`` value will override the original values of the model, or if - preequilibration was used, they will override the value obtained from - preequilibration. A ``NaN`` value indicates that the original value of the - model is to be used (when used in the preequilibration condition, or in the - simulation condition if no preequilibration is used) or that the result of - preequilibration is to be used (when used in the simulation condition after - preequilibration). - - The value in the condition table either replaces the initial value or the - value at all timepoints based on whether the model entity has a rate law - assigned or not: - - * For model entities that have constant algebraic assignments - (but not necessarily constant values), i.e, that do not have a rate of - change with respect to time assigned and that are not subject to event - assignments, the algebraic assignment is replaced statically at all - timepoints. Examples for such model entities are the targets of SBML - `AssignmentRules`. - - * For all other entities, e.g., those that are assigned by SBML `RateRules`, - only the initial value can be assigned in the condition table. If an - assignment of the rate of change with respect to time or event assignment - is desired, the values of model entities that are used to define rate of - change or event assignments must be assigned in the condition table. - If no such model entities exist, assignment is not possible. +- ``targetId`` [NON_ESTIMATED_ENTITY_ID, required except for ``operationType=noChange``] + + The ID of the non-estimated entity that will change. + Different restrictions apply depending on the ``operationType`` and the + type of the model. + + We distinguish between three types of entities: + + * **Differential Targets**: Entities that are defined in terms of a + time-derivative, e.g., the targets of SBML rate rules or species that + change by participating in reactions (educts or products). + + * **Algebraic targets**: Entities that are defined in terms of an algebraic + assignment, i.e., they are not subject to time-derivative information, but + are not generally constant, e.g., the targets of SBML assignment rules. + + * **Constant targets**: Entities are that are defined in terms of a constant + value but may be subject to event assignments, e.g., parameters of an SBML + model that are not targets of rate rules or assignment rules. +- ``operationType`` [STRING, REQUIRED] + + How the target value is to be interpreted. Allowed values are: + + - ``setCurrentValue``: The current value of the target is initialized to the + value of ``targetValue`` when the respective condition is applied. + Any symbols in ``targetValue`` are interpreted as their value at the time + just before this change is applied (similar + to an SBML event with ``useValuesFromTriggerTime=True``; in case of the + first period of a timecourse, they will be interpreted as their initial + values as defined in the model). + The target must be a constant target or a differential target. + + - ``setRate``: The time-derivative of the target is set to ``targetValue`` + (symbolically; the expression is not evaluated at the time the condition is + applied). + The target must be a differential target. + + - ``addToRate``: The target's rate is increased by ``targetValue`` + (symbolically). + The target must be a differential target. + + - ``setAssignment``: The target is set to the value of ``targetValue`` + (symbolically). + The target must be an algebraic target. + + - ``addToAssignment``: The expression assigned to the target is increased by + ``targetValue`` (symbolically). + The target must be an algebraic target. + + - ``noChange``: This value is used to indicate that no change is associated + with this condition. This is useful in cases where an explicit condition + ID is required, but no change is to be applied. (E.g., if pre-equilibration + is to be performed using the default values of the model, followed by a + different condition.) + ``targetId`` and ``targetValue`` have to be empty in this case. + For any ``conditionId`` with ``operationType=noChange``, there must not be + any other row with the same ``conditionId`` in the conditions table. + +- ``targetValue`` [MATH_EXPRESSION, REQUIRED] + + The value or expression that will be used to change the target. The + interpretation of the value depends on the ``operationType`` as described + above. If the model has a concept of species and a species ID is provided, its value is interpreted as amount or concentration in the same way as anywhere else in the model. +**TODO**: clarify order of evaluation + +**Examples:** **TODO** + + - given a timecourse ``0:condition1;10:condition2`` and two constant + model parameters ``par1``, ``par2`` and the two conditions: + + - ``condition1``: {``par1=0.1``, ``par2=0.2``} + - ``condition2``: {``par1=par2``, ``par2=par1``} + + This is okay, since no circular dependencies exist: ``par1 = 0.2``, ``par2=0.1`` + + - given a ``timecourse 0:condition1`` and two model parameters + ``par1``, ``par2`` with only a single condition: + + - ``condition1``: {``par1=par2``, ``par2=par1``} + + This is not allowed, in the first condition of the timecourse ``par1``, ``par2`` + cannot be used in the right-hand side of the assignment + + - Given a condition: ``condition1``: {``par1=par3``, ``par2=2*par3``} + + This is allowed. + + Condition changes should be implemented to respect the dependency + graph between model components: + + - When a condition changes quantity ``A`` and ``B``, and ``B`` is dependent on + ``A``, the change in quantity A should be applied first such that the + new value for ``B`` is consistent with what is specified in the + condition. + + - For example, concentrations are generally dependent on volume + i.e. when a model compartment volume changes, the concentrations + of all species in that compartment change too, because mass is + usually conserved. In this case, if a condition change involves a + change in both a compartment volume and a species concentration, + then the compartment change should be applied first. Otherwise, + the species concentration after the condition is applied, will not + match the concentration specified by the user, because it would be + modified by the volume change. + +.. _measurements_table: + Measurement table ----------------- @@ -205,13 +312,13 @@ model training or validation. Expected to have the following named columns in any (but preferably this) order: -+--------------+-------------------------------+-----------------------+-------------+--------------+ -| observableId | [preequilibrationConditionId] | simulationConditionId | measurement | time | -+==============+===============================+=======================+=============+==============+ -| observableId | [conditionId] | conditionId | NUMERIC | NUMERIC\|inf | -+--------------+-------------------------------+-----------------------+-------------+--------------+ -| ... | ... | ... | ... | ... | -+--------------+-------------------------------+-----------------------+-------------+--------------+ ++--------------+--------------+-------------+--------------+ +| observableId | experimentId | measurement | time | ++==============+==============+=============+==============+ +| PETAB_ID | PETAB_ID | NUMERIC | NUMERIC\|inf | ++--------------+--------------+-------------+--------------+ +| ... | ... | ... | ... | ++--------------+--------------+-------------+--------------+ *(wrapped for readability)* @@ -242,27 +349,26 @@ replicates and plot error bars. Detailed field description ~~~~~~~~~~~~~~~~~~~~~~~~~~ -- ``observableId`` [STRING, NOT NULL, REFERENCES(observables.observableID)] +- ``observableId`` [PETAB_ID, REQUIRED, REFERENCES(observables.observableID)] Observable ID as defined in the observable table described below. -- ``preequilibrationConditionId`` [STRING OR NULL, REFERENCES(conditionsTable.conditionID), OPTIONAL] - - The ``conditionId`` to be used for preequilibration. E.g. for drug - treatments, the model would be preequilibrated with the no-drug condition. - Empty for no preequilibration. +- ``experimentId`` [[PETAB_ID], REQUIRED, REFERENCES(experimentsTable.experimentID)] -- ``simulationConditionId`` [STRING, NOT NULL, REFERENCES(conditionsTable.conditionID)] + Experiment ID as defined in the experiments table described below. This + column may have empty cells, which are interpreted as *use the model as is*. + This avoids the need for "dummy" conditions and experiments if only a single + condition is required. - ``conditionId`` as provided in the condition table, specifying the condition-specific parameters used for simulation. - -- ``measurement`` [NUMERIC, NOT NULL] +- ``measurement`` [NUMERIC, REQUIRED] The measured value in the same units/scale as the model output. -- ``time`` [NUMERIC OR STRING, NOT NULL] +- ``time`` [NUMERIC OR STRING, REQUIRED] - Time point of the measurement in the time unit specified in the SBML model, numeric value or ``inf`` (lower-case) for steady-state measurements. + Time point of the measurement in the time unit specified in the SBML model, + a finite numeric value, or ``inf`` (lower-case) for steady-state + measurements. - ``observableParameters`` [NUMERIC, STRING OR NULL, OPTIONAL] @@ -309,8 +415,93 @@ Detailed field description ``datasetId``, which is helpful for plotting e.g. error bars. -Observable table ----------------- +.. _experiments_table: + +Experiments table +----------------- + +The optional experiments table describes a sequence of different experimental +conditions (here: discrete changes) that are applied to the model. + +This is specified as a tab-separated value file in the following way: + ++---------------------+-------------------+-----------------+ +| experimentId | time | conditionId | ++=====================+===================+=================+ +| PETAB_ID | NUMERIC or '-inf' | CONDITION_ID | ++---------------------+-------------------+-----------------+ +| timecourse_1 | 0 | condition_1 | ++---------------------+-------------------+-----------------+ +| timecourse_1 | 10 | condition_2 | ++---------------------+-------------------+-----------------+ +| timecourse_1 | 250 | condition_3 | ++---------------------+-------------------+-----------------+ +| patient_3 | -inf | condition_1 | ++---------------------+-------------------+-----------------+ +| patient_3 | 0 | condition_2 | ++---------------------+-------------------+-----------------+ +| intervention_effect | -20 | no_lockdown | ++---------------------+-------------------+-----------------+ +| intervention_effect | 20 | mild_lockdown | ++---------------------+-------------------+-----------------+ +| intervention_effect | 40 | severe_lockdown | ++---------------------+-------------------+-----------------+ + +Detailed field description +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The time courses table with three mandatory columns ``experimentId``, +``time``, and ``conditionId``: + +- ``experimentId`` [PETAB_ID, REQUIRED] + + Identifier of the experiment. + This is referenced by the ``experimentId`` column in the measurement table. + +- ``time``: [NUMERIC or ``-inf``, REQUIRED] + + The time when the condition will become active, in the time unit specified + in the model. ``-inf`` indicates that the respective condition will be + simulated until a steady state is reached. + + If the simulation of a condition with steady fails to reach a steady state, + and the condition is required for the evaluation of simulation at measurement + points, the evaluation of the model is not well-defined. + In such cases, PEtab interpreters should notify the user, for example, by + returning ``NaN`` or ``inf`` values for the objective function. + PEtab does not specify a numerical criterion for steady states. + +- ``CONDITION_ID``: [PETAB_ID, REQUIRED, REFERENCES(conditions.conditionID)] + + Reference to a condition ID in the condition table that + is to be applied at the given `time`. + + Note: The time interval in which a condition is applied includes the + respective starting timepoint, but excludes the starting timepoint of + the following condition. This means that for an experiment where + ``condition_A`` is applied at ``time_A`` and later ``condition_B`` is + applied at ``time_B``, then ``condition_A`` is active + during the interval ``[time_A, time_B)``. This implies that any event + assignment that triggers at ``time_B`` will occur *after* ``condition_B`` was + applied and for any measurements at ``time_B``, the observables will be + evaluated *after* ``condition_B`` was applied. + +Multiple conditions can be applied at the same time point by specifying +multiple lines with the same ``experimentId`` and ``time`` but different +``conditionId``. The order of the conditions is arbitrary. + +All changes across all simultaneous conditions are applied in order of +dependencies, with conservation of mass when volumes change, i.e. +a volume change implies a concentration change, but not vice versa. + +Hence, volume changes are applied before concentration changes in the +same compartment, and changes to parameters are applied before +changes to species that depend on the parameters. + +.. _observables_table: + +Observables table +----------------- Parameter estimation requires linking experimental observations to the model of interest. Therefore, one needs to define observables (model outputs) and @@ -319,7 +510,7 @@ Since parameter estimation is beyond the scope of SBML, there exists no standard way to specify observables (model outputs) and respective noise models. Therefore, in PEtab observables are specified in a separate table as described in the following. This allows for a clear separation of the -observation model and the underlying dynamic model, which allows, in most +observation model and the underlying dynamic model, which allows, in most cases, to reuse any existing SBML model without modifications. The observable table has the following columns: @@ -468,6 +659,7 @@ The distributions above are for a single data point. For a collection :math:`D=\ .. math:: \pi(D|Y,\Sigma) = \prod_i\pi(m_i|y_i,\sigma_i) +.. _parameters_table: Parameter table --------------- @@ -519,7 +711,7 @@ Additional columns may be added. Detailed field description ~~~~~~~~~~~~~~~~~~~~~~~~~~ -- ``parameterId`` [STRING, NOT NULL] +- ``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 @@ -621,6 +813,7 @@ Detailed field description Prior parameters used for the objective function during estimation. For more detailed documentation, see ``initializationPriorParameters``. +.. _visualization_table: Visualization table ------------------- @@ -665,7 +858,7 @@ order: Detailed field description ~~~~~~~~~~~~~~~~~~~~~~~~~~ -- ``plotId`` [STRING, NOT NULL] +- ``plotId`` [STRING, REQUIRED] An ID which corresponds to a specific plot. All datasets with the same plotId will be plotted into the same axes object. @@ -685,7 +878,7 @@ Detailed field description ``provided`` (if numeric values for the noise level are provided in the measurement table). Default is ``MeanAndSD``. -- ``datasetId`` [STRING, NOT NULL, REFERENCES(measurementTable.datasetId), OPTIONAL] +- ``datasetId`` [STRING, REQUIRED, REFERENCES(measurementTable.datasetId), OPTIONAL] The datasets which should be grouped into one plot. @@ -733,6 +926,7 @@ Detailed field description The name that should be displayed for the corresponding dataset in the legend and which defaults to the value in ``datasetId``. +.. _mapping_table: Mapping table ------------- @@ -757,14 +951,14 @@ The TSV file has two mandatory columns, ``petabEntityId`` and Detailed field description ~~~~~~~~~~~~~~~~~~~~~~~~~~ -- ``petabEntityId`` [STRING, NOT NULL] +- ``petabEntityId`` [PETAB_ID, REQUIRED] A valid PEtab identifier that is not defined in any other part of the PEtab problem. This identifier may be referenced in condition, measurement, parameter and observable tables, but cannot be referenced in the model itself. -- ``modelEntityId`` [STRING, NOT NULL] +- ``modelEntityId`` [STRING, REQUIRED] A globally unique identifier defined in the model, *that is not a valid PEtab ID* (see :ref:`identifiers`). @@ -793,6 +987,7 @@ Examples of the visualization table can be found in the `Benchmark model collection `_, for example in the `Chen_MSB2009 `_ model. +.. _problem_yaml: YAML file for grouping files ---------------------------- @@ -823,6 +1018,8 @@ namespace is global. Therefore, parameters with the same ID in different models will be considered identical. +.. _math_expressions: + Math expressions syntax ----------------------- diff --git a/doc/v2/gfx/petab_files.png b/doc/v2/gfx/petab_files.png new file mode 100644 index 00000000..971fd729 Binary files /dev/null and b/doc/v2/gfx/petab_files.png differ diff --git a/doc/v2/gfx/petab_files.svg b/doc/v2/gfx/petab_files.svg new file mode 100644 index 00000000..9ede262e --- /dev/null +++ b/doc/v2/gfx/petab_files.svg @@ -0,0 +1,3489 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + YAML + + + + + + + Problem + • Grouping model +• and other tables +• Combination of +• multiple files + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + • Reaction• network + Model + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + • Parameter• transformations• Bounds• Prior information + • Data visualization• Model fit + • Condition-specific• parameters + • Measured values• Preequilibration• Noise• Output parameters + Parameters + ExperimentalConditions + Measurements + Visualization + • Observation functions• Noise model + Observables + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + • Sequences of experimental conditionl + Experiments + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/doc/v2/gfx/petab_scope_and_files.pdf b/doc/v2/gfx/petab_scope_and_files.pdf new file mode 100644 index 00000000..e0ca20f4 Binary files /dev/null and b/doc/v2/gfx/petab_scope_and_files.pdf differ diff --git a/doc/v2/gfx/petab_scope_and_files.png b/doc/v2/gfx/petab_scope_and_files.png new file mode 100644 index 00000000..4bad5733 Binary files /dev/null and b/doc/v2/gfx/petab_scope_and_files.png differ diff --git a/doc/v2/gfx/petab_scope_and_files.svg b/doc/v2/gfx/petab_scope_and_files.svg new file mode 100644 index 00000000..de0945dd --- /dev/null +++ b/doc/v2/gfx/petab_scope_and_files.svg @@ -0,0 +1,1652 @@ + + + + + + + + + + + + + + + + + + + image/svg+xml + + + + + + + + + + + + + TODO][] + + + + + Measurements + + + + + + + + + + + + + + + + + Experiments + + + + + + + + + + + + + + + + + + + + + + + + + + + + + ... + Condition 1 + Condition 2 + ... + + + + Simulate + Likelihood, Residuals, ... + Parameter estimation / Uncertainty analysisOptimize, Profile, Sample, ... + + + + + Visualize, Analyze, Predict, ... + + Generic model of biological system + Condition-specific model of biological system + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Generic observation model + Condition-specific observation model + + Generic noise model + + + y1 = sa ⋅ x1 y2 = ca + x2...y1 = sb ⋅ x1 y2 = cb + x2... + + + + y1 = s ⋅ x1 y2 = c + x2... + + + + + + + + + + + + + + + + Condition table + + + + + conditionId p1 p2 ...Condition1 1.0 1.0 Condition2 5.0 4.0 ... + + + + + Observable table + + + + + observableId observableFormula noiseDistribution noiseParametersObservable1 s · x1 normal 1.0Observable2 c + x2 laplace 3.0... + + + + + Model + + + + + Measurement table + + + + observableId timecourseId time measurementObservable1 Timecourse1 1.0 2.0Observable2 Timecourse2 1.0 3.0... + + + + Parameter table + + + + + + parameterId estimate nominalValueParameter1 1 Parameter2 0 3.0... + + + + + Timecourses table + + + + timecourseId timecourseTimecourse1 0:Condition1 Timecourse2 0:Condition2 ... + + + + + A + Typical experimental and model setup and workflow + + + B + Representation of the workflow elements in PEtab + + + + + σ1 = 0.1 ⋅ x1σ2 = 0.5...σ1 = 1.0σ2 = 2.0... + + Condition-specific noise model + + + + + + + + + + + + + + + + + + + +