Create standard/schema for a Model (#130)

* refactor `Model` with mkstd

* remove constraint column (constraints aren't implemented yet)

* update test cases 1-8 expected models

* refactor to remove `PetabMixin`

* predecessor_model now always set to virtual or real model; update candidate_space.py

* model subspace: require explicit parameter definitions; implement `can_fix_all`

* fix 0009 expected yaml

* add schema; add to RTD

---------

Co-authored-by: Daniel Weindl <[email protected]>

doc/conf.py

@@ -58,7 +58,7 @@
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
 
 html_theme = "sphinx_rtd_theme"
-# html_static_path = ['_static']
+html_static_path = ["standard"]
 html_logo = "logo/logo-wide.svg"
 
 

doc/problem_definition.rst

@@ -7,7 +7,9 @@ Model selection problems for PEtab Select are defined by the following files:
 #. a specification of the model space, and
 #. (optionally) a specification of the initial candidate model.
 
-The different file formats are described below.
+The different file formats are described below. Each file format is a YAML file
+and comes with a YAML-formatted JSON schema, such that these files can be
+easily worked with independently of the PEtab Select library.
 
 1. Selection problem
 --------------------
@@ -116,28 +118,41 @@ can be specified like
   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
+as a YAML list of the same format. Some optional keys are required in different
 contexts (for example, model comparison will require ``criteria``).
 
+Brief format description
+^^^^^^^^^^^^^^^^^^^^^^^^
+
+
 .. 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).
+   model_subspace_id: # str (required).
+   model_subspace_indices: # list[int] (required).
+   criteria: # dict[str, float] (optional). Criterion ID => criterion value.
+   model_hash: # str (optional).
+   model_subspace_petab_yaml: # str (required).
+   estimated_parameters: # dict[str, float] (optional). Parameter ID => parameter value.
+   iteration: # int (optional).
+   model_id: # str (optional).
+   parameters: # dict[str, float | int | "estimate"] (required). Parameter ID => parameter value or "estimate".
+   predecessor_model_hash: # str (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.
+- ``criteria``: The value of the criterion by which model selection was performed, at least. Optionally, other criterion values too.
+- ``model_hash``: The model hash, generated by the PEtab Select library. The format is ``[MODEL_SUBSPACE_ID]-[MODEL_SUBSPACE_INDICES_HASH]``. If all parameters are in the model are defined like ``0;estimate``, then the hash is a string of ``1`` and ``0``, for parameters that are estimated or not, respectively.
+- ``model_subspace_petab_yaml``: Same as in model space files (see ``petab_yaml``).
+- ``estimated_parameters``: Parameter estimates, including all estimated parameters that are not in the model selection problem; i.e., parameters that are set to be estimated in the model subspace PEtab problem but don't appear in the column header of the model space file.
+- ``iteration``: The iteration of model selection in which this model appeared.
+- ``model_id``: The model ID.
+- ``parameters``: The parameter combination from the model space file that defines this model (either values or ``"estimate"``). Not the calibrated values, which are in ``estimated_parameters``!
+- ``predecessor_model_hash``: The hash of the model that preceded this model during the model selection process. Will be ``virtual_initial_model-`` if the model had no predecessor model.
+
+Schema
+^^^^^^
+
+The format is provided as `YAML-formatted JSON schema <_static/model.yaml>`_, which enables easy validation with various third-party tools.
+
+.. literalinclude:: standard/model.yaml
+   :language: yaml

doc/standard/make_schemas.py

@@ -0,0 +1,3 @@
+from petab_select.model import ModelStandard
+
+ModelStandard.save_schema("model.yaml")

doc/standard/model.yaml

@@ -0,0 +1,67 @@
+$defs:
+  ModelHash:
+    type: string
+description: "A model.\n\nSee :class:`ModelBase` for the standardized attributes.\
+  \ Additional\nattributes are available in ``Model`` to improve usability.\n\nAttributes:\n\
+  \    _model_subspace_petab_problem:\n        The PEtab problem of the model subspace\
+  \ of this model.\n        If not provided, this is reconstructed from\n        :attr:`model_subspace_petab_yaml`."
+properties:
+  model_subspace_id:
+    title: Model Subspace Id
+    type: string
+  model_subspace_indices:
+    items:
+      type: integer
+    title: Model Subspace Indices
+    type: array
+  criteria:
+    additionalProperties:
+      type: number
+    title: Criteria
+    type: object
+  model_hash:
+    $ref: '#/$defs/ModelHash'
+    default: null
+  model_subspace_petab_yaml:
+    anyOf:
+    - format: path
+      type: string
+    - type: 'null'
+    title: Model Subspace Petab Yaml
+  estimated_parameters:
+    anyOf:
+    - additionalProperties:
+        type: number
+      type: object
+    - type: 'null'
+    default: null
+    title: Estimated Parameters
+  iteration:
+    anyOf:
+    - type: integer
+    - type: 'null'
+    default: null
+    title: Iteration
+  model_id:
+    default: null
+    title: Model Id
+    type: string
+  parameters:
+    additionalProperties:
+      anyOf:
+      - type: number
+      - type: integer
+      - const: estimate
+        type: string
+    title: Parameters
+    type: object
+  predecessor_model_hash:
+    $ref: '#/$defs/ModelHash'
+    default: null
+required:
+- model_subspace_id
+- model_subspace_indices
+- model_subspace_petab_yaml
+- parameters
+title: Model
+type: object

doc/test_suite.rst

@@ -15,70 +15,60 @@ the model format.
      - Method
      - Model space files
      - Compressed format
-     - Constraints files
      - Predecessor (initial) models files
    * - 0001
      - (all)
      - (only one model)
      - 1
      -
      -
-     -
    * - 0002 [#f1]_
      - AIC
      - forward
      - 1
      -
      -
-     -
    * - 0003
      - BIC
-     - all
+     - brute force
      - 1
      - Yes
      -
-     -
    * - 0004
      - AICc
      - backward
      - 1
      -
-     - 1
      -
    * - 0005
      - AIC
      - forward
      - 1
      -
-     -
      - 1
    * - 0006
      - AIC
      - forward
      - 1
      -
      -
-     -
    * - 0007 [#f2]_
      - AIC
      - forward
      - 1
      -
      -
-     -
    * - 0008 [#f2]_
      - AICc
      - backward
      - 1
      -
      -
-     -
    * - 0009 [#f3]_
      - AICc
      - FAMoS
      - 1
      - Yes
-     -
      - Yes
 
 .. [#f1] Model ``M1_0`` differs from ``M1_1`` in three parameters, but only 1 additional estimated parameter. The effect of this on model selection criteria needs to be clarified. Test case 0006 is a duplicate of 0002 that doesn't have this issue.