Problem definition and file formats
===================================

Model selection problems for PEtab Select are defined by the following files:

#. a general description of the model selection problem,
#. a specification of the model space, and
#. (optionally) a specification of the initial candidate model.

The different file formats are described below.

1. 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[string]. Filenames.
   candidate_space_arguments: # list[string] (optional). Filenames.

- ``format_version``: The version of the model selection extension format
  (e.g. ``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.
- ``candidate_space_arguments``: Additional arguments used to generate
  candidate models during model selection. For example, an initial candidate
  model can be specified with the following code, where
  ``predecessor_model.yaml`` is a valid model file. Additional arguments are
  provided in the documentation of the ``CandidateSpace`` class.

.. code-block:: yaml

   candidate_space_arguments:
     predecessor_model: predecessor_model.yaml

2. Model space
--------------

A TSV file with candidate models, in compressed or uncompressed format.
Each row defines a model subspace, by specifying value(s) that each parameter
can take. The models in a model subspace are all combinations of values across
all parameters.

.. list-table::
   :header-rows: 1

   * - ``model_subspace_id``
     - ``petab_yaml``
     - ``parameter_id_1``
     - ...
     - ``parameter_id_n``
   * - (unique) [string]
     - [string]
     - (``;``-delimited list) [string/float]
     - ...
     - ...

- ``model_subspace_id``: An ID for the model subspace.
- ``petab_yaml``: The PEtab YAML filename that serves as the basis of all
  models in this subspace.
- ``parameter_id_1`` ... ``parameter_id_n``: Specify the values that a
  parameter can take in the model subspace. For example, this could be:

  - a single value

    - ``0.0``
    - ``1.0``
    - ``estimate``

  - one of several possible values, as a ``;``-delimited list

    - ``0.0;1.1;estimate`` (the parameter can take the values ``0.0`` or
      ``1.1``, or be estimated)

Using the ``;``-delimited list format, a model subspace that has two parameters
(``p1, p2``) and six models:

- ``p1:=0, p2:=10``
- ``p1:=0, p2:=20``
- ``p1:=0, p2:=estimate``
- ``p1:=estimate, p2:=10``
- ``p1:=estimate, p2:=20``
- ``p1:=estimate, p2:=estimate``

can be specified like

.. list-table::
   :header-rows: 1

   * - model_subspace_id
     - petab_yaml
     - p1
     - p2
   * - subspace1
     - petab_problem.yaml
     - 0;estimate
     - 10;20;estimate

3. Model(s) (Predecessor models / model interchange / report)
-------------------------------------------------------------

- *Predecessor models* are used to initialize a compatible model selection
  method.
- *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
  selected 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. Other keys are required in different
contexts (for example, model comparison will require ``criteria``).

.. code-block:: yaml

   criteria: # dict[string, float] (optional). Criterion ID => criterion value.
   estimated_parameters: # dict[string, float] (optional). Parameter ID => parameter value.
   model_hash: # string (optional).
   model_id: # string (optional).
   model_subspace_id: # string (optional).
   model_subspace_indices: # string (optional).
   parameters: # dict[string, float] (optional). Parameter ID => parameter value or "estimate".
   petab_yaml: # string.
   predecessor_model_hash: # string (optional).

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