diff --git a/doc/problem_definition.rst b/doc/problem_definition.rst index 4734cb9..3a544b5 100644 --- a/doc/problem_definition.rst +++ b/doc/problem_definition.rst @@ -1,21 +1,16 @@ Problem definition and file formats =================================== -Model selection problems for PEtab Select are defined by the following -components: +Model selection problems for PEtab Select are defined by the following files: -* 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 +#. 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. -Column or key names that are surrounded by square brackets -(e.g. \[constraint_files\]) are optional. -Selection problem ------------------ +1. Selection problem +-------------------- A YAML file with a description of the model selection problem. @@ -25,41 +20,51 @@ A YAML file with a description of the model selection problem. 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'``) + 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. -- ``constraint_files``: The filenames of constraint files. -- ``predecessor_model_files``: The filenames of predecessor (initial) model 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 -Model space ------------ +2. Model space +-------------- -A TSV with candidate models, in compressed or uncompressed format. +A TSV with candidate models, in compressed or uncompressed format. Each row +defines a model subspace. .. list-table:: :header-rows: 1 * - ``model_subspace_id`` - ``petab_yaml`` - - ``sbml`` - ``parameter_id_1`` - ... - ``parameter_id_n`` - * - (Unique) [string] - - [string] + * - (unique) [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: +- ``petab_yaml``: The PEtab YAML filename that serves as the basis of all + models in this subspace. +- ``parameter_id_1``...``parameter_id_n``: Parameter IDs that are specified to + take specific values or be estimated. Example valid values are: - uncompressed format: @@ -69,37 +74,25 @@ A TSV with candidate models, in compressed or uncompressed format. - 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) ----------------------------------------------------------- + - ``0.0;1.1;estimate`` (the parameter can take the values ``0.0`` or + ``1.1``, or be estimated) -- *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. +3. Model(s) (Predecessor models / model interchange / report) +------------------------------------------------------------- -Here, the format for a single model is shown. Multiple models can be specified as a YAML list of the same format. +- *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. -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). +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 ``criterion``. .. code-block:: yaml @@ -107,10 +100,11 @@ The only required key is the PEtab YAML, as a model requires a PEtab problem. Al 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). - 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. @@ -121,4 +115,3 @@ The only required key is the PEtab YAML, as a model requires a PEtab problem. Al - ``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/petab_select/constants.py b/petab_select/constants.py index 692e019..bba90ac 100644 --- a/petab_select/constants.py +++ b/petab_select/constants.py @@ -49,7 +49,6 @@ PREDECESSOR_MODEL_HASH = "predecessor_model_hash" PETAB_PROBLEM = "petab_problem" PETAB_YAML = "petab_yaml" -SBML = "sbml" HASH = "hash" # MODEL_SPACE_FILE_NON_PARAMETER_COLUMNS = [MODEL_ID, PETAB_YAML]