From 1ab73f46ef58326e774bd5ae8ac410239b9c57eb Mon Sep 17 00:00:00 2001 From: Anna Krystalli Date: Wed, 22 Feb 2023 16:44:11 +0200 Subject: [PATCH 1/4] Update docson schema versions --- docs/source/format/hub-metadata.md | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/docs/source/format/hub-metadata.md b/docs/source/format/hub-metadata.md index 07a91fb2..9f42d90f 100644 --- a/docs/source/format/hub-metadata.md +++ b/docs/source/format/hub-metadata.md @@ -36,8 +36,7 @@ These are described separately in the following subsections. The administrative hub metadata file contains settings that are expected to remain fixed throughout a hub’s existence, or for which it is not required to retain past values in order to work with hub data. - - + Other things we may want to consider adding here: * Something about truth data? @@ -183,4 +182,4 @@ With options for `task_ids` and forecast representations broken down into those ### Model Tasks (`tasks.json`) Interactive Schema - + From d13e7e870d58cd1f969ddcc5088a28f7479ec0c8 Mon Sep 17 00:00:00 2001 From: Anna Krystalli Date: Wed, 22 Feb 2023 16:45:29 +0200 Subject: [PATCH 2/4] remove superceeded information about model task metadata --- docs/source/format/hub-metadata.md | 137 +---------------------------- 1 file changed, 3 insertions(+), 134 deletions(-) diff --git a/docs/source/format/hub-metadata.md b/docs/source/format/hub-metadata.md index 9f42d90f..fd65b78e 100644 --- a/docs/source/format/hub-metadata.md +++ b/docs/source/format/hub-metadata.md @@ -36,6 +36,8 @@ These are described separately in the following subsections. The administrative hub metadata file contains settings that are expected to remain fixed throughout a hub’s existence, or for which it is not required to retain past values in order to work with hub data. +### Hub administrative metadata (`admin.json`) Interactive Schema + Other things we may want to consider adding here: @@ -45,140 +47,7 @@ The administrative hub metadata file contains settings that are expected to rema (tasks_metadata)= ## Hub model task metadata (`tasks.json` file) -The hub model task metadata file specifies the model tasks and model output formats for the hub. To reduce redundancy, hubs may optionally specify a 'defaults' entry with values that apply unless they are overridden by round-specific entries; this may be particularly useful for forecast hubs, which typically accept the same formats for all rounds. - - -The hub model task metadata should follow this format: - - -* Top level object - * property named `“model_tasks”`, which is an object - * Each element of the model_tasks object corresponds to one submission round; its name specifies the round id. Hubs may optionally specify one entry named `“default”`, with settings that apply to all rounds; as noted above, this will primarily be of use in forecast hubs. The element for a single submission round is an array. - * Each element of the array for a single submission round is an object with two properties: `“task_ids”` and `“output_types”`. - * “Task_ids” - * Optionally, the top level object may contain other objects that define model task or output type definitions that are referenced multiple times. - -```json -{ - "model_tasks": [ - "default": [ - { - "task_ids": { - "location": { - "required": { - "$ref": "#/$defs/task_ids/location/us_states" - }, - "optional": { - "$ref": "#/$defs/task_ids/location/us_counties" - }, - }, - "age_group": { - "required": { - "$ref": "#/$defs/task_ids/age_group/all_ages" - }, - "optional": { - "$ref": "#/$defs/task_ids/age_group/age_subdivisions" - }, - }, - "horizon": { - "required": null, - "optional": { - "$ref": "#/$defs/task_ids/horizon/valid_horizons" - }, - }, - "outcome_variable": { - "required": null, - "optional": { - "$ref": "#/$defs/task_ids/outcome_variable/cases" - }, - } - }, - "output_types": { - "mean": { - "required": false - }, - "bin_prob": { - "required": { - "$ref": "#/$defs/output_type_ids/short_term_inc_bins" - }, - "optional": null - } - } - }, - { - "task_ids": { - "location": { - "required": { - "$ref": "#/$defs/task_ids/location/us_states" - }, - "optional": null, - }, - "age_group": { - "required": { - "$ref": "#/$defs/task_ids/age_group/all_ages" - }, - "optional": { - "$ref": "#/$defs/task_ids/age_group/age_subdivisions" - }, - }, - "horizon": { - "required": null, - "optional": { - "$ref": "#/$defs/task_ids/horizon/valid_horizons" - }, - }, - "outcome_variable": { - "required": null, - "optional": { - "$ref": "#/$defs/task_ids/outcome_variable/hosps_and_deaths" - }, - } - }, - "output_types": { - "mean": { - "required": false - }, - "cdf": { - "required": [10.0, 20.0], - "optional": null - } - } - }, - { - "task_groups": - "output_types": - }, - ], - "round-1": [ - // if needed, a complete specification of settings for round 1 here - ], - "round-2": [ - // if needed, a complete specification of settings for round 2 here - ] - ], - - - "$defs": { - "task_ids": { - "location": { - "us_nat_states": ["US", "01", "02", ..., "56"], - "us_counties": ["01001", ..., "56045"] - }, - "age_group": { - "all_ages": ["all_ages"] - "age_subdivisions": ["0-5 yr", ..., "65+ yr"] - }, - "horizon": { - "weekly_horizons": [1, 2, 3, 4], - "daily_horizons": [1, .., 28] - }, - "outcome_variable": … - } - } -} -``` - -With options for `task_ids` and forecast representations broken down into those that are required and those that are optional, with valid values/combinations of values specified using something like a `$ref` to a top-level list of options. +The hub model task metadata file specifies the model tasks and model output formats for the hub. ### Model Tasks (`tasks.json`) Interactive Schema From bdf18340ede84ce22456dcbcce0167ad08e0236c Mon Sep 17 00:00:00 2001 From: Anna Krystalli Date: Wed, 22 Feb 2023 16:46:28 +0200 Subject: [PATCH 3/4] add substitution functionality --- docs/source/conf.py | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/docs/source/conf.py b/docs/source/conf.py index e0dda9c0..abad9d8b 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -37,6 +37,7 @@ "deflist", "dollarmath", "fieldlist", + "substitution" ] # -- Options for HTML output @@ -59,3 +60,8 @@ # -- Options for EPUB output epub_show_urls = 'footnote' + + +myst_substitutions = { + 'schema_version': "v0.0.1" +} From 2d6620a10d8a4eca52d592387bfa4a04a946aed1 Mon Sep 17 00:00:00 2001 From: Anna Krystalli Date: Wed, 22 Feb 2023 17:14:15 +0200 Subject: [PATCH 4/4] add versioning documentation --- README.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/README.md b/README.md index 4630c04b..98ab7861 100644 --- a/README.md +++ b/README.md @@ -92,7 +92,11 @@ To use Live Server: 4. To disconnect the server, click on :no_entry_sign:. +# Versioning +Documentation is [versioned by using releases](https://docs.readthedocs.io/en/stable/versions.html). Releases should track releases of Hub schema versions in [`schemas` repository](https://github.com/Infectious-Disease-Modeling-Hubs/schemas). While changes to documentation text can be commited without creating a new release and will appear in th `latest` version of the documentation, **changes to documentation related to a new schema release must be accompanied by a new release in this repository**. New releases on `hubDocs` should use the same version number as the `schemas` release but without the `v` (e.g. a `v0.0.1` `schemas` version number would be released as `0.0.1` on `hubDocs`). + +Before making a new release, **ensure that URLs to schema files which power the interactive docson widget visualisation of schemas in the [`docs/source/format/hub-metadata.md` page](https://github.com/Infectious-Disease-Modeling-Hubs/hubDocs/blob/main/docs/source/format/hub-metadata.md?plain=1) are updated** to display the new versions of `admin.json` and `tasks.json` schema files. ## Contribution guidelines In general, contributions should be made via pull requests to the `main` branch.