From 813ba0ee4068c84f986bf0a3ffcbc8f2d0d5e3ae Mon Sep 17 00:00:00 2001 From: FFroehlich Date: Wed, 20 Oct 2021 14:13:25 -0400 Subject: [PATCH 01/10] add proposal for extensions --- CHANGELOG.md | 7 ++++++ README.md | 2 ++ doc/development.rst | 54 +++++++++++++++++++++++++++++++++++++++++++++ doc/tutorial.rst | 15 ++++++------- 4 files changed, 70 insertions(+), 8 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 9e8a28ea..cb7597d3 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -14,6 +14,13 @@ available at https://github.com/PEtab-dev/libpetab-python/. * Update tutorial.rst (#512) * Update how-to-cite (Closes #432) (#509) +## 0.2 series + +### 0.2.0 + +* Specify how PEtab functionality can be expanded through extensions. +* YAML files are now required for the specification of PEtab problems + ## 0.1 series ### 0.1.14 diff --git a/README.md b/README.md index 849f5493..2c5a7aec 100644 --- a/README.md +++ b/README.md @@ -125,6 +125,8 @@ will have to: 1. Create a parameter table. +1. Create a yaml file that list 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 you with that. This includes also a PEtab validator called `petablint` which diff --git a/doc/development.rst b/doc/development.rst index 8c9f29c0..e06fd894 100644 --- a/doc/development.rst +++ b/doc/development.rst @@ -192,6 +192,60 @@ Upon a new release, the PEtab editors ensure that * the new version of the specifications is deposited at Zenodo * the new release is announced on the PEtab mailing list +PEtab Extensions +---------------- + +An elaborate, monolithic format would make it difficult to understand and +implement support for PEtab, leading to a steep learning curve and discouraging +support in new toolboxes. To address this issue the PEtab format is modular and +also permits modifications through extensions that complement the core standard. +This modular specification evens the learning curve and provides toolbox +developers with more guidance on which features to implement to maximize +support for real world applications. Moreover, such modular extensions +facilitate and promote the use of specialized tools for specific, non-parameter +estimation tasks such as visualization. + +Requirements for new extensions: + +* Specifications in PEtab extensions take precedence over PEtab core, i.e., they +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 versioned using semantic versioning. +* PEtab extensions required for interpretation of a problem specification must +be specified in the in the PEtab-YAML files +* There are at least two tools that support the proposed extension +* The authors provide a library that implements validation checks for the +proposed format. + +Developers are free to develop any PEtab extension. To become an official +PEtab extension, it needs to go through the following process. + +1. The developers write a proposal describing the motivation and specification +of the extension, following the template provided at XXXXXXX. +1. The proposal submitted as an issue in the https://github.com/PEtab-dev/PEtab +repository. +1. The technical specification and documentation of the extension is submitted +as pull request in https://github.com/PEtab-dev/PEtab that references the issue +in the https://github.com/PEtab-dev/PEtab repository. +1. The developers submit a pull request that adds test cases to validate support +for the extension https://github.com/PEtab-dev/petab_test_suite that references +the issue in the https://github.com/PEtab-dev/PEtab repository. + +The PEtab editors jointly decide whether an extension meets the requirements +described here. In case of a positive evaluation, they announce a poll for the +acceptance as official extension to the PEtab forum. All members of the PEtab +community are eligible to vote. If at least 50% of the votes are in favor, +the extension is accepted and the respective pull requests with specifications, +documentation and test cases are merged. + +It is encouraged that extensions are informally discussed with the community +before initiating the process of becoming an official extension. Such +discussions can be conducted through the communication channels mentioned +above. + + Versioning of the PEtab format ------------------------------ diff --git a/doc/tutorial.rst b/doc/tutorial.rst index b95908b5..e231b5d9 100644 --- a/doc/tutorial.rst +++ b/doc/tutorial.rst @@ -19,9 +19,9 @@ details of the model are not relevant for the purpose of this tutorial. For more details, we refer to the original publication. A PEtab problem consists of 1) an SBML model of a biological system, 2) -condition, observable and measurement definitions, and 3) the -specification of the parameters. We will show how to generate the -respective files in the following. +condition, observable and measurement definitions, 3) the +specification of the parameters and 4) a configuration file that lists all of +these files. We will show how to generate the respective files in the following. 1. The model ++++++++++++ @@ -324,11 +324,10 @@ https://petab.readthedocs.io/en/latest/documentation_data_format.html#visualizat 5. YAML file ++++++++++++ -To group the previously mentioned PEtab files, a YAML file can be used, -defining which files constitute a PEtab problem. While being optional, -this makes it easier to import a PEtab problem into tools, and allows -reusing files for different PEtab problems. This file has the following -format (``Boehm_JProteomeRes2014.yaml``): +To group the previously mentioned PEtab files, a YAML file must be used, +defining which files constitute a PEtab problem. This makes it easier to import +a PEtab problem into tools, and allows reusing files for different PEtab +problems. This file has the following format (``Boehm_JProteomeRes2014.yaml``): .. code-block:: yaml From 48ae6366f87027de73a22f4412a78dcb4f985ea7 Mon Sep 17 00:00:00 2001 From: FFroehlich Date: Wed, 20 Oct 2021 14:34:30 -0400 Subject: [PATCH 02/10] add issue template --- .github/ISSUE_TEMPLATE/petab-extensions.md | 26 ++++++++++++++++++++++ 1 file changed, 26 insertions(+) create mode 100644 .github/ISSUE_TEMPLATE/petab-extensions.md diff --git a/.github/ISSUE_TEMPLATE/petab-extensions.md b/.github/ISSUE_TEMPLATE/petab-extensions.md new file mode 100644 index 00000000..47eafe60 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/petab-extensions.md @@ -0,0 +1,26 @@ +--- +name: PEtab Extension +about: Suggest a new extension for PEtab core +title: '' +labels: file format +assignees: '' + +--- + +**Name of the Extension** +Please make sure that the extension is named matches the regular expressin `^[a-zA-Z_]\w*$`. + +**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. + +**Describe the solution you would like** +A clear and concise description of the changes you want to propose. Please describe any additional fields / files you would want to add, including allowed inputs and implications. + +**Describe why this should not be implemented by changes to PEtab core** +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. + +**List two toolboxes that support the proposed standard ** +A link to the website or github repository that contains the software that implements support for the standard. From c0a22d8259b96040c138686c4cc1331ff56a2da2 Mon Sep 17 00:00:00 2001 From: FFroehlich Date: Wed, 20 Oct 2021 14:37:36 -0400 Subject: [PATCH 03/10] update data format documentation --- doc/documentation_data_format.rst | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/doc/documentation_data_format.rst b/doc/documentation_data_format.rst index 76b088ad..cabdeed8 100644 --- a/doc/documentation_data_format.rst +++ b/doc/documentation_data_format.rst @@ -58,6 +58,9 @@ and - A parameter file specifying optimization parameters and related information [TSV] +- A grouping file that list all of the files and provides additional information + including employed extensions [YAML] + - (optional) A simulation file, which has the same format as the measurement file, but contains model simulations [TSV] @@ -697,7 +700,7 @@ To link the SBML 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). +to change in the future) and employed PEtab extensions. Furthermore, this can be used to describe parameter estimation problems comprising multiple models (more details below). From 1cc87b4fd0cf5633719bd7f432d1c1fbe918691d Mon Sep 17 00:00:00 2001 From: FFroehlich Date: Wed, 20 Oct 2021 14:39:16 -0400 Subject: [PATCH 04/10] Update development.rst --- doc/development.rst | 9 ++++----- 1 file changed, 4 insertions(+), 5 deletions(-) diff --git a/doc/development.rst b/doc/development.rst index e06fd894..e64031aa 100644 --- a/doc/development.rst +++ b/doc/development.rst @@ -223,15 +223,14 @@ Developers are free to develop any PEtab extension. To become an official PEtab extension, it needs to go through the following process. 1. The developers write a proposal describing the motivation and specification -of the extension, following the template provided at XXXXXXX. -1. The proposal submitted as an issue in the https://github.com/PEtab-dev/PEtab +of the extension, following the respective issue template provided in this repository. +1. The proposal submitted as an issue in this repository. 1. The technical specification and documentation of the extension is submitted -as pull request in https://github.com/PEtab-dev/PEtab that references the issue -in the https://github.com/PEtab-dev/PEtab repository. +as pull request in this repository that references the respective issue. 1. The developers submit a pull request that adds test cases to validate support for the extension https://github.com/PEtab-dev/petab_test_suite that references -the issue in the https://github.com/PEtab-dev/PEtab repository. +the issue in this repository. The PEtab editors jointly decide whether an extension meets the requirements described here. In case of a positive evaluation, they announce a poll for the From 52a378a944aa6765a8ccd5bb0f3fd44632ca91f3 Mon Sep 17 00:00:00 2001 From: Daniel Weindl Date: Thu, 28 Oct 2021 16:30:25 +0200 Subject: [PATCH 05/10] Fix documentation build on RTD (#530) * update reqs * m2r2 for markdown * anonymous_references --- .rtd_pip_reqs.txt | 43 +++++++++++++++++++++++++++++++++++++------ doc/conf.py | 4 ++-- doc/md2rst.py | 4 ++-- 3 files changed, 41 insertions(+), 10 deletions(-) diff --git a/.rtd_pip_reqs.txt b/.rtd_pip_reqs.txt index 52f9d30d..19e8aefb 100644 --- a/.rtd_pip_reqs.txt +++ b/.rtd_pip_reqs.txt @@ -1,6 +1,37 @@ -sphinx -sphinxcontrib-napoleon -sphinx-markdown-tables -sphinx-rtd-theme -recommonmark -m2r +# Direct dependencies: +# Sphinx +# sphinx-markdown-tables +# sphinx-rtd-theme +# sphinxcontrib-napoleon +# m2r2 +alabaster==0.7.12 +Babel==2.9.1 +certifi==2021.10.8 +charset-normalizer==2.0.7 +docutils==0.17.1 +idna==3.3 +imagesize==1.2.0 +Jinja2==3.0.2 +m2r2==0.3.1 +Markdown==3.3.4 +MarkupSafe==2.0.1 +mistune==0.8.4 +packaging==21.0 +pockets==0.9.1 +Pygments==2.10.0 +pyparsing==3.0.3 +pytz==2021.3 +requests==2.26.0 +six==1.16.0 +snowballstemmer==2.1.0 +Sphinx==4.2.0 +sphinx-markdown-tables==0.0.15 +sphinx-rtd-theme==1.0.0 +sphinxcontrib-applehelp==1.0.2 +sphinxcontrib-devhelp==1.0.2 +sphinxcontrib-htmlhelp==2.0.0 +sphinxcontrib-jsmath==1.0.1 +sphinxcontrib-napoleon==0.7 +sphinxcontrib-qthelp==1.0.3 +sphinxcontrib-serializinghtml==1.1.5 +urllib3==1.26.7 diff --git a/doc/conf.py b/doc/conf.py index 3cabc896..5db1a578 100644 --- a/doc/conf.py +++ b/doc/conf.py @@ -37,7 +37,7 @@ extensions = [ 'sphinx.ext.napoleon', 'sphinx.ext.autodoc', - 'recommonmark', + 'm2r2', 'sphinx.ext.autosummary', 'sphinx_markdown_tables', ] @@ -78,7 +78,7 @@ # html_theme = 'sphinx_rtd_theme' def setup(app): - app.add_stylesheet('custom.css') + app.add_css_file('custom.css') # Add any paths that contain custom static files (such as style sheets) here, # relative to this directory. They are copied after the builtin static files, # so a file named "default.css" will overwrite the builtin "default.css". diff --git a/doc/md2rst.py b/doc/md2rst.py index e7972e89..858ab0c4 100644 --- a/doc/md2rst.py +++ b/doc/md2rst.py @@ -1,4 +1,4 @@ -import m2r +import m2r2 import re @@ -25,7 +25,7 @@ def absolute_links(txt): def md2rst(source: str, target: str): txt = absolute_links(read(source)) - txt = m2r.convert(txt) + txt = m2r2.convert(txt, anonymous_references=True) with open(target, 'w') as f: f.write(txt) From 595e19902adc1beb5eb01b5c6a96cd3ee43d3d28 Mon Sep 17 00:00:00 2001 From: Daniel Weindl Date: Fri, 5 Nov 2021 12:08:13 +0100 Subject: [PATCH 06/10] Fix missing yaml file schema (#529) Got lost when splitting off the PEtab library... --- doc/_static/petab_schema.yaml | 86 +++++++++++++++++++++++++++++++++++ 1 file changed, 86 insertions(+) create mode 100644 doc/_static/petab_schema.yaml diff --git a/doc/_static/petab_schema.yaml b/doc/_static/petab_schema.yaml new file mode 100644 index 00000000..bf012e57 --- /dev/null +++ b/doc/_static/petab_schema.yaml @@ -0,0 +1,86 @@ +# For syntax see: https://json-schema.org/understanding-json-schema/index.html +#$schema: "https://json-schema.org/draft/2019-09/meta/core" +$schema: "http://json-schema.org/draft-06/schema" +description: PEtab parameter estimation problem config file schema + +properties: + + format_version: + type: integer + description: Version of the PEtab format (e.g. 1). + + parameter_file: + oneOf: + - type: string + - type: array + description: | + 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, condition, observable and measurement + files and optional visualization files. + properties: + + sbml_files: + type: array + description: List of PEtab SBML files. + + items: + type: string + description: PEtab SBML file name or URL. + + measurement_files: + type: array + description: List of PEtab measurement files. + + items: + type: string + description: PEtab measurement file name or URL. + + condition_files: + type: array + description: List of PEtab condition files. + + items: + type: string + description: PEtab condition 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. + + items: + type: string + description: PEtab visualization file name or URL. + + required: + - sbml_files + - observable_files + - measurement_files + - condition_files + +required: + - format_version + - parameter_file + - problems From a7c376369f2fffed6ef999d116f80f1a15b0fb14 Mon Sep 17 00:00:00 2001 From: FFroehlich Date: Tue, 16 Nov 2021 11:39:51 -0500 Subject: [PATCH 07/10] Update petab_schema.yaml --- doc/_static/petab_schema.yaml | 31 ++++++++++++++++++++++++++++--- 1 file changed, 28 insertions(+), 3 deletions(-) diff --git a/doc/_static/petab_schema.yaml b/doc/_static/petab_schema.yaml index bf012e57..06e78770 100644 --- a/doc/_static/petab_schema.yaml +++ b/doc/_static/petab_schema.yaml @@ -6,8 +6,13 @@ description: PEtab parameter estimation problem config file schema properties: format_version: - type: integer - description: Version of the PEtab format (e.g. 1). + anyof: + - type: string + # (corresponding to PEP 440). + pattern: ^([1-9][0-9]*!)?(0|[1-9][0-9]*)(\.(0|[1-9][0-9]*))*((a|b|rc)(0|[1-9][0-9]*))?(\.post(0|[1-9][0-9]*))?(\.dev(0|[1-9][0-9]*))?$ + - type: integer + + description: Version of the PEtab format parameter_file: oneOf: @@ -17,7 +22,6 @@ 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: | @@ -80,6 +84,27 @@ properties: - measurement_files - condition_files + extensions: + type: object + description: | + PEtab extensions being used. + patternProperties: + "^[a-zA-Z_]\\w*$": + + type: object + description: | + Information on a specific extension + properties: + version: + type: string + pattern: ^([1-9][0-9]*!)?(0|[1-9][0-9]*)(\.(0|[1-9][0-9]*))*((a|b|rc)(0|[1-9][0-9]*))?(\.post(0|[1-9][0-9]*))?(\.dev(0|[1-9][0-9]*))?$ + + required: + - version + additionalProperties: true + + additionalProperties: false + required: - format_version - parameter_file From bd7215f80e7b36d822023d3002439448d1f0df96 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Fabian=20Fr=C3=B6hlich?= Date: Tue, 16 Nov 2021 11:40:42 -0500 Subject: [PATCH 08/10] Apply suggestions from code review Co-authored-by: Daniel Weindl --- .github/ISSUE_TEMPLATE/petab-extensions.md | 4 ++-- README.md | 2 +- doc/development.rst | 2 +- 3 files changed, 4 insertions(+), 4 deletions(-) diff --git a/.github/ISSUE_TEMPLATE/petab-extensions.md b/.github/ISSUE_TEMPLATE/petab-extensions.md index 47eafe60..9b99d252 100644 --- a/.github/ISSUE_TEMPLATE/petab-extensions.md +++ b/.github/ISSUE_TEMPLATE/petab-extensions.md @@ -8,7 +8,7 @@ assignees: '' --- **Name of the Extension** -Please make sure that the extension is named matches the regular expressin `^[a-zA-Z_]\w*$`. +Please make sure that the extension name matches the regular expression `^[a-zA-Z_]\w*$`. **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. @@ -22,5 +22,5 @@ A clear and concise description in what way the proposed changes introduce featu **List the extension library that implements validation checks** A link to the website or github repository that accompanies the proposed extension. -**List two toolboxes that support the proposed standard ** +**List two toolboxes that support the proposed standard** A link to the website or github repository that contains the software that implements support for the standard. diff --git a/README.md b/README.md index cdd6b55d..b063e928 100644 --- a/README.md +++ b/README.md @@ -125,7 +125,7 @@ will have to: 1. Create a parameter table. -1. Create a yaml file that list 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/development.rst b/doc/development.rst index e64031aa..2a6bc348 100644 --- a/doc/development.rst +++ b/doc/development.rst @@ -214,7 +214,7 @@ 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 versioned using semantic versioning. * PEtab extensions required for interpretation of a problem specification must -be specified in the in the PEtab-YAML files +be specified in the PEtab-YAML files * There are at least two tools that support the proposed extension * The authors provide a library that implements validation checks for the proposed format. From db03fd8960b0494c5710397ad5cae382396265dc Mon Sep 17 00:00:00 2001 From: FFroehlich Date: Tue, 16 Nov 2021 12:10:16 -0500 Subject: [PATCH 09/10] Update development.rst --- doc/development.rst | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/doc/development.rst b/doc/development.rst index e64031aa..aab9b41a 100644 --- a/doc/development.rst +++ b/doc/development.rst @@ -197,8 +197,8 @@ PEtab Extensions An elaborate, monolithic format would make it difficult to understand and implement support for PEtab, leading to a steep learning curve and discouraging -support in new toolboxes. To address this issue the PEtab format is modular and -also permits modifications through extensions that complement the core standard. +support in new toolboxes. To address this issue, the PEtab format is modular and +permits modifications through extensions that complement the core standard. This modular specification evens the learning curve and provides toolbox developers with more guidance on which features to implement to maximize support for real world applications. Moreover, such modular extensions @@ -215,7 +215,7 @@ tasks, i.e., they should not make trivial changes to PEtab core. * PEtab extensions must be versioned using semantic versioning. * PEtab extensions required for interpretation of a problem specification must be specified in the in the PEtab-YAML files -* There are at least two tools that support the proposed extension +* There are at least one tool that supports the proposed extension * The authors provide a library that implements validation checks for the proposed format. @@ -229,8 +229,9 @@ repository. 1. The technical specification and documentation of the extension is submitted as pull request in this repository that references the respective issue. 1. The developers submit a pull request that adds test cases to validate support -for the extension https://github.com/PEtab-dev/petab_test_suite that references -the issue in this repository. +for the extension in the https://github.com/PEtab-dev/petab_test_suite +repository. The external pull request must also reference the issue containing +the proposal. The PEtab editors jointly decide whether an extension meets the requirements described here. In case of a positive evaluation, they announce a poll for the @@ -244,7 +245,6 @@ before initiating the process of becoming an official extension. Such discussions can be conducted through the communication channels mentioned above. - Versioning of the PEtab format ------------------------------ From 128ddb3909ae72bac54150b1823f66a5c1ad2db2 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Fabian=20Fr=C3=B6hlich?= Date: Tue, 14 Dec 2021 10:03:49 -0500 Subject: [PATCH 10/10] Apply suggestions from code review MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Yannik Schälte <31767307+yannikschaelte@users.noreply.github.com> --- doc/development.rst | 4 ++-- doc/documentation_data_format.rst | 2 +- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/doc/development.rst b/doc/development.rst index a8dcc18d..c7e1a0ec 100644 --- a/doc/development.rst +++ b/doc/development.rst @@ -225,9 +225,9 @@ PEtab extension, it needs to go through the following process. 1. The developers write a proposal describing the motivation and specification of the extension, following the respective issue template provided in this repository. -1. The proposal submitted as an issue in this repository. +1. The proposal is submitted as an issue in this repository. 1. The technical specification and documentation of the extension is submitted -as pull request in this repository that references the respective issue. +as a pull request in this repository that references the respective issue. 1. The developers submit a pull request that adds test cases to validate support for the extension in the https://github.com/PEtab-dev/petab_test_suite repository. The external pull request must also reference the issue containing diff --git a/doc/documentation_data_format.rst b/doc/documentation_data_format.rst index cabdeed8..14793ef9 100644 --- a/doc/documentation_data_format.rst +++ b/doc/documentation_data_format.rst @@ -58,7 +58,7 @@ and - A parameter file specifying optimization parameters and related information [TSV] -- A grouping file that list all of the files and provides additional information +- A grouping file that lists all of the files and provides additional information including employed extensions [YAML] - (optional) A simulation file, which has the same format as the measurement