Nat dogfooding notes

[nmdefries]

• Documentation website
  • [x] ~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(
    • [x] "signal discovery" how-to should be more fleshed out and NOT listed as advanced or experimental. Potentially better as a stand-alone vignette
    • [x] Can copy over some covidcast documentation, for both signal discovery and other
    • [x] geo discovery/how to find geo ids (basic version done)
    • [x] how to use metadata
    • [x] versioned data (separate vignette)
    • [x] getting the call obj shouldn't be part of "getting started"
    • [x] 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
  • [x] 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
  • [ ] #238
    • [x] 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)
  • [x] fetch description typo. "only support will return"
  • [x] ~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
  • [x] 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 https://github.com/cmu-delphi/epidatr/issues/233
  • [ ] ~what locations are allowed for pub_flusurv?~ moved to https://github.com/cmu-delphi/epidatr/issues/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 https://github.com/cmu-delphi/epidatr/issues/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 https://github.com/cmu-delphi/epidatr/issues/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 https://github.com/cmu-delphi/epidatr/issues/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 https://github.com/cmu-delphi/delphi-epidata/issues/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 https://github.com/cmu-delphi/epidatr/issues/233
  • [ ] ~hard to tell that pub_nidss_flu has non-US data, has Taiwanese data, and what the regions to request are~ moved to https://github.com/cmu-delphi/epidatr/issues/233
• Endpoint standardization (moved to https://github.com/cmu-delphi/epidatr/issues/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
  • [x] All endpoints should accept wildcard for dates
    • [x] 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
  • [x] issues doesn't support a list of dates
  • [x] pub_covid_hosp_facility says it takes weeks, but actually takes days corresponding to weeks
• Naming (moved to https://github.com/cmu-delphi/epidatr/issues/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
  • [x] 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
  • [x] Endpoints should use defaults so that users are able to get some data specifying no or minimal args. This mirrors covidcast behavior.
    • [x] endpoints should default to providing data for all dates
    • [x] geo_type should have no default
  • [x] 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?
  • [ ] #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
  • [x] epidatr doesn't offer plotting (right?). Suggest alternatives (hubvis?), especially for more complex plots like choropleths
  • [ ] #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.