Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

clarify documentation about fetchData function #44

Open
elray1 opened this issue Nov 22, 2024 · 2 comments
Open

clarify documentation about fetchData function #44

elray1 opened this issue Nov 22, 2024 · 2 comments

Comments

@elray1
Copy link

elray1 commented Nov 22, 2024

  • Function arguments are described in the readme under a section titled App.initialize() args; it could be helpful to repeat them again below in the fetchData data format section
  • In that section, we could add language explaining that for target data, the expected behavior is to return a version of the target data that was available as of the specified referenceDate
@zkamvar
Copy link
Member

zkamvar commented Nov 22, 2024

It would also be good to reword it to say "target time series data" instead of "truth data".

@zkamvar
Copy link
Member

zkamvar commented Nov 22, 2024

Your suggestions would definitely help.

I think one of the biggest problems that I encountered was that I didn't have any clear examples beyond the example in predtimechart/src/index.html. Without a narrative behind this example, I could only see that the updated target data was simply adding dates, but nothing else changed:

// https://zoltardata.com/api/project/316/viz-data/?is_forecast=false&target_key=week_ahead_incident_deaths&unit_abbrev=48&reference_date=2022-01-22 :
'2022-01-22': {
"date": ["2021-12-18", "2021-12-25", "2022-01-01", "2022-01-08", "2022-01-15", "2022-01-22"],
"y": [478.0, 266.0, 422.0, 717.0, 623.0, 971.0]
},
// https://zoltardata.com/api/project/316/viz-data/?is_forecast=false&target_key=week_ahead_incident_deaths&unit_abbrev=48&reference_date=2022-01-29 :
'2022-01-29': {
"date": ["2021-12-18", "2021-12-25", "2022-01-01", "2022-01-08", "2022-01-15", "2022-01-22", "2022-01-29"],
"y": [478.0, 266.0, 422.0, 717.0, 623.0, 971.0, 1212.0]
},

Since the target data in the flusight hub was a single file, I had assumed that we were just appending new data and not amending existing data (which in hindsight was a foolish assumption, because I even designed a figure that shows that scenario) and just went with it.

Most of the documentation that exists is low-level reference documentation, but for someone without much context to go from, it's not clear where to start or what features are important or auxiliary. A more explanatory form of documentation would have been helpful in this situation so that it was clear where the data were coming from and what the context was for the different modes of visualization.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

No branches or pull requests

2 participants