A JavaScript (ES6 ECMAScript) module for forecast visualization.
To use the component in your app, you'll need to add the following to your HTML:
- add
<script>and stylesheet<link>tags for dependencies to the<head> - add a
<div>to the<body>for the component to fill - add a
<script>in the<body>that initializes the component via the (default)Appobject that's exported
See the "HTML file example" section below for an example, and see the "JavaScript API" section for how to initialize the component.
In your HTML file, load the required CSS and JavaScript files:
- In the
<head>, load Bootstrap 5 and other required library files:
<!-- jquery -->
<script src="https://ajax.googleapis.com/ajax/libs/jquery/1.12.4/jquery.min.js"></script>
<!-- Bootstrap 5 -->
<script src="https://cdn.jsdelivr.net/npm/bootstrap@5.3.7/dist/js/bootstrap.bundle.min.js"
integrity="sha384-ndDqU0Gzau9qJ1lfW4pNLlhNTkCfHzAVBReH9diLvGRem5+R9g2FzA8ZGN954O5Q"
crossorigin="anonymous"></script>
<link href="https://cdn.jsdelivr.net/npm/bootstrap@5.3.7/dist/css/bootstrap.min.css" rel="stylesheet"
integrity="sha384-LN+7fdVzj6u52u30Kp6M/trliBMCMKTyK833zpbD+pXdCLuTusPj697FH4R/5mcr" crossorigin="anonymous">
<!-- Bootstrap Icons -->
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/bootstrap-icons@1.13.1/font/bootstrap-icons.min.css"
integrity="sha384-CK2SzKma4jA5H/MXDUU7i1TqZlCFaD4T01vtyDFvPlD97JQyS+IsSh1nI2EFbpyk"
crossorigin="anonymous">
<!-- https://www.daterangepicker.com/ -->
<script type="text/javascript" src="https://cdn.jsdelivr.net/momentjs/latest/moment.min.js"></script>
<script type="text/javascript" src="https://cdn.jsdelivr.net/npm/daterangepicker/daterangepicker.min.js"></script>
<link rel="stylesheet" type="text/css" href="https://cdn.jsdelivr.net/npm/daterangepicker/daterangepicker.css"/>
<!-- plotly -->
<script src="https://cdn.plot.ly/plotly-2.12.1.min.js"></script>- In the
<body>, add the row<div>that will hold the component:
<div id="forecastViz_row" class="row"></div>- In the
<body>, load and use the predtimechart module:
<script type="module">
// import the module's entry point (the `App` object)
import App from 'https://cdn.jsdelivr.net/gh/reichlab/predtimechart@2.0.9/dist/predtimechart.js';
// set up _fetchData and options
function _fetchData(isForecast, targetKey, taskIDs, referenceDate) { ... }
const options = {...};
// initialize the component: componentDiv, _fetchData, isIndicateRedraw, options
App.initialize('forecastViz_row', _fetchData, false, options);
</script>The component is accessed via the App object, and is initialized via the App.initialize() function. After that, everything else is taken care of by the app.
Predtimechart has adopted a simplified version of the modeling tasks concept defined in Modeling Hub task ID variables, and specifically the idea of task ID variables. These variables are used in these ways (details follow):
- Initializing the application's UI: The
task_idsobject passed to App.initialize() via the containing options object (see the "Options object" section below) configures the dropdown menus in the options section of the UI. Specifically, each task ID gets its own dropdown, positioned between the fixed Outcome and Interval dropdowns. For example, if the options object'stask_idsspecifies two task IDs ("scenario_id" and "location") then there will be two dropdowns between Outcome and Interval: "scenario_id" and "location". Those dropdowns' values will contain the values passed in thetask_idsobject. - Initializing the dropdown default values: Predtimechart uses the options object's
initial_task_idsto select the initial values that the user sees. - Args to the
_fetchDatafunction: When the user takes an action that requires obtaining data, predtimechart will pass the currently-selected values in the above dropdowns to the_fetchDatafunction.
App.initialize(componentDiv, _fetchData, isIndicateRedraw, options) takes these args:
componentDiv:idof the empty<div>to place the component into._fetchData: function to retrieve truth and forecast data. It is called whenever the plot needs updating. See the "fetchData data format" section for details. It takes these args:isForecast:booleanindicating type of data to retrieve.truemeans retrieve forecast data andfalsemeans get truth data.targetKey:stringnaming the target of interest. Must be one of the values in the options object'starget_variablesvalue.taskIDs:objectspecifying which modeling task to retrieve data for (see task ID variables above). Must be consistent with theoptionsobject'stask_idsvalue (see the "Options object" section for details).referenceDate: "" reference date "". Must be one of the values in the options object'savailable_as_ofsvalue.
isIndicateRedraw:booleanthat controls whether the plot area should be grayed out while waiting for data requests. Useful for applications that have a noticeable delay when fetching data.options:objectthat contains initialization data. See the "Options object" section for details.
The component is initialized by a JavaScript object with the following keys and values. See the "Example options object" for a detailed example. See src/schema.json for the options object's JSON Schema.
available_as_ofs:objectthat mapstarget_variablesvalueto anarrayof dates in 'YYYY-MM-DD' format that have truth and/or forecasts availablecurrent_date:available_as_ofsvaluekey to use for the initial plotdisclaimer:stringproviding any important information users should knowinitial_as_of:stringspecifying the initial date from 'available_as_ofs' (in 'YYYY-MM-DD' format) to use for the initially-selected as_of dateinitial_checked_models:modelsvalue(s) to use for the initial plotinitial_interval:intervalsvalue to use for the initial plotinitial_target_var:target_variablesvaluekey to use for the initial plotinitial_task_ids: anobjectto use for the initial plot. Its format is identical to_fetchData()'staskIDsarg above.initial_xaxis_range:arrayof two dates in 'YYYY-MM-DD' format that specify the initial xaxis range to use. To not initialize the range, passnullfor its valueinitial_yaxis_range:arrayof two values (format depends on outcome variable) that specify the initial yaxis range to use. To not initialize the range, passnullfor its valueintervals:arrayof one or more prediction interval widths to offer in the Interval dropdown, each a string of the form'<integer>%'from'0%'to'99%'(no zero padding, and'100%'is not accepted).'50%','80%', and'95%'are plotted as shaded bands, built from theq0.25/q0.75,q0.1/q0.9, andq0.025/q0.975forecast data keys respectively.'0%'plots the median line alone, as does any other width, since we have no quantile keys to map it to. A width is also skipped for any model whose forecast data is missing its two backing quantiles — so a hub that doesn't submitq0.1/q0.9should simply omit'80%'here.models:arrayof model names (strings) that provide datamodel_urls:objectwhere the keys are the model names inmodels(strings) and the values are URLs to pages showing model information (strings)target_variables:arrayofobjects defining the target variables in the data. Each object contains three keys:- 'value': used as the main value that's passed around for the target
- 'text': human-readable text
- 'plot_text': plot text (purpose: TBD)
task_ids:objectdefining the tasks in the data as described in_fetchData'staskIDsarg above. Likeavailable_as_ofs, the keys must matchtarget_variablesvalue. Each of those is an object that contains astringkey for each task ID variable, the value of which is anarrayofobjects defining possible values. The keys should consist of only ASCII letters, digits,_, and-, and should start with a letter. (Note that, for display, the IDs are split on_and-and the title-cased.) The objects have two keys:value: used as the main value that's passed around for the task IDtext: human-readable text
Here's a real-world example from the COVID-19 Forecast Hub project. Only the first two items in the lists are shown.
{
"available_as_ofs": {
"day_ahead_cumulative_deaths": [
"2020-03-15",
"2020-03-22",
"..."
],
"day_ahead_incident_deaths": [
"2020-03-15",
"2020-03-22",
"..."
],
"...": "..."
},
"current_date": "2022-10-22",
"disclaimer": "Most forecasts have failed to reliably predict rapid changes in the trends of reported cases and hospitalizations...",
"initial_as_of": "2022-10-12",
"initial_checked_models": [
"COVIDhub-baseline",
"COVIDhub-ensemble"
],
"initial_interval": "95%",
"initial_target_var": "week_ahead_incident_deaths",
"initial_task_ids": {"unit": "48"},
"initial_xaxis_range": null,
"initial_yaxis_range": null,
"intervals": ["0%", "50%", "80%", "95%"],
"models": [
"COVIDhub-baseline",
"COVIDhub-ensemble",
"..."
],
"model_urls": {
"COVIDhub-baseline": "https://github.com/CDCgov/covid19-forecast-hub/blob/main/model-metadata/CovidHub-baseline.yaml",
"COVIDhub-ensemble": "https://github.com/CDCgov/covid19-forecast-hub/blob/main/model-metadata/CovidHub-ensemble.yaml"
},
"target_variables": [
{
"value": "day_ahead_cumulative_deaths",
"text": "day ahead cumulative deaths",
"plot_text": "day ahead cumulative deaths"
},
{
"value": "day_ahead_incident_deaths",
"text": "day ahead incident deaths",
"plot_text": "day ahead incident deaths"
},
"..."
],
"task_ids": {
"week_ahead_incident_deaths": {
"unit": [
{"value": "48", "text": "Texas"},
{"value": "US", "text": "US"},
"..."
]
}
}
}As described above, the fetchData(isForecast, targetKey, taskIDs, referenceDate) function passed to App.initialize() is responsible for returning truth and forecast data as directed by the isForecast arg. It uses the other three args to retrieve and return the requested data. The data is in the following formats.
Truth data is represented as an object with x/y pairs represented as columns, where x=date and y=truth_value. The dates must correspond to those in the options object's available_as_ofs. For example:
{
"date": ["2020-03-15", "2020-03-22", "..."],
"y": [0, 15, "..."]
}Forecast data is an object with one entry for each model in the options object's models, each of which is in turn an object with entries for target end date of the forecast and the quantiles required to display point predictions and prediction intervals. q0.5 gives the point prediction, and each interval width in the options object's intervals is drawn from its two backing quantiles as documented there. The q0.1 and q0.9 entries backing the '80%' interval are optional; a model that omits them simply gets no '80%' band. For example:
{
"UChicagoCHATTOPADHYAY-UnIT": {
"target_end_date": ["2021-09-11", "2021-09-18"],
"q0.025": [1150165.71, 1176055.78],
"q0.1": [1150793.36, 1177824.19],
"q0.25": [1151044.42, 1178626.67],
"q0.5": [1151438.21, 1179605.9],
"q0.75": [1152121.55, 1180758.16],
"q0.9": [1152583.94, 1181790.27],
"q0.975": [1152907.55, 1182505.14]
},
"USC-SI_kJalpha": {
"target_end_date": ["2021-09-11", "2021-09-18"],
"q0.025": [941239.7761, 775112.557],
"q0.1": [988431.0294, 856894.311],
"q0.25": [1010616.1863, 896160.705],
"q0.5": [1149400.162, 1137280.4614],
"q0.75": [1313447.0159, 1461013.716],
"q0.9": [1398215.4382, 1637168.583],
"q0.975": [1456851.692, 1771312.0932]
},
"...": "..."
}Following is how to do development-related activities. You must first install the required Node.js packages via npm install --save-dev.
We use QUnit for our unit tests. To run the tests, execute the package.json test script: npm run test. You should see output at the bottom like this:
...
# pass 22
# skip 0
# todo 0
# fail 0We've included src/index.html as a simple example of the app in action. The file hard-codes truth and forecast data, and has ata for only one referenceDate, but can be useful during development. To use it, follow the below packaging step and then serve dist/index.html from your development environment via these commands:
Note: You can't open the file directly in your browser due to CORS restrictions (e.g., "CORS request not http" in Firefox).
cd <this_repo>/dist
python3 -m http.server --cgi 8080
# visit: http://127.0.0.1:8080We use Ajv to validate App.initialize()'s options object. More specifically we use a standalone validation function generated from the schema, which is saved to schema-validator.cjs. This file must be regenerated whenever the schema file /src/schema.json changes. To do so, execute the package.json ajv_compile script via npm run ajv_compile.
We use webpack to package up all dependencies into a single dist/predtimechart.bundle.js file for end users. To do so, execute the package.json build script via npm run build, which will update all files in dist/.
TBC
To jump to a specific "as of" date (i.e., reference date), use the calendar icon in the plot's modebar, which is located in the top right of the plot. This strip of gray icons is shown by hovering over the chart. (See the below screenshot for an example.) Clicking the icon will pop up a date picker where you can navigate to a date and then click "Apply" to set it as the current "as of" date. Note that the year select box above calendar is constrained to the current target's data date range. Because not every calendar data has a corresponding "as of" date, picking a date that corresponds to the currently-set "as of" date will not update the display.
