NEWS.md
elevation() function: the Google Maps API requires a form of payment up front, and so we’ve decided to move away from the service. elevation() now uses the Geonames service https://www.geonames.org/; it does require you to register to get a username, but its a free service. Geonames has a few different data models for elevation and can be chosen in the elevation_model parameter (#344) (#345)occ_data()/occ_search() output: the data.frame in the data slot now always has the first column as the occurrence key (key), and the second column is now the scientific name (scientificName). the previously used name column still exists in the data.frame, so as not to break any user code, but is simply a duplicate of the scientificName column. in a future version of this package the name column will be dropped (#329)occ_search()/occ_data()/occ_download() documentation on WKT (well-known text) with respect to winding order. GBIF requires counter-clockwise winding order; if you submit clockwise winding order WKT to occ_search() or occ_data() you should get data back but the WKT is treated as an exclusion, so returns data outside of that shape instead of within it; if you submit clockwise winding order WKT to occ_download() you will get no data back (#340)occ_download(), was failing in certain cases because of some bad code in an internal function catch_err() (#333)occ_download() was not returning user name and email in it’s print method (#334)occ_issues() was failing with occ_data() or occ_search() input when type="many" (i.e., when > 1 thing was passed in) (#341)vcr package so do not require an internet connection (#306) (#327)name_usage() problem, more work coming to allow users to use the name issues data like we allow for occurrence issues through occ_issues() (#324)map_fetch() changes following changes in GBIF maps API: new parameters taxonKey, datasetkey, country, publishingOrg, publishingCountry and removed parameters search and id; note that this changes how queries work with this function (#319)map_fetch() docs that style parameter does not necessarily use the style you give it. not sure why (#302)occ_download_queue() to report an accurate number of jobs being processed; before we were just saying “kicking off first 3 requests” even if there were only 1 or 2 (#312)occ_get() when verbatim=TRUE (#318)elevation() function now fails better. when the API key was invalid the function did not give an informative message; now it does (#322)occ_download_queue(): sleep time between successive calls to check on the status of download requests is now 10 seconds or greater. This shouldn’t slow down your use of occ_download_queue() much because most requests should take more than the 10 seconds to be prepared (#313)@importFrom fxns used from lazyeval package to avoid check note (#316)reshape2 and maps packages from Suggests (#317)name_usage(): we were screwing up parsing of issues column when single taxon keys passed in (#314)occ_issues() now works with download data and arbitrary data.frame’s (#193)occ_download_prep() for preparing a download request without executing it, and occ_download_queue() for kicking off many download jobs while respecting GBIF’s downloads rate limits. See also internal R6 classes for dealing with queuing: DownReq, GifQueue. See ?occ_download_queue to get started (#266) (#305) (#311)map_fetch() working with the GBIF maps API https://www.gbif.org/developer/maps. See ?map_fetch to get started (#238) (#269) (#284) thanks to @JanLauGe for the work on thisname_lookup() gains origin parameter (#288) (#293) thanks @peterdesmet and @damianooldoniname_lookup() and name_usage() gain internal paging - just as occ_search()/occ_data() have (#291) (see also #281) thanks @damianooldonilazyeval, and new suggests png and raster
occ_search()/occ_data() gain parameter skip_validate (boolean) to skip or not stkip WKT validation by the wicket packagename_usage() to check params that now only allow 1 value: name, language, datasetKey, rank (#287)occ_count() loses nubKey, catalogNumber, and hostCountry as those parameters are no longer accepted by GBIFname_usage(), was screwing something up internally (#286)occ_data(): curl options weren’t being passed through (#297)occ_search()/occ_data() - skipping the wicket validation and constructing WKT by hand from bounding box (if bounding box given) - the validation that wicket does isn’t what GBIF wants (#303)fill parameter to occ_download_import() to pass on to fill in data.table::fread, and set fill=TRUE as default. (#292)occ_download() (#300)occ_download() in which a single taxonKey passed in was failing (#283)name_usage() was ignoring datasetKey and uuid parameters (#290)gbifmap() has been removed, see the package mapr for similar functionality and map_fetch() in this package to use the GBIF map API (#298)gbif_citation() function gains an S3 method for passing the output of occ_download_meta() to it. In addition, for downloads gbif_citation() now returns a citation for the entire download (including) its DOI, in addition to citations for each dataset (#274) thanks @dnoesgaardocc_count(): georeferenced had a misleading description of what the value FALSE did (#265)gbifmap() - was failing in some cases - better error handlingn now (#271) thanks @TomaszSuchanocc_download_cancel_staged(): it wasn’t passing on authentication parameters correctly (#280)?many-values manual file for details. added docs to individual functions that support this, and added additional tests (#200) (#260) (#261)V8 dependency and replaced with C++ based WKT parser package wicket. We still use rgeos for some WKT parsing. rgbif functions that use wicket: gbif_bbox2wkt, gbif_wkt2bbox, check_wkt (#243)httr replaced with crul for HTTP reqeusts. As part of this change, the ... parameter was replaced in most functions by curlopts which expects a list. Some functions require a ... parameter for facet inputs, so ... is retained with the addition of curltops parameter. A result of this change is that whereas in the past parameters that were not defined in a function that also had a ... parameter would essentially silently ignore that undefined parameter, but with functions where ... was removed a misspelled or undefined parameter will cause an error with message (#256)occ_download_import() to allow import of csv type download in addition to darwin core archive. additional change to occ_download_get to add format attribute stating which format (#246)occ_download_import adding fill=TRUE to the data.table::fread call (#257)occ_dowload gains new parameter body to allow users to pass in JSON or a list for the query instead of passing in statements to .... See examples in ?occ_dowload.occ_download to structure query correctly when type=within and geometry used because the structure is slightly different than when not using geometry (#242)occ_download to allow OR queries for many values of a parameter, e.g., taxonKey=2475470,2480946 will be queried correctly now as essentially taxonKey=2475470 or taxonKey=2480946 (#245)parsenames() caused by some slots in the list being NULL (#237)occ_facet() tests were failing due to changes in GBIF API (#239)gbif_oai_get_records() for slight changes in oai dependency pkg (#236)occ_search() now has faceted search. This feature is not in occ_data() as that function focuses on getting occurrence data quickly, so will not do get facet data. This means that a new slot is available in the output object from occ_search(), namely facets. Note that rgbif has had faceted search for the species search route (name_lookup()) and the registry search route (dataset_search()) for quite a while. (#215)occ_facet()) to facilitate retrieving only facet data, so no occurrence data is retrieved. (#215) (#229)occ_search() and occ_data() following addition the GBIF search API: subgenusKey, repatriated, phylumKey, kingdomKey, classKey, orderKey, familyKey, genusKey, establishmentMeans, protocol, license, organismId, publishingOrg, stateProvince, waterBody, locality (#216) (#224)spellCheck added to occ_search() and occ_data() that if TRUE spell checks anything passed to the search parameter (same as q parameter on GBIF API; which is a full text search) (#227)occ_spellcheck to spell check search terms, returns TRUE if no spelling problems, or a list with info on suggestions if not.occ_search() and occ_data() now have ability to support queries where limit=0, which for one should be possible and not fail as we did previously, and second, this makes it so that you can do faceted searches (See above) and not have to wait for occurrence records to be returned. (#222)MULTIPOLYGON well known text features now supported in the GBIF API. Previously, you could not query geometry with more than one polygon (POLYGON), but now you can. (#222)occ_count(), especially for the set of allowed parameter options that the GBIF count API supportsocc_count() gains new parameter typeStatus to indicate the specimen type status.data slot now returns NULL instead of a character stringgbif_photos(): 1) Mapbox URLs to their JS and CSS assets were out of date, and API key needed. 2) In RStudio, the table view was outputting errors due to serving files on localhost:<port> instead of simply opening the file; fixed now by checking platform and using simple open file command appropriate for the OS. (#228) (#235)is() with inherits(), no longer importing methods() (#219)data parameter, now they are (#210)gbifmap() man file (#212) thanks to @rossmounceocc_download(), in which strings to parse were not being parsed correctly if spaces weren’t in the right place, should be more robust now, and added tests (#217). Came from https://discuss.ropensci.org/t/rgbif-using-geometry-in-occ-download/395
type was being silently ignored in a number of registry functions. fixed that. (#211)occ_data() and occ_search() gain ability to more flexibly deal with inputs to the geometry parameter. Previously, long WKT strings passed to occ_search() or occ_data() would fail because URIs can only be so long. Another option is to use the download API (see ?downloads). This version adds the ability to choose what to do with long WKT strings via the geom_big parameter: asis (same as previous version), bbox which detects if a WKT sting is likely too long, and creates a bounding box from the WKT string then once data is retrived, clips the result to the original WKT string; axe uses the geoaxe package to chop up the input WKT polygon into many, with toggles in the new parameters geom_size and geom_n. (#197) (#199)geom_big="axe", then named elements of the output get names geom1, geom2, geom3, etc. instead of the input WKT strings - this is because WKT strings can be very long, and make for very awkward named access to elements. The original WKT strings can still be accessed via attr(result, "args")$geometry
name_usage() function, see commit e88cf01cc11cb238d44222346eaeff001c0c637e
testthat fxn names, e.g., expect_gt() instead of expect_more_than()
occ_download() to parse error correctly when empty body passed from GBIF (#202)occ_data() - its primary purpose to perform faster data requests. Whereas occ_search() gives you lots of data, including taxonomic hierarchies and media records, occ_data() only gives occurrence data. (#190)XML with xml2 (#192)data.table::rbindlist() for fast list to data.frame coercion: name_lookup(), name_backbone(), name_suggest(), name_usage(), and parsenames() (#191)httr usage to comply with changes in httr >= v1.1.0: now setting encoding explicitly to UTF-8 and parsing all data manually, using the internal function function(x) content(x, "text", encoding = "UTF-8") (#195)move_col() to not fail on fields that don’t exist. Was failing sometimes when no latitude or longitude columns were returned. (#196)gbif_oai_*()) for working with GBIF registry OAI-PMH service. Now importing oai package to make working with GBIF’s OAI-PMH service easier (#183)r-curl/0.9.4 httr/1.0.0 rOpenSci(rgbif/0.9.0), with whatever versions of each package you’re using. We also pass a user-agent string with the header X-USER-AGENT in case the useragent header gets stripped somewhere along the line (#185)gbif_citation() helps get citations for datasets eith using the occurrence search API via occ_search() or the downloads API via occ_downlad() (#178) (#179)importFrom instead of import in all cases now.collectorName changed to recordedBy (#184)occ_download_meta() print method to handle 1 or more predicate results (#186)occ_issues() to work with return=data and return=all occ_search() output (#188)terraformer.js javascript code included in the package along with an update in that codebase (#156)email parameter now NULL by default in the function occ_download(), so that if not provided or not set in options, then function fails. (#173)?downloads help file.elevation() to check for coordinates that are impossible (e.g., latitude > 90), not complete (e.g., lat given, long not given), or points at 0,0 (just warns, doesn’t stop). (#176) thanks @luisDVA/species route, fix to function name_usage() (#174)occ_search() to remove a block of code to do synonym checking. This block of code was used if the parameter scientificName was passed, and checked if the name given was a synonym; if yes, we used the accepted name according to the GBIF backbone taxonomy; if no, we proceeded with the name given by the user. We removed the block of code because the GBIF API now essentially does this behind the scenes server side. See https://github.com/gbif/gbif-api for examples. (#175)gbif_photos() and gbif_names() (#170)occ_download*() for working with the GBIF download API. This is the same service as using the GBIF website, but via an API. See ?downloads. (#154) (#167)utils, methods, and stats (#166)httr v1 where empty list not allowed to pass to the query parameter in GET (#163)/enumerations GBIF API route: enumeration() and enumeration_country(). Many parts of the GBIF API make use of enumerations, i.e. controlled vocabularies for specific topics - and are available via these functions. (#152)elevation() now requires an API key (#148)V8 package an Import now, used to do WKT read/create with use of the Javascript library Terraformer (http://terraformer.io/). Replaces packages sp and rgeos, which are no longer imported (#155)occ_search() parameter spatialIssues to hasGeospatialIssues (#151)/search and /count services, and how they work. (#150)name_lookup() (#149)plyr from Imports (#159)stringr from Imports (#160)maps and grid packages from Imports (#161)limit and start parameters was in some cases resulting in duplicate records returned. Problem fixed. (#157)\dontrun (#139)occ_search() to give correct values for default and max limit and start parameters (#145)GET helper function to properly pass on error message (#144)assertthat::assert_that() with stopifnot() to have one less dependency (#134)occ_search() to allow ability to query by only publishingCountry, that is, with no other parameters if desired (#137)GET() helper function to just pass NULL to the query parameter when the list of length 0 passed, since it caused requests to fail in some cases.name_lookup() to force a logical entry for certain parameters - before this fix if the correct logical param was not passed, the GBIF API went with its default parameter (#135)name_backbone() due to change in namelkupparser() helper function - fixes parsing for verbose output (#136)occ_search() documentation (#140)occ_issues() to subset data from occ_search() based on GBIF issues. (#) (#122)occ_search() results, and are intentionally moved to the beginning of the column order of the data to be more obvious. (#102)occ_search() now returns all data fields by default. The default setting for the fields parameter is all - but can be changed. See ?occ_search
gbif_names() to view highlighted terms in name results from a call to name_lookup(). (#114)occ_issues_lookup() to lookup GBIF issues based on code name or full issue name, and gbif_issues() to print the entire issues table.RCurl with httr
RJSONIO with jsonlite. Should see slight performance in JSON parsing with jsonlite.occ_search() now 500; was 25. (#113)organizations(), datasets(), networks(), nodes(), installations()) to data.frames when possible. (#117)occ_search() (#123)callopts parameter changed to ... throughout all functions. Now pass on options to httr as named lists or functions. (#130)dataset_search() and dataset_suggest() gain new parameter publishingOrg
limit parameter changed to 100 for dataset functions: dataset_search(), dataset_suggest(), and datasets().limit parameter changed to 100 for registry functions: installations(), networks(), organizations, and nodes().networks(): name, code, modifiedsince, startindex, and maxresults gone; new parameters query, identifier, identifierType, limit, and start
nodes(): new parameters identifier, identifierType, limit, and start
occ_search() failed sometimes on species that were not found. Fixed. (#112)occ_search() (#119)name_lookup() (#120)gbif_photos() that caused map with no data. (#121)name_() functions according to changes in the GBIF API spec, and fixed documentation to align with GBIF API changes, and added note about maximum limit. (#124) (#127) (#129) Thanks to @willgearty !occ_search() so that user can pass in multiple values to the issue parameter. (#107)occ_search() now has a dplyr like summary output when return='all'. See ?occ_search for examples. You can still easily access all data, by indexing to meta, hierarchy, data, or media via e.g., $data, ['data'], or [['data']]. (#95)occ_search(), we now return a media slot in the output list by default.gbif_photos() to view media files (photos in the wild or of museum specimens). Two options are available, which='map' creates a single map which presents the image when the user clicks on the point, and which='table' in which a table has one row for each image, presenting the image and an interactive map with the single point. (#88)sp and whisker
rgbif changed accordingly. (#92)camelCase from under_score style - changed accordingly in rgbif.plyr::compact() instead of importing from plyr.name_lookup() removed facet_only parameter as it doesn’t do anything - use limit=0 instead. Further, added two new slots of output: hierarchy and names (for common/vernacular names) (#96). The output can be determined by user via the return parameter.name_suggest(), if the field higherClassificationMap is selected to be returned via the fields parameter, a list is returned with a data frame, and a list of the hierarchies separately. If higherClassificationMap is not selected, only a data frame is returned.occ_search() gains new parameters mediatype and issue (#93), with detailed list of possible options for the issue parameter. Gains new examples for searching for images, examples of calls that will throw errors.check_wkt().facet_only parameter removed from dataset_search() function as it doesn’t do anything - use limit=0 instead.gbif_bbox2wkt() and gbif_wkt2bbox() to convert a bounding box to wkt and a wkt object to a bounding box, respectively. Copied from the spocc package. Prefixes to fxn names will avoid conflicts.rgeos::readWKT or from the returned response from GBIF.gbifmap() was throwing an error because it was looking for two variables latitude and longitude, which had been changed to decimalLatitude and decimalLongitude, respectively, in other functions in this package. Fixed. (#81)occ_get() was updated to include changes in the GBIF API for this endpoint. The fix included fixing the parser for verbatim results, see rgbif::gbifparser_verbatim. (#83)elevation() - it was expecting column names to be latitude and longitude, whereas inputs from other rgbif functions have changed to decimalLatitude and decimalLongitude.count_facet() introduced b/c GBIF no longer accepts hostCountry or nubKey parameters.gist(), stylegeojson(), and togeojson() functions now listed as deprecated. Their functionality moved to the spocc package (http://cran.r-project.org/web/packages/spocc/index.html). These functions will be removed from this package in a future version. (#82)gbifmap().occ_get() for when verbatim=TRUE, which gives back different data than when verbatim=FALSE.latitude is now decimalLatitude. longitude is now decimalLongitude. clazz is now class. Code in this package changed to accomodate these changes. date is now eventDate. georeferenced is now hasCoordinate. Beware of these changes in your own code using rgbif - find and replace for these should be easy.altitude parameter in occ_search() to elevation - should have been elevation the whole time.occ_count() function with parameter changes: nubKey parameter in changed to taxonKey. New parameter protocol. Parameter catalogNumber gone. Parameter hostCountry gone. These parameters are still in the function definition, but if called they throw a useful warning telling you the correct parameter names. (#76)name_lookup() function that was labeling facet outputs incorrectly. (#77)application/json, then parse JSON ourselves using RJSONIO::fromJSON (instead of httr doing it).stringsAsFactors = FALSE to all data.frame() calls.occ_search() function. These parameters are still in the function definition, but if called they throw a useful warning telling you the correct parameter names. (#75)name_usage, name_backbone, name_lookup, and name_suggest functions.sourceId parameter in name_usage() function doesn’t work so error message is thrown when used.check_wkt() to check that well known text string is the right format. (#68)occ_search() function. scientificName: search for a species by name (instead of taxonKey). continent: search by continent. lastInterpreted: search by last time GBIF modified the record. recordNumber: search by the data collector’s specimen record number - this is different from the GBIF record number. typeStatus: search by specimen type status. (#74)parameterName = c(x, y, z). These parameters are: taxonKey, scientificName, datasetKey, catalogNumber, collectorName, geometry, country, recordNumber, search, institutionCode, collectionCode, decimalLatitude, decimalLongitude, depth, year, typeStatus, lastInterpreted, and continent. This isn’t faceted search server side - this is just looping your different values of the parameter against the GBIF API.occ_search() now support range queries: decimalLatitude,decimalLongitude,depth,elevation,eventDate,lastInterpreted,month, and year. Do a range query for example by depth=50,100 to ask for occurrences where depth was recorded between 50 and 100 meters. Note that this syntax depth=c(50,100) will perform two separate searches, one for depth=50 and one for depth=100. (#71)DEPRECATED