-
Notifications
You must be signed in to change notification settings - Fork 1
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Merge branch 'develop' into test_rtd
- Loading branch information
Showing
3 changed files
with
125 additions
and
116 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -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[string]. Filenames. | ||
| constraint_files: # list[string] (optional). Filenames. | ||
| predecessor_model_files: # list[string] (optional). 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: # 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). | ||
| parameters: # dict[string, float] (optional). Parameter ID => parameter value or "estimate". | ||
| petab_yaml: # string. | ||
| predecessor_model_hash: # string (optional). | ||
| sbml: # 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. | ||
| - ``sbml``: Same as in model space files. |