File formats to RTD

README.md

@@ -47,122 +47,6 @@ if there are no models with 3 estimated parameters, but some models with 4
 estimated parameters, then the search may return candidate models with 4
 estimated parameters.
 
-## File formats
-
-Column or key names that are surrounding by square brackets
-(e.g. `[constraint_files]`) are optional.
-
-### Selection problem
-
-A YAML file with a description of the model selection problem.
-
-```yaml
-format_version: [string]
-criterion: [string]
-method: [string]
-model_space_files: [List of filenames]
-[constraint_files]: [List of filenames]
-[predecessor_model_files]: [List of filenames]
-```
-
-- `format_version`: The version of the model selection extension format (
-  e.g. `'beta_1'`)
-- `criterion`: The criterion by which models should be compared (e.g. `'AIC'`)
-- `method`: The method by which model candidates should be generated
-  (e.g. `'forward'`)
-- `model_space_files`: The filenames of model space files.
-- `constraint_files`: The filenames of constraint files.
-- `predecessor_model_files`: The filenames of predecessor (initial) model
-  files.
-
-### Model space
-
-A TSV with candidate models, in compressed or uncompressed format.
-
-| `model_subspace_id` | `petab_yaml` | [`sbml`] | `parameter_id_1`                                     | ... | `parameter_id_n`                                     |
-|---------------------|--------------|----------|------------------------------------------------------|-----|------------------------------------------------------|
-| (Unique) [string]   | [string]     | [string] | [string/float] OR [; delimited list of string/float] | ... | [string/float] OR [; delimited list of string/float] |
-
-- `model_subspace_id`: An ID for the model subspace.
-- `petab_yaml`: The PEtab YAML filename that serves as the base for a model.
-- `sbml`: An SBML filename. If the PEtab YAML file specifies multiple SBML
-  models, this can select a specific model by model filename.
-- `parameter_id_1`...`parameter_id_n` : Parameter IDs that are specified to
-  take specific values or be estimated. Example valid values are:
-    - uncompressed format:
-        - `0.0`
-        - `1.0`
-        - `estimate`
-    - compressed format
-        - `0.0;1.1;estimate` (the parameter can take the values `0.0` or `1.1`,
-          or be estimated according to the PEtab problem)
-
-### Constraints
-
-A TSV file with constraints.
-
-| `petab_yaml` | [`if`]                       | `constraint`                 |
-|--------------|------------------------------|------------------------------|
-| [string]     | [SBML L3 Formula expression] | [SBML L3 Formula expression] |
-
-- `petab_yaml`: The filename of the PEtab YAML file that this constraint
-  applies to.
-- `if`: As a single YAML can relate to multiple models in the model space file,
-  this ensures the constraint is only applied to the models that match
-  this `if` statement
-- `constraint`: If a model violates this constraint, it is skipped during the
-  model selection process and not optimized.
-
-### Model(s) (Predecessor models / model interchange / report)
-
-- *Predecessor models* are used to initialize an appropriate model selection
-  method. Model IDs should be unique here and compared to model IDs in any
-  model space files.
-- *Model interchange* refers to the format used to transfer model information
-  between PEtab Select and a PEtab-compatible calibration tool, during the
-  model selection process.
-- *Report* refers to the final results of the model selection process, which may
-  include calibration results from any calibrated models, or just the select
-  model.
-
-Here, the format for a single model is shown. Multiple models can be specified
-as a YAML list of the same format.
-
-The only required key is the PEtab YAML, as a model requires a PEtab problem.
-All other keys are maybe required, for the different uses of the format (e.g.,
-the report format should include `estimated_parameters`), or at different
-stages of the model selection process (the PEtab-compatible calibration tool
-should provide `criteria` for model comparison).
-
-```yaml
-[criteria]: [Dictionary of criterion names and values]
-[estimated_parameters]: [Dictionary of parameter IDs and values]
-[model_hash]: [string]
-[model_id]: [string]
-[parameters]: [Dictionary of parameter IDs and values]
-petab_yaml: [string]
-[predecessor_model_hash]: [string]
-[sbml]: [string]
-```
-
-- `criteria`: The value of the criterion by which model selection was
-  performed, at least. Optionally, other criterion values too.
-- `estimated_parameters`: Parameter estimates, not only of parameters specified
-  to be estimated in a model space file, but also parameters specified to be
-  estimated in the original PEtab problem of the model.
-- `model_hash`: The model hash, generated by the PEtab Select library.
-- `model_id`: The model ID.
-- `model_subspace_id`: Same as in the model space files.
-- `model_subspace_indices`: The indices that locate this model in its model
-  subspace.
-- `parameters`: The parameters from the problem (either values
-  or `'estimate'`) (a specific combination from a model space file, but
-  uncalibrated).
-- `petab_yaml`: Same as in model space files.
-- `predecessor_model_hash`: The hash of the model that preceded this model
-  during the model selection process.
-- `sbml`: Same as in model space files.
-
 ## Test cases
 
 Several test cases are provided, to test the compatibility of a

doc/index.rst

@@ -12,6 +12,7 @@ Welcome to petab-select's documentation!
 
    examples
    api
+   problem_definition
 
 
 Indices and tables

doc/problem_definition.rst

@@ -0,0 +1,124 @@
+Problem definition and file formats
+===================================
+
+Model selection problems for PEtab Select are defined by the following
+components:
+
+* A general description of the model selection problem
+* Model space files that specify the initial set of candidate models
+* Constraints files that further restrict the model space
+* Predecessor model files that are used to initialize the model selection
+  process
+
+The different file formats are described below.
+Column or key names that are surrounded by square brackets
+(e.g. \[constraint_files\]) are optional.
+
+Selection problem
+-----------------
+
+A YAML file with a description of the model selection problem.
+
+.. code-block:: yaml
+
+   format_version: [string]
+   criterion: [string]
+   method: [string]
+   model_space_files: [List of filenames]
+   [constraint_files]: [List of filenames]
+   [predecessor_model_files]: [List of filenames]
+
+- ``format_version``: The version of the model selection extension format (e.g. ``'beta_1'``)
+- ``criterion``: The criterion by which models should be compared (e.g. ``'AIC'``)
+- ``method``: The method by which model candidates should be generated (e.g. ``'forward'``)
+- ``model_space_files``: The filenames of model space files.
+- ``constraint_files``: The filenames of constraint files.
+- ``predecessor_model_files``: The filenames of predecessor (initial) model files.
+
+Model space
+-----------
+
+A TSV with candidate models, in compressed or uncompressed format.
+
+.. list-table::
+   :header-rows: 1
+
+   * - ``model_subspace_id``
+     - ``petab_yaml``
+     - ``sbml``
+     - ``parameter_id_1``
+     - ...
+     - ``parameter_id_n``
+   * - (Unique) [string]
+     - [string]
+     - [string]
+     - [string/float] OR [; delimited list of string/float]
+     - ...
+     - [string/float] OR [; delimited list of string/float]
+
+- ``model_subspace_id``: An ID for the model subspace.
+- ``petab_yaml``: The PEtab YAML filename that serves as the base for a model.
+- ``sbml``: An SBML filename. If the PEtab YAML file specifies multiple SBML models, this can select a specific model by model filename.
+- ``parameter_id_1``...``parameter_id_n``: Parameter IDs that are specified to take specific values or be estimated. Example valid values are:
+
+  - uncompressed format:
+
+    - ``0.0``
+    - ``1.0``
+    - ``estimate``
+
+  - compressed format:
+
+    - ``0.0;1.1;estimate`` (the parameter can take the values ``0.0`` or ``1.1``, or be estimated according to the PEtab problem)
+
+Constraints
+-----------
+
+A TSV file with constraints.
+
+.. list-table::
+   :header-rows: 1
+
+   * - ``petab_yaml``
+     - ``if``
+     - ``constraint``
+   * - [string]
+     - [SBML L3 Formula expression]
+     - [SBML L3 Formula expression]
+
+- ``petab_yaml``: The filename of the PEtab YAML file that this constraint applies to.
+- ``if``: As a single YAML can relate to multiple models in the model space file, this ensures the constraint is only applied to the models that match this ``if`` statement
+- ``constraint``: If a model violates this constraint, it is skipped during the model selection process and not optimized.
+
+Model(s) (Predecessor models / model interchange / report)
+----------------------------------------------------------
+
+- *Predecessor models* are used to initialize an appropriate model selection method. Model IDs should be unique here and compared to model IDs in any model space files.
+- *Model interchange* refers to the format used to transfer model information between PEtab Select and a PEtab-compatible calibration tool, during the model selection process.
+- *Report* refers to the final results of the model selection process, which may include calibration results from any calibrated models, or just the select model.
+
+Here, the format for a single model is shown. Multiple models can be specified as a YAML list of the same format.
+
+The only required key is the PEtab YAML, as a model requires a PEtab problem. All other keys are maybe required, for the different uses of the format (e.g., the report format should include ``estimated_parameters``), or at different stages of the model selection process (the PEtab-compatible calibration tool should provide ``criteria`` for model comparison).
+
+.. code-block:: yaml
+
+   [criteria]: [Dictionary of criterion names and values]
+   [estimated_parameters]: [Dictionary of parameter IDs and values]
+   [model_hash]: [string]
+   [model_id]: [string]
+   [parameters]: [Dictionary of parameter IDs and values]
+   petab_yaml: [string]
+   [predecessor_model_hash]: [string]
+   [sbml]: [string]
+
+- ``criteria``: The value of the criterion by which model selection was performed, at least. Optionally, other criterion values too.
+- ``estimated_parameters``: Parameter estimates, not only of parameters specified to be estimated in a model space file, but also parameters specified to be estimated in the original PEtab problem of the model.
+- ``model_hash``: The model hash, generated by the PEtab Select library.
+- ``model_id``: The model ID.
+- ``model_subspace_id``: Same as in the model space files.
+- ``model_subspace_indices``: The indices that locate this model in its model subspace.
+- ``parameters``: The parameters from the problem (either values or ``'estimate'``) (a specific combination from a model space file, but uncalibrated).
+- ``petab_yaml``: Same as in model space files.
+- ``predecessor_model_hash``: The hash of the model that preceded this model during the model selection process.
+- ``sbml``: Same as in model space files.