I think my internet flaked out, so I got a connection time out message. Might be nice to catch timeout errors, esp. if they happen when the API is down for maintenance / data update.

@watronfire noticed a potential connection issue when trying to run the package through rpy2

Function call: countries <- getAdmn0()

Vignette .Rmd would have to be moved into the vignettes/ directory.
In addition, would be nice to edit the DESCRIPTION file to include a link to the vignette.

Add a title to plotPrevalenceByLocation(pangolin_lineage = "P.1", location = "Brazil"):

Personally, I also prefer percentage over proportion, but it's not a big deal either way.

plotPrevalenceByLocation(pangolin_lineage = "P.1", location = "Brazil") +
  ggtitle("Prevalence of P.1 in Brazil") +
  scale_y_continuous(labels = scales::percent, name="percentage")

from @flaneuse : Add introduction to the Github Readme and the vignette to explain what the data is, where it comes from, etc. More context about what the package can do. Should also link to the data sources (outbreak.info/sources) and the api documentation (api.outbreak.info)

Functions like getAdmn2ByCounty take a while to load the data. Showing a progress bar with the number of items retrieved would improve user experience.

Call: county_df=getAdmn2ByCountry()

• The counter says things like 144 records retrieved; do you actually mean 14,400 records? Would suggest changing language to either something like "query" or multiplying by 1000.
• It'd be helpful to grab the number of results so you have an idea of how far you are into the function call (e.g. 14,400 out of 68,000)
• Would be nice to add a newline after "X records are retrieved". When there's an error, they get pasted together.
• Might also be useful to display the estimated time remaining in the function. see progress package: https://dplyr.tidyverse.org/reference/progress_estimated.html

From @flaneuse : searchLocations would be MUCH more useful if there was a geographic synonym lookup function. If I try to lookup “USA” right now, I get no results. We could do this either by a gazetteer approach (store a list of synonyms for each location), or we could use a package that calls Google’s Geocode API to find the lat/lon of the location and let the user select what they mean.

We would need an api_key for google geocoding api.

Feedback from @flaneuse : It would be something like getEpiData(location_id, location_name, date, most_recent, admin_level, fields, sort, size), where all those fields are optional. getData() would return ALL the data. The advantage of this approach is that you now have one function which all the others can rely on, so if anything ever changes, like the API URL, you only have to change it in one place. You can also then have one place to do all the transformations you need. This function would also expose a lot more functionality to the user like sorting, specifying size, fields to return, etc. It’d be really cool too if you could specify date ranges (let us know if you need help constructing that ES query).

getAdmn2ByState(“California”)
-->

1] "Retrieving data..."
 1 records retrieved

Error in rbind_pages(results) : 
  all(vapply(pages, is.data.frame, logical(1))) is not TRUE

p <- plotAllLineagesByLocation(location = "United States", other_threshold = 0.03, nday_threshold = 5, ndays = 60)
p <- p + scale_fill_brewer(palette="Paired")

The ColorBrewer "Paired" scheme wouldn't be my first choice for this plot. The paired-ness of the colors mean that users subconsciously associate the two similar colors together, when B.1.1.519 and B.1.1.7 are completely unrelated.

Only the Epi vignette is listed.

e.g. https://outbreak-info.github.io/R-outbreak-info/reference/getMutationsByLineage.html

• Be explicit that installation occurs in R script and not command line (this seems intuitive, but doesn't hurt to state)
• Be more descriptive with purpose and function of R package directly, rather than relying on the user to click on the vignette (which does a good job of explaining functions themselves, but isn't entirely descriptive itself). For example, provide a few of the package uses directly.
• License? Credits? I know we did an overview on how to approach a README (Mar 3, 2020) that Ginger facilitating, and there was a GoogleDoc breakdown

@gkarthik : maybe add to API the total worldwide instances of S:N501Y and percentage of all sequences for a given mutation? could be useful in cases where there are multiple nucleotide substitutions for a given amino acid change to figure out which is the more frequent change.

searchLocations(c("California", "Florida", "Texas"), admin_level=1) which returns "California" "Florida" "Texas" seems not particularly useful.

ditch_the_axes <- theme(
  axis.text = element_blank(),
  axis.line = element_blank(),
  axis.ticks = element_blank(),
  panel.border = element_blank(),
  panel.grid = element_blank(),
  axis.title = element_blank()
)

p <- ggplot() + geom_polygon(data = us_df, aes(x, y, group=group, fill=proportion), color="gray25", size=0.3) + scale_fill_gradient(low = "lemonchiffon", high = "lightseagreen", name = "Cumulative prevalence \nof B.1.1.7", labels = scales::percent) + ditch_the_axes + coord_fixed(1.05)
show(p)

Suggest replacing ditch_the_axes with the in-built ggplot::theme_void() function

Add context, link to the outbreak.info report, etc.: https://outbreak-info.github.io/R-outbreak-info/lineagevignette.html

See also #32

Suggestions for "Characteristic S-gene mutations in common lineages" in https://outbreak-info.github.io/R-outbreak-info/locationvignette.html:

• The heatmap is wrong; you need to grab all the mutations which have at least 75% prevalence in any of the lineages. I do this by getting all mutations (getMutationsByLineage(.x, frequency=0)) within the lineage_list, then finding all unique mutations where they're > 0.75 in any lineage, and then filtering the mutations in df_ll to only be those mutations.
• If you want a dplyr version (I'm a big advocate because I find the code easier to read): lineage_list <- lineage_df %>% filter(lineage != "other") %>% pull(lineage) %>% unique()
• df_ll <- subset(df_ll, gene == "S") can also be dplyr-ized with filter
• add coord_equal to the ggplot so the chiclets are square rather than rectangular.
• add a border around the tiles
• add a ggtitle
• To mimic the outbreak palette, I'm using RdPu from ColorBrewer
• I'd probably change the theme to remove the distracting gridlines, etc.

In "Tracked variants of concern in the United States" (https://outbreak-info.github.io/R-outbreak-info/locationvignette.html), would suggest using a more descriptive variable name than out. I use df all the time, so i'm not one to talk, but out seems just a little too divorced from what it's trying to represent.

Add context, link to the outbreak.info report, etc.: https://outbreak-info.github.io/R-outbreak-info/locationvignette.html

getByAdmnLevel(-1)
Error in open.connection(con, "rb") : HTTP error 400.

Probably need to enquote admin_level:"-1"?

Create a generic function to get all region with the specified admin_level. This will be useful to plot world map.

getByAdminLevel(admin_level = 0/1/2/1.5)

For instance: plotAllLineagesByLocation(location = "United States", other_threshold = 0.03, nday_threshold = 5, ndays = 60) takes a few seconds to load. Add feedback on how much longer the function will take to return data.

printAPIFields()

Add this function to Rmarkdown as well.

Reasoning and execution:
https://stevenmortimer.com/5-steps-to-change-github-default-branch-from-master-to-main/

getEpiData(name="United States of America", date=2020-07-01, mostRecent=T) example from the help documentiation is broken.

1. Need to translate mostRecent argument TRUE / FALSE into ES-compatible representations of booleans (true, false)
2. Fixing that string leads to an rbind err:

getEpiData(name="United States of America", date=2020-07-01, mostRecent='true')

[1] "Retrieving data..."
 1 records retrieved

Error in rbind_pages(results) : 
  all(vapply(pages, is.data.frame, logical(1))) is not TRUE

For getAdmn2ByState, getCountryByRegion, getAdmn1ByCountry, etc. provide another example where you supply the function with a list of location names rather than a string.

When you call functions like getAdmn0() or getAdmn2ByCountry() the function is slooooooooow since it has to make a bunch of calls and returns a lot of data.

Would be nice to offer the users the ability to limit the query to a smaller subset of the data to help make it easier to return data faster. Potential options could include narrowing by date range, mostRecent, returning only a subset of fields...

Might also be worth double-checking that the function is as fast as possible. You're probably API-limited, but if it could be faster, that'd be nice. (low priority)

https://outbreak-info.github.io/R-outbreak-info/

and/or

https://outbreak-info.github.io/

should point to some sort of basic homepage, ideally listing all the vignettes and maybe the functions. the tidyverse format is nice: installation instructions, usage, features, authors, etc: https://dplyr.tidyverse.org/

Should also link to outbreak.info and the API.

Pre-release testing

From https://outbreak-info.github.io/R-outbreak-info/outbreakvignette.html, using version 0.2.0 built on 3 November 2020:

df=getLocationData(c("Texas", "Brazil", "San Diego County"))

-->

Error in getLocationData(c("Texas", "Brazil", "San Diego County")) : 
  could not find function "getLocationData"

I'm not in love with the call to coord_fixed(1.05) in the Lineage Report vignette, since that's a hardcoded value of the aspect ratio of the lat/lon in a proper projection of the U.S. map.

I would think about converting the mapping data into an sf object, where you will need to:

1. convert the lat/lon of the polygons into a geometry object
2. specify the projection using st_transform and a proj4 string -- can grab from projection wizard
3. change the ggplot geom_polygon call into geom_sf

There's a lot more cool things the sf package can do for manipulating geographic data...

The api now contains a geometry column with coordinates and type sub fields. Plot maps using this without the need to download shapefile or do geojoins.

getPrevalenceByLocation(mutations = c("S:P681R"), location = "Brazil")
should work, but it's requiring a pangolin_lineage.

In the returned data frame convert column date to date type

Currently the following error is thrown since & is not encoded as \u0026

eu = getCountryByRegion("Europe & Central Asia")
Error in open.connection(con, "rb") : HTTP error 400.

??outbreakinfo only lists one help page and no vignettes:

https://outbreak-info.github.io/R-outbreak-info -- add an intro to explain what the purpose of the vignette is, what you'll do in it.

getEpiData(name="United States of America", date=2020-07-01) will not work since the date here will be 2012. Add check to see if date is a string else show relevant error message.