diff --git a/README.md b/README.md index a5f091cd..15dff1f6 100644 --- a/README.md +++ b/README.md @@ -46,119 +46,3 @@ given the forward method and a predecessor model with 2 estimated parameters, 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. diff --git a/doc/index.rst b/doc/index.rst index 35c20954..62c081a6 100644 --- a/doc/index.rst +++ b/doc/index.rst @@ -13,6 +13,7 @@ Welcome to petab-select's documentation! examples Test Suite api + problem_definition Indices and tables diff --git a/doc/problem_definition.rst b/doc/problem_definition.rst new file mode 100644 index 00000000..4734cb9b --- /dev/null +++ b/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[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.