diff --git a/.github/ISSUE_TEMPLATE/petab-extensions.md b/.github/ISSUE_TEMPLATE/petab-extensions.md index ebe3a47b..cf7c7e59 100644 --- a/.github/ISSUE_TEMPLATE/petab-extensions.md +++ b/.github/ISSUE_TEMPLATE/petab-extensions.md @@ -9,7 +9,7 @@ assignees: '' --- **Name of the Extension** -Please make sure that the extension name matches the regular expression `^[a-zA-Z_][\w-]*$`. +Please make sure that the extension name matches the regular expression `^[a-zA-Z_][A-Za-z0-9_-]*$`. **Which problem would you like to address?** A clear and concise description of which use case you want to address and, if applicable, why the current specifications do not fulfill your requirements. @@ -21,7 +21,7 @@ A clear and concise description of the changes you want to propose. Please descr A clear and concise description in what way the proposed changes introduce features that are orthogonal to the PEtab core specification. **List the extension library that implements validation checks** -A link to the website or github repository that accompanies the proposed extension. +A link to the website or GitHub repository that accompanies the proposed extension. **List the toolboxes that support the proposed standard** -A link to the website or github repository that contains the software that implements support for the standard. +A link to the website or GitHub repository that contains the software that implements support for the standard. diff --git a/CHANGELOG.md b/CHANGELOG.md index cb7597d3..c2fe2359 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -19,7 +19,7 @@ available at https://github.com/PEtab-dev/libpetab-python/. ### 0.2.0 * Specify how PEtab functionality can be expanded through extensions. -* YAML files are now required for the specification of PEtab problems +* YAML files are now required for the specification of PEtab problems. ## 0.1 series diff --git a/README.md b/README.md index a282745d..7b5d81ae 100644 --- a/README.md +++ b/README.md @@ -23,7 +23,7 @@ for example: - Specifying multiple simulation conditions with potentially shared parameters -![PEtab files](doc/gfx/petab_files.png) +![PEtab files](doc/v1/gfx/petab_files.png) ## Documentation @@ -140,7 +140,7 @@ will have to: 1. Create a parameter table. -1. Create a yaml file that lists the model and all of the tables above. +1. Create a YAML file that lists the model and all of the tables above. If you are using Python, some handy functions of the [PEtab library](https://github.com/PEtab-dev/libpetab-python/) can help diff --git a/doc/_static/petab_schema.yaml b/doc/_static/petab_schema.yaml index 95316be0..9cc0f7aa 100644 --- a/doc/_static/petab_schema.yaml +++ b/doc/_static/petab_schema.yaml @@ -123,7 +123,7 @@ properties: type: bool description: | Indicates whether the extension is required for the - mathematical interpretation of problem. + mathematical interpretation of the problem. required: - version - required diff --git a/doc/development.rst b/doc/development.rst index d2b79cbb..9bdc34e5 100644 --- a/doc/development.rst +++ b/doc/development.rst @@ -211,14 +211,16 @@ Requirements for new extensions: can ease or refine format restrictions imposed by PEtab core. * PEtab extensions should extend PEtab core with new orthogonal features or tasks, i.e., they should not make trivial changes to PEtab core. -* PEtab extensions must be named according to ^[a-zA-Z][\w\-]*$ +* PEtab extensions must be named according to ``^[a-zA-Z][a-zA-Z0-9_\-]*$``. * PEtab extensions must be versioned using semantic versioning. -* PEtab extensions required for interpretation of a problem specification must - be specified in the PEtab-YAML files -* There is at least one tool that supports the proposed extension +* If a PEtab extension changes the mathematical interpretation of a problem, + it must appear in the PEtab YAML file. +* There is at least one tool that supports the proposed extension. * The authors provide a library that provides test cases and implements validation checks for the proposed format. +It is encouraged that (potential) extensions are informally discussed with the +community as early as possible. Developers are free to develop any PEtab extension. To become an official PEtab extension, it needs to go through the following process. diff --git a/doc/tutorial.rst b/doc/tutorial.rst index 983ac3a1..7e86abc4 100644 --- a/doc/tutorial.rst +++ b/doc/tutorial.rst @@ -33,7 +33,7 @@ illustration purposes we slightly modified the SBML model and shortened some parts of the PEtab files. The full PEtab problem introduced in this tutorial is available `online `_. -.. figure:: gfx/tutorial_model.png +.. figure:: tutorial/gfx/tutorial_model.png :width: 4.9846in :height: 5.5634in @@ -65,7 +65,7 @@ phosphorylation levels of STAT5A and STAT5B as well as relative STAT5A abundance for different timepoints between 0 - 240 minutes after stimulation with erythropoietin (Epo): -.. figure:: gfx/tutorial_data.png +.. figure:: tutorial/gfx/tutorial_data.png :width: 6.2681in :height: 2.0835in @@ -120,7 +120,7 @@ overridden by these condition-specific values. Here, we define the Epo concentration, but additional columns could be used to e.g. set different initial concentrations of STAT5A/B. In addition to numeric values, also parameter identifiers can be used here to introduce -condition specific estimateable parameters. +condition specific estimatable parameters. 2.2 Specifying the observation model ------------------------------------ @@ -384,7 +384,7 @@ PEtab. The easiest tool to get started with is probably COPASI which comes with a graphical user interface (see https://github.com/copasi/python-petab-importer for further instructions). -.. figure:: gfx/copasi_simulation.png +.. figure:: tutorial/gfx/copasi_simulation.png :width: 4.9846in :height: 5.5634in diff --git a/doc/gfx/copasi_simulation.png b/doc/tutorial/gfx/copasi_simulation.png similarity index 100% rename from doc/gfx/copasi_simulation.png rename to doc/tutorial/gfx/copasi_simulation.png diff --git a/doc/gfx/tutorial_data.png b/doc/tutorial/gfx/tutorial_data.png similarity index 100% rename from doc/gfx/tutorial_data.png rename to doc/tutorial/gfx/tutorial_data.png diff --git a/doc/gfx/tutorial_model.png b/doc/tutorial/gfx/tutorial_model.png similarity index 100% rename from doc/gfx/tutorial_model.png rename to doc/tutorial/gfx/tutorial_model.png diff --git a/doc/v1/documentation_data_format.rst b/doc/v1/documentation_data_format.rst index 3829c92c..c3af75f9 100644 --- a/doc/v1/documentation_data_format.rst +++ b/doc/v1/documentation_data_format.rst @@ -31,7 +31,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:: ../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% @@ -64,7 +64,7 @@ and - (optional) A visualization file, which contains specifications how the data and/or simulations should be plotted by the visualization routines [TSV] -.. figure:: ../gfx/petab_files.png +.. figure:: gfx/petab_files.png :alt: Files constituting a PEtab problem **Figure 2: Files constituting a PEtab problem.** diff --git a/doc/gfx/petab_files.pdf b/doc/v1/gfx/petab_files.pdf similarity index 100% rename from doc/gfx/petab_files.pdf rename to doc/v1/gfx/petab_files.pdf diff --git a/doc/gfx/petab_files.png b/doc/v1/gfx/petab_files.png similarity index 100% rename from doc/gfx/petab_files.png rename to doc/v1/gfx/petab_files.png diff --git a/doc/gfx/petab_files.svg b/doc/v1/gfx/petab_files.svg similarity index 100% rename from doc/gfx/petab_files.svg rename to doc/v1/gfx/petab_files.svg diff --git a/doc/gfx/petab_scope_and_files.pdf b/doc/v1/gfx/petab_scope_and_files.pdf similarity index 100% rename from doc/gfx/petab_scope_and_files.pdf rename to doc/v1/gfx/petab_scope_and_files.pdf diff --git a/doc/gfx/petab_scope_and_files.png b/doc/v1/gfx/petab_scope_and_files.png similarity index 100% rename from doc/gfx/petab_scope_and_files.png rename to doc/v1/gfx/petab_scope_and_files.png diff --git a/doc/gfx/petab_scope_and_files.svg b/doc/v1/gfx/petab_scope_and_files.svg similarity index 100% rename from doc/gfx/petab_scope_and_files.svg rename to doc/v1/gfx/petab_scope_and_files.svg diff --git a/doc/v2/documentation_data_format.rst b/doc/v2/documentation_data_format.rst index bebb48af..a969fbe9 100644 --- a/doc/v2/documentation_data_format.rst +++ b/doc/v2/documentation_data_format.rst @@ -1,3 +1,7 @@ +.. warning:: + + This document is a draft and subject to change. + PEtab data format specification =============================== @@ -31,7 +35,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:: ../gfx/petab_scope_and_files.png +.. figure:: ../v1/gfx/petab_scope_and_files.png :alt: A common setup for data-based modeling studies and its representation in PEtab. :scale: 80% @@ -69,7 +73,7 @@ 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:: ../gfx/petab_files.png +.. figure:: ../v1/gfx/petab_files.png :alt: Files constituting a PEtab problem **Figure 2: Files constituting a PEtab problem.** @@ -793,11 +797,10 @@ model. YAML file for grouping files ---------------------------- -To link the SBML model, measurement table, condition table, etc. in an +To link the model, measurement table, condition table, etc. in an unambiguous way, we use a `YAML `_ file. -This file also allows specifying a PEtab version (as the format is not unlikely -to change in the future) and employed PEtab extensions. +This file also allows specifying a PEtab version and employed PEtab extensions. Furthermore, this can be used to describe parameter estimation problems comprising multiple models (more details below). @@ -998,6 +1001,8 @@ languages. Use parentheses to enforce the desired order of operations. Operators must be specified; there are no implicit operators. For example, ``a b`` is invalid, unlike ``a * b``. +.. _math_functions: + Functions +++++++++ @@ -1152,8 +1157,7 @@ Identifiers * Identifiers must not be a reserved keyword (see below). * Identifiers must be globally unique within the PEtab problem. - PEtab math function names must not be used as identifiers for other model - entities. PEtab does not put any further restrictions on the use of + PEtab does not put any further restrictions on the use of identifiers within the model, which means modelers could potentially use model-format--specific (e.g. SBML) function names as identifiers. However, this is strongly discouraged. @@ -1169,4 +1173,4 @@ as identifiers: measurements * ``time``: Model time, used in PEtab expressions. * ``nan``: Undefined in PEtab, but reserved to avoid implementation issues. - +* PEtab math function names (:ref:`math_functions`)