Skip to content

Commit

Permalink
Merge pull request #29 from Infectious-Disease-Modeling-Hubs/version-…
Browse files Browse the repository at this point in the history 
…docs

Introduce documentation versioning. Release v0.0.1
  • Loading branch information
@annakrystalli
annakrystalli committed Feb 22, 2023
2 parents db775f1 + 2d6620a commit ded383d
Show file tree
Hide file tree
Showing 3 changed files with 14 additions and 136 deletions.
4 changes: 4 additions & 0 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down
6 changes: 6 additions & 0 deletions docs/source/conf.py
View file
Original file line number Diff line number Diff line change
Expand Up @@ -37,6 +37,7 @@
"deflist",
"dollarmath",
"fieldlist",
"substitution"
]

# -- Options for HTML output
Expand All @@ -59,3 +60,8 @@

# -- Options for EPUB output
epub_show_urls = 'footnote'


myst_substitutions = {
'schema_version': "v0.0.1"
}
140 changes: 4 additions & 136 deletions docs/source/format/hub-metadata.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -36,8 +36,9 @@ 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

<script src="../_static/docson/widget.js" data-schema="https://raw.githubusercontent.com/Infectious-Disease-Modeling-Hubs/schemas/main/v0.0.0.9/admin-schema.json"></script>
<script src="../_static/docson/widget.js" data-schema="https://raw.githubusercontent.com/Infectious-Disease-Modeling-Hubs/schemas/main/v0.0.1/admin-schema.json"></script>

Other things we may want to consider adding here:
* Something about truth data?
Expand All @@ -46,141 +47,8 @@ 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

<script src="../_static/docson/widget.js" data-schema="https://raw.githubusercontent.com/Infectious-Disease-Modeling-Hubs/schemas/main/v0.0.0.9/tasks-schema.json"></script>
<script src="../_static/docson/widget.js" data-schema="https://raw.githubusercontent.com/Infectious-Disease-Modeling-Hubs/schemas/main/v0.0.1/tasks-schema.json"></script>

0 comments on commit ded383d

Please sign in to comment.