Nat dogfooding notes

[nmdefries]

• Documentation website
  • the epidatr vignette isn't up to date about ways to set api keys -- it doesn't mention the set_api_key fn. code is up to date, but site needs to be released (looks like releases not done automatically(
    • "signal discovery" how-to should be more fleshed out and NOT listed as advanced or experimental. Potentially better as a stand-alone vignette
    • Can copy over some covidcast documentation, for both signal discovery and other
    • geo discovery/how to find geo ids (basic version done)
    • how to use metadata
    • versioned data (separate vignette)
    • getting the call obj shouldn't be part of "getting started"
    • And then it just has a huge list of endpoints?? doesn't seem super useful since it doesn't actually describe them, just link to the online docs and provide the same example from each fn doc page
  • landing page looks more like "getting started". Should focus more on what the package is/provides, how it differs from covidcast, setup, links to other resources, good vignettes to start with, etc
  • Reference page should have more info about the different fn sections #238
    • private endpoints should be at the bottom (or maybe even hidden/collapsed by default) since they're not relevant to most users.
• Function documentation (most of these are really issues with the Epidata doc website)
  • fetch description typo. "only support will return"
  • timeset doc page doesn't link to any of the formats it mentions. Esp looking at epiweek and epirange. And then asking for docs on epiweek sends me to a lubridate page. Is there even an EpiWeek fn/class available? Fixed in a previous doc update
  • docs for covidcast_epidata refer to covidcast fn that no longer exists. "These objects can be used directly to fetch data, without requiring us to use the covidcast() function."
  • unclear what pub_covid_hosp_facility signal cols represent. There are covariance columns (names end with "_cov")?? moved to Better describe meaning/context of endpoints in documentation #233
  • what locations are allowed for pub_flusurv? moved to Better describe meaning/context of endpoints in documentation #233
  • can't tell what pub_meta returns. What API? How is it different than pub_covidcast_meta? Docs and blurb in avail_endpoints need more fleshing out moved to Better describe meaning/context of endpoints in documentation #233
  • pub_ecdc_ili not clear what are valid region names. Example uses a (lowercase and unabbreviated) country name. online docs don't list allowed regions either, and is basically a stub. moved to Better describe meaning/context of endpoints in documentation #233
  • pub_kcdc_ili not clear what are valid region names. Example uses a (uppercase and abbreviated) acronym -- unclear what it means. online docs don't list allowed regions either, and is basically a stub. Nowhere does it say what the KCDC is or link to any additional info moved to Better describe meaning/context of endpoints in documentation #233
  • when i try region = "taiwan" with both pub_ecdc_ili and pub_kcdc_ili, I get epidata warning: no results and an empty tibble. But I'm pretty sure that this region is invalid. I'd like an error that it's invalid, with more info about how to provide a valid region name. opened issue Error when API request is made for an invalid region? delphi-epidata#1365
  • Private endpoints need more info about authorization required. Can non-Delphi users get access to the private endpoints? Why are they private? moved to Better describe meaning/context of endpoints in documentation #233
  • hard to tell that pub_nidss_flu has non-US data, has Taiwanese data, and what the regions to request are moved to Better describe meaning/context of endpoints in documentation #233
• Endpoint standardization (moved to Standardize endpoint arg names and formats #242)
  • Integer-type geo codes (e.g. fips) should be able to be passed as integers to geo_values, like dates can
  • make pub_delphi support a range of epiweeks; currently only takes one epiweek date at a time. This could also be changed in delphi-epidata
  • All endpoints should accept wildcard for dates
    • Want a fn that converts any "*" passed for dates into a long date period
  • don't like that endpoints don't all have the same args (although I can see why). Might be nice to unify them more, though. e.g. pub_ecdc_ili uses epiweeks when it could just use time_values
  • issues doesn't support a list of dates
  • pub_covid_hosp_facility says it takes weeks, but actually takes days corresponding to weeks
• Naming (moved to Make endpoint names more descriptive #241)
  • pub_covid_hosp_facility_lookup arg fips_code name doesn't parallel arg zip. Neither should have "code" in their names.
  • pub_gft name too short and not descriptive. Ditto pvt_ght, and pvt_cdc and pub_delphi (although for the last two it's more that "CDC" and "Delphi" are very broad)
  • name covidcast_epidata is not informative. What about "covidcast_signal_explorer"?
• Other
  • In message "source, signals, time_type, geo_type, time_values, and geo_value are all required", geo_value should be plural.
    • Also it would be nice if the message said specifically what arg/s you were missing
  • Data problem: lots of -999999 in pub_covid_hosp_facility total_adult_patients_hospitalized_confirmed_covid_7_day_avg field, but also has NAs. Is resolving this within our purview? Or are we just re-reporting this as-is? moved to delphi-epidata
  • Endpoints should use defaults so that users are able to get some data specifying no or minimal args. This mirrors covidcast behavior.
    • endpoints should default to providing data for all dates
    • geo_type should have no default
  • pub_covid_hosp_facility (and presumably all other endpoints) forces me to specify a time range. Why not just default to giving me data for all dates?
  • Render markdown in covidcast_epidata output #239

[1] "Information about hospital admissions, provided to us by health system partners. Using inpatient claim counts, we estimate the percentage of new hospital admissions with a COVID-associated diagnosis code in a given location, on a given day.\n\nSee also our [Health & Human Services](https://cmu-delphi.github.io/delphi-epidata/api/covidcast-signals/hhs.html\) data source for official COVID hospitalization reporting from the US Department of Health & Human Services."

• Extensions
  • epidatr doesn't offer plotting (right?). Suggest alternatives (hubvis?), especially for more complex plots like choropleths
  • Include geo data for geo/geo id discovery and to support geo_value "*"? #240

[brookslogan]

A lot of great points! Couple of notes

unclear what pub_covid_hosp_facility signal cols represent. There are covariance columns (names end with "_cov")??

_cov = "coverage", not "covariance". And "coverage" in some sense of % facilities reporting the corresponding non-_cov column or something like that. Would need to read upstream docs. I think they do just use that _cov naming upstream though, unfortunate.

Should endpoints use defaults so that users are able to get some data? This mirrors covidcast behavior.

No geo_type = "county" default please. The wait [to be able to do something again after realizing one's mistake of not specifying another geo_type desired] might be shorter with epidatr but I expect there's still a wait. (I'd also vote for no geo_type default at all. geo_values = "*" default maybe...)

[Another argument against geo_type = "county" default: this could cause mixups between megacounties and state-level data.]

[nmdefries]

Remaining tasks moved to their own issues.