WIP: Specification of Timecourses

.github/ISSUE_TEMPLATE/petab-extensions.md

@@ -0,0 +1,27 @@
+---
+
+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 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.
+
+**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 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.

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

README.md

@@ -140,6 +140,8 @@ will have to:
 
 1. Create a parameter table.
 
+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
 you with that. This includes also a PEtab validator called `petablint` which

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: |
@@ -31,7 +35,7 @@ properties:
       type: object
       description: |
         A set of PEtab model, condition, observable and measurement
-        files and optional visualization files.
+        files and optional visualization and time courses files.
       properties:
 
         sbml_files:
@@ -74,11 +78,44 @@ properties:
             type: string
             description: PEtab visualization file name or URL.
 
+        timecourse_files:
+          type: array
+          description: List of PEtab time courses files
+
+          items: 
+            type: string
+            description: PEtab time courses file name or URL.
+
       required:
         - sbml_files
         - observable_files
         - 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:
+            type: bool
+            description: |
+              Indicates whether the extension is required for the
+              mathematical interpretation of problem.
+        required:
+          - version
+          - required
+      additionalProperties: true
+
+    additionalProperties: false
 
 required:
   - format_version

doc/development.rst

@@ -192,6 +192,56 @@ 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
+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 PEtab-YAML files
+* 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.
+
+Developers are free to develop any PEtab extension. To become an official
+PEtab extension, it needs to go through the following process.
+
+#. The developers write a proposal describing the motivation and specification
+   of the extension, following the respective issue template provided in this
+   repository.
+#. The proposal is submitted as an issue in this repository.
+#. The technical specification and documentation of the extension is submitted
+   as a pull request in this repository that references the respective issue.
+
+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. There is no quorum number of votes
+for acceptance.
+
+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
 ------------------------------