pmap (almost) all the things

[dpprdan]

The main point of the feat_pmap branch is to vectorise (almost) all arguments of oc_forward()/oc_reverse(). This made some code clean_up necessary. The exported gecoding functions basically just wrap oc_check_query and oc_process() which do the main work.

The main changes are:

1. I implemented NSE in base R rather than tidyeval in oc_forward_df()/oc_reverse_df(). This is probably the part I am most uncertain about, so let me know if you have a better idea on how to implement this.
2. I added a oc_bbox() helper function, to get the countrycode arguments into shape.
3. I added a oc_config() function, which only changes the rate limit at the moment (useful if you have one of the paid plans), but may also change other per-session settings in the future.
4. NEWS: I have added NEWS items for these changes.
5. documentation: I have added (at least minimally viable) documentation.
6. Vignette(s): I've updated the introductory vignette. I used a child document to keep the README and the introductory vignette in sync, as described here https://www.garrickadenbuie.com/blog/2018/03/05/dry-vignette-and-readme/, which is something Jonathan Carroll brought up here: Vignette standards software-review-meta#55. I have not yet addressed the vectorised arguments of the geocoding functions though, as well as the other topics mentioned in Issue Vignette(s) topics #53. I propose we resume discussion about vignettes there.
7. Issues add documentation for oc_forward and oc_reverse #34 (oc_forward docs), vignette title #54 (vignette title) and new OpenCage website URL #59 (new website URL) are fixed.
8. Issue Before a PR asking questions here #61 is fixed, as far as safer tests are concerned. As stated there, return = "url_only" is only allowed if key = NULL or if used in an interactive session in order to prevent credential leakage.
9. Issue keys for testing response code 402 and 403 #63, keys for testing 402/403. fixed in this commit in feat_pmap branch: dpprdan@ec344be

I'll also add the current NEWS:

opencage 0.1.4.9001

This is a major rewrite of the {opencage} package. opencage_forward() and opencage_reverse() have been deprecated and are superseded by oc_forward() and oc_reverse(), respectively. In addition there are two new functions oc_forward_df() and oc_reverse_df(), which (reverse) geocode a placename column (or latitude/longitude columns) in a data frame.

The new features include:

• oc_forward() and oc_reverse() return either lists of data frames, JSON strings, GeoJSON strings, or URLs to be sent to the API (for debugging purposes).
• oc_forward_df() and oc_reverse_df() take a data frame as input and return a data frame with the geocoding results, optionally with the source data frame bound to the results data frame.
• Almost all arguments of the geocoding functions are vectorised (the exceptions being output, key and no_record), so it is possible to serially (reverse) geocode lists of placenames or coordinates. The geocoding functions show a progress indicator when more than one placename or latitude/longitude pair is provided.
• The forward geocoding functions now support multiple countrycodes in accordance with the OpenCage API (Support multiple country codes #44). The countrycodes can now be provided in upper or lower case (Let country code be lower or upper #47).
• A helper function oc_bbox() now makes it easier to create (lists of) bounding boxes from vectors, bbox objects and data frames.
• http requests are now handled by {crul}, not {httr} (Ditch httr in favour of crul #37).
• API calls are now rate limited (ratelimit API calls #32). The default limit is set to 1 call per second as per the API limit of the Free Trial plan. The rate limit can be adjusted with oc_config().

Breaking changes

• opencage_forward(), opencage_reverse(), and opencage_key() are (soft) deprecated. opencage_key() has just been renamed to oc_key() for consistency.
• opencage_forward() and opencage_reverse() will always output strings as characters, i.e. they won't coerce to factor depending on the stringsAsFactor option.
• The column name for both languagecodes and countrycodes is now code, and not alpha2 and Code, respectively.

[maelle]

ah interesting and tidyr has no such thing like dplyr's .data$?

[dpprdan]

Nope, or rather op is part of ...?! I don't remember though if lintr would be satisfied with op being defined in globalVariables.

[maelle]

Fantastic work @dpprdan, thanks a ton! I have added comments/requests but they're all minimal I think.

Two further comments

❯ checking R code for possible problems ... NOTE
  oc_forward_df: no visible binding for global variable ‘query’
  oc_forward_df: no visible binding for global variable ‘lat’
  oc_forward_df: no visible binding for global variable ‘lng’
  oc_forward_df: no visible binding for global variable ‘formatted’
  oc_forward_df: no visible binding for global variable ‘op’
  oc_reverse_df: no visible binding for global variable ‘query’
  oc_reverse_df: no visible binding for global variable ‘formatted’
  oc_reverse_df: no visible binding for global variable ‘op’
  Undefined global functions or variables:
    formatted lat lng op query

So lintr isn't the only one to complain 😉

❯ checking Rd cross-references ... NOTE
  Package unavailable to check Rd xrefs: ‘sf’

Please remove the cross-ref to sf because otherwise we'd need to have sf as a dependency.

[dpprdan]

Re global variables: That is fixed in devel already. Do I need to do anything here?

Re Rd xrefs: ‘sf’ Is that from R CMD check? Why did I not see that before. It probably is from oc_bbox where one example shows to to use a sf::bbox object. Do you think we could get away with it if we wrap it in a if (requireNamespace("sf") call?

[maelle]

The cross ref is from somewhere in docs where you tried to refer to sf docs, we should not do that since sf is not a dependency. But yes to making that example safer too!