decouple grey region in time-chart from timezero

[nickreich]

Currently, I believe, the grey shaded region in a time-chart starts at the timezero. however, we would like this to represent not the origin of the forecasts (that info is already captured in the transition from observed to forecasted points) but rather the data-version-date or the time at which the forecast was made. This latter piece of information is not currently represented in the visualization when looking back retrospectively. After a conversation with @matthewcornell about this, we think that a fix would entail including an optional date field in the predictions array of data passed to the TimeChart. If this date is present, it would be indicating this "data-version-date" or the date at which a forecast was made, and the grey region should extend to that point rather than the timePoint index (which could remain the default, if the d-v-d is not present.

So the format might look something like this below (with data-version-date field added.

       "predictions": [
          {
            "data-version-date": "YYYYMMDD",
            "series": [
              {
                "point": 1.30017860564934
              },
              {
                "point": 1.40042830976304
              },
              {
                "point": 1.5016975272185
              },
              {
                "point": 1.50294394685125
              }
            ]

[lepisma]

Can we change this a little bit to accommodate cases like 82 (from zoltar)? When we pass in data-version-date, we can use a arbitrary steps (including negative values). An example prediction data will now look like the following:

       "predictions": [
          {
            "data-version-date": "YYYYMMDD",
            "series": [
              {
                "offset": -1,
                "point": 1.30017860564934
              },
              {
                "offset": 0,
                "point": 1.40042830976304
              },
              {
                "offset": 1,
                "point": 1.5016975272185
              },
              {
                "offset": 2,
                "point": 1.50294394685125
              }
            ]

Offsets are to be added to the data-version-date before plotting that specific point.

[lepisma]

Also, in case of no data-version-date offset values (if any) will be ignored so that the solution stays backward compatible.

[lepisma]

Also, @matthewcornell can we keep the value of data-version-date an integer (index in the timePoints array)? I was thinking to keep 'date' values in a single array (timePoints) and everywhere else use indices.

[lepisma]

We now allow dataVersionTime (an index mapping to time in timePoints array) in predictions. The gray region now follows the dataVersionTime if provided, otherwise it follows the regular indices.

Its in a separate branch (feature/time-rect-data-version-time) as of now. Will merge when we settle the formats and also how we handle arbitrary offsets.

Here is the format as of now:

       "predictions": [
          {
            "dataVersionTime": 1, // index maps to the main timePoints array
            "series": [
              {
                "offset": -1, // offsets are not getting used right now
                "point": 1.30017860564934
              },
              {
                "offset": 0,
                "point": 1.40042830976304
              },
              {
                "offset": 1,
                "point": 1.5016975272185
              },
              {
                "offset": 2,
                "point": 1.50294394685125
              }
            ]

[nickreich]

Stating definition of some of our terms here, for clarity:

• data-version-date is the date at which a forecast is made, or date at which data is queried to make a certain forecast.
• timezero is the date relative to which targets are defined.

@lepisma My understanding from the documentation is that the TimeChart expects a set of timePoints. In the currently implemented version (not the new dev branch), we assume that each timePoint is a timezero with 1-step, 2-step, ... k-step ahead forecasts from that timePoint being represented with the "predictions" array. I don't think there is a problem with this structure, per se, and don't totally see the value (and possible see more room for confusion) in adding the offsets. The user can do the calculations needed offline to ensure that the timePoints passed to d3-foresight align with the times just before each 1-step-ahead forecast.

In my mind, the new dataVersionTime should be kept, but only for determining where the gray shaded region is needed.

[lepisma]

Reopening. Lets close once we try it.

[lepisma]

@matthewcornell try 0.9.4. Structure is now this:

       "predictions": [
          {
            "dataVersionTime": 1, // index maps to the main timePoints array
            "series": [
              {
                "point": 1.30017860564934
              },
              {
                "point": 1.40042830976304
              },
              {
                "point": 1.5016975272185
              },
              {
                "point": 1.50294394685125
              }
            ]

[matthewcornell]

I'm confused. The timePoints array is always time zeros, correct? Having dataVersionTime index into them means timePoints would have to include data version dates as well, but that doesn't make sense because predictions is synchronized in order. I think that's why @nickreich and I had an actual date for data-version-date instead of an index. ??

[nickreich]

@matthewcornell Good point. The dataVersionTime should be in a date format, not an index.

[matthewcornell]

Alternatively, if we wanted to stick with indexes like @lepisma suggested, we could have a second optional array similar to timePoints: dataVersionDates, and index into that.

[lepisma]

Oh, I thought these two dates are from the same discrete set. No problem, I will make it read the time (in whatever format we are accepting everywhere else).

[nickreich]

Perfect. And then to be clear, does this dataVersionTime then define the boundary of the grey shaded region shown for that particular series?

[lepisma]

Yes, so here is what it would look like

• The gray region shows the data version time (week 49 here but could be something non discrete).
• Time zero is week 47
• Our predictions start from week 48 (1 ahead), then 49 (2 ahead) ...

Am I getting this right?

[nickreich]

yes, looks awesome.

[nickreich]

do we need an explanation somewhere for the grey shaded region? either in the intro or as a title (as we have for the "current time" bar? not sure what text we would include there. "data as of" or "data version"?

[lepisma]

Fix for allowing timestring is up in v0.9.9 (https://unpkg.com/[email protected]/dist/d3-foresight.min.js).

We will definitely be needing an explanation. I feel data as of/data used feels more intuitive as compared to data version. We can put it like the TODAY text on the today line.

Another issue is related to the observed line. Its not getting used in zoltar but its meaning changes a little bit when we allow separating dataVersionTime. What feels reasonable is to do the following:

• Let the discrete time zero unit (weeks for example) be u.
• Suppose we are at timezero t u and dataVersionTime is t u + few hours (this might not align in terms of u units).

1. Show predictions in discrete jumps of time zeros from t + 1 u to whatever length we do predictions for.
2. Show the gray region covering time t u + few hours.
3. Show observed line in discrete jumps of time zeros from 0 u to tp u where tp is the largest u less than t u + few hours.

[matthewcornell]

@lepisma Thanks for that; it's looking good. I uploaded a change that outputs a dataVersionTime if a time zero has a data version date. You can see the result here: https://reichlab-forecast-repository.herokuapp.com/project/3/visualizations .

Question (see attached screen shot): Here I've clicked on 44 which caused the gray line to show that time zero's dvd around 46. I'm hovering over the 1 step ahead point around 45, which is where the darker gray vertical line is that tracks the mouse. However, Zoltar does not have the gray hashed area that Abhinav's screen shot above shows (it's got the blue and red dots above 47). Without those, I don't see a visual reference the the current time zero that was last clicked. Is there a way to show that in this case?

Question: I expected dataVersionTime to be named dataVersionDate to reflect its being a date in format (YYYYMMDD), and not a time one. What was the reasoning for using 'Time' instead of 'Date'?

[lepisma]

1. Hmm, that was not a problem earlier since we were using the gray region (data version date) as an indicator for the time zero. Now we need to have a separate indicators for both times. The most non intrusive way would be to make the mouse-hover vertical line stick to the time zero when the mouse goes outside the chart and follow the mouse (like it already does) when we are hovering in the chart.

2. I thought to make time units independent of the granularity (week, month, day) and so named stuff using time suffix (we also accept fuller strings like YYYYMMDDHHMMSS since we convert them anyway to a full date and time object). Should we change it? Assuming that we are the only consumers, and that we don't take time of the day into account, its a reasonable thing to do (changing to dataVersionDate).

[lepisma]

For 1, we can also add another vertical line instead of overloading the mouse hover line.

[matthewcornell]

1: Which is the easiest to code? Let's try that 👍 2: OK, let's not change it.

[lepisma]

Try v0.9.10 (https://unpkg.com/[email protected]/dist/d3-foresight.min.js). I added the following:

1. Descriptive text for the shaded region (says data as of; we can change/hide this in simpler situations)
2. Another vertical line showing timezero (with a descriptive text). This is only visible when there are different dataVersionTimes, otherwise we show the simpler ui (à la reichlab.io/flusight) with gray region only.

[matthewcornell]

Sweet! I uploaded the code to http://reichlab-forecast-repository.herokuapp.com/ . Nice work.

[nickreich]

This all looks great! Thanks for the iterations on it. One additional comment is that the "timezero" line might be a bit redundant for certain users here. As in, a more layperson consumer of this may not care what the timezero is, since it's fairly obvious from the forecasts themselves. So if it's an easy add in a future version maybe we could toggle on/off the showing of timezero line? In general, I think the shaded grey region up to data as of is the most useful feature to show here on this graph.

[lepisma]

Did you mean a toggle in the UI (the user might do this) or a toggle in the config (the programmer, while plotting will do)?

EDIT: We already don't show the timezero line in case there is no difference in timezero and dataversionTime (like in flusight). This might get rid of few cases where people (not knowing what timezero is) get confused.

[nickreich]

I was thinking toggle in the config for the developer.

[lepisma]

Will be doing this sometime this week.

[lepisma]

Done in 0.10.1. Documentation here.