Apply suggestions from code review

Co-authored-by: Dilan Pathirana <[email protected]>

.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.

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
 

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

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

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.
 

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 <https://github.com/PEtab-dev/PEtab/tree/b50d000a5fb4cf37bf62315686acd2694e29e5fc/doc/tutorial>`_.
 
-.. 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
 

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.**

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 <https://yaml.org/>`_ 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`)