Doc: Add 'scope' section and illustration of PEtab components (#486)

* Doc: Add 'scope' section and illustration of PEtab components

* Image to figure, add caption, update references

* fixup

Author: dweindl

doc/documentation_data_format.rst

@@ -15,14 +15,36 @@ systems biology, especially for the case of Ordinary Differential Equation
 (ODE) models.
 
 
+Scope
+-----
+
+The scope of PEtab is the full specification of parameter estimation problems
+in typical systems biology applications. In our experience, a typical setup of
+data-based modeling starts either with (i) the model of a biological system
+that is to be calibrated, or with (ii) experimental data that are to be
+integrated and analyzed using a computational model.
+Measurements are linked to the biological model by an observation and noise
+model. Often, measurements are taken after some perturbations have been
+applied, which are modeled as derivations from a generic model
+(Figure 1A). Therefore, one goal was to specify such a setup in the
+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
+   :alt: A common setup for data-based modeling studies and its representation in PEtab.
+   :scale: 80%
+
+   **Figure 1: A common setup for data-based modeling studies and its representation in PEtab.**
+
 Overview
 ---------
 
 The PEtab data format specifies a parameter estimation problem using a number
 of text-based files (`Systems Biology Markup Language (SBML) <http://sbml.org>`_
 and
-`Tab-Separated Values (TSV) <https://www.iana.org/assignments/media-types/text/tab-separated-values>`_),
-i.e.
+`Tab-Separated Values (TSV) <https://www.iana.org/assignments/media-types/text/tab-separated-values>`_)
+(Figure 2), i.e.
 
 - An SBML model [SBML]
 
@@ -42,9 +64,14 @@ i.e.
 - (optional) A visualization file, which contains specifications how the data
   and/or simulations should be plotted by the visualization routines [TSV]
 
-.. image:: gfx/petab_files.png
+.. figure:: gfx/petab_files.png
    :alt: Files constituting a PEtab problem
 
+   **Figure 2: Files constituting a PEtab problem.**
+
+Figure 1B shows how those files relate to a common setup for
+data-based modeling studies.
+
 The following sections will describe the minimum requirements of those
 components in the core standard, which should provide all information for
 defining the parameter estimation problem.