add schema; add to RTD

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
 --------------------
@@ -122,22 +124,27 @@ 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).
+   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.
+
+.. 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