From f08da31bfbd0e51ab80957d1ca6279ea9460b5dc Mon Sep 17 00:00:00 2001 From: Daniel Weindl Date: Thu, 5 Dec 2024 14:33:31 +0100 Subject: [PATCH] Update experiment table --- doc/v2/documentation_data_format.rst | 128 ++++++++++++--------------- 1 file changed, 59 insertions(+), 69 deletions(-) diff --git a/doc/v2/documentation_data_format.rst b/doc/v2/documentation_data_format.rst index 618f7588..dd2a130e 100644 --- a/doc/v2/documentation_data_format.rst +++ b/doc/v2/documentation_data_format.rst @@ -47,7 +47,7 @@ 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 @@ -56,7 +56,7 @@ of text-based files ( - (optional) A condition file specifying model inputs and condition-specific parameters [TSV] -- (optional) A timecourses file, which describes a sequence of different +- (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] @@ -309,7 +309,8 @@ Detailed field description Experiment ID as defined in the experiments table described below. This column may have ``NA`` values, which are interpreted as *use the model as is*. - This avoids the need for "dummy" conditions and experiments. + This avoids the need for "dummy" conditions and experiments if only a single + condition is required. - ``measurement`` [NUMERIC, NOT NULL] @@ -364,6 +365,61 @@ Detailed field description ``datasetId``, which is helpful for plotting e.g. error bars. +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`` [STRING, NOT NULL] + + Identifier of the experiment. The usual PEtab identifier requirements apply. + This is referenced by the ``experimentId`` column in the measurement table. + +- ``time``: [NUMERIC or ``-inf``, NOT NULL] + + The time when the condition will become active, in the time unit specified + in the model. ``-inf`` indicates pre-equilibration (e.g., for drug + treatments, the model would be pre-equilibrated with the no-drug condition). + +- ``CONDITION_ID``: 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 + ``[time_A:condition_A; time_B:condition_B]``, ``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. + + Observable table ---------------- @@ -878,72 +934,6 @@ namespace is global. Therefore, parameters with the same ID in different models will be considered identical. -Timecourses table ------------------ - -The optional time courses 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: - -+--------------------+-------------------------------------------------+ -| timecourseId | timecourse | -+====================+=================================================+ -| STRING | STRING | -+--------------------+-------------------------------------------------+ -| timecourse_1 | 0:condition_1;10:condition_2;250:condition_3 | -+--------------------+-------------------------------------------------+ -| patient_3 | -inf:condition_1;0:condition_2 | -+--------------------+-------------------------------------------------+ -| i | -20: | -| ntervention_effect | no_lockdown;20:mild_lockdown;40:severe_lockdown | -+--------------------+-------------------------------------------------+ - -Detailed field description -~~~~~~~~~~~~~~~~~~~~~~~~~~ - -The time courses table with two mandatory columns ``timecourseId`` and -``timecourse``: - -- ``timecourseId`` [STRING, NOT NULL] - - Identifier of the timecourse. The usual PEtab identifier requirements apply. - -- ``timecourse``: [STRING, NOT NULL] - - A semicolon-separated list of different phases of the experiment along with - their starting time. A value in the ``timecourse`` column takes the format - ``[TIMEPOINT:CONDITION_ID;...]``. - - ``TIMEPOINT`` can be: - - - ``-inf``: Marking the following condition as pre-equilibration - condition. (Despite ``-inf``, the pre-equilibration-starts at ``t=0`` and - simulation time is reset to ``TIMEPOINT`` of the following condition - afterwards). - - - ``float``: The timepoint at which to switch to the following - condition. The start time of the first non-preequilibration - condition is ``t_0``. If ``t_0`` is non-zero, then simulators are expected - to simulate from this non-zero time, not zero. - - - ``float0:float1``: indicates repetition of a period from ``time=float0``, - every ``float1`` time units, until the next period - -``CONDITION_ID``: - - References condition IDs from the conditions table that specify which - changes to apply at ``TIMEPOINT`` - - 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 a timecourse - ``[time_A:condition_A; time_B:condition_B]``, ``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. - Math expressions syntax -----------------------