other/reviewers-response.md

In naturalis/nbaR: R Package Client for the Netherlands Biodiversity API

Hi @sckott @DomBennett @mbjoseph, thank you for the thorough evaluation of the package. The new version of the nbaR package aims to address all of these issues. For a better overview, I cpoied your comment into github issues summarised in the milestone Ropenscience-revision. This resulted in the following major changes:

Wrapper functions The package now features low-level API access using function wrappers which are more easy to use. For each endpoint, there is one wrapper which can be called directly without any QuerySpec, QueryCondition etc. objects. For complex structures, the wrappers return native R datatypes, such as data.frame (with list columns) or list (types are configurable by the user) instead of R6 objects such as Specimen or Taxon. Documentation on the wrappers can be found in the reference and further description is provided in the get started vignette.

This is documented in the following issues: #18, #32, #34

Documentation The main vignette has been split into smaller parts. Documentation is now spread over 5 pages: Getting started, Objects and advanced queries, services summary, sharks workflow, tomato workflow (issue #17, issue #36, issue #34). Help files: Have been improved. Extended descriptions have been added for the main model datatypes (Specimen, Taxon, Multimedia, Geo and also for QuerySpec and QueryCondition). These changes have to be made in the code annotations of the API itself, therefore not yet all of the classes are documented in detail. Since I am not the developer of the API, this has to be communicated and done by someone else; we are working on completing more descriptions. However, many classes will never be used by the nbaR user: For example, almost no records have a LithoStratigraphy field, thus the user will in most cases not come across this object.(issue #24). More information on operators is now given in the vignette (issue #28). Typos: issue #46, issue #35. Different clients are now better explained: (issue #45). Pkdown issues have been resolved. In addition, client classes and model classes are now better organised in the reference page (issue #23). Character length in vignette code has been reduced to max 80 chrs per line (issue #37). Empty query example at start of vignette has been removed (issue #38). * Size argument now better explained in shark vignette (issue #47).

Tests/Checks/Coverage Unit tests failed if the NBA was down, thus we now do a ping in the unit tests to test beforehand if the NBA is alive (issue #19. Check results: R CMD CHECK now proceeds without errors, warnings or notes (issue #20). Spell-check was done (issue #22). Goodpractice results were improved (issue #21). However, it was not possible to cut all lines of code to 80 characters, due to autogenerated code.

Miscellaneuos dwca download functions now suppress excessive output (issue #44). Much of the duplicated code is now avoided by having rewritten the fromJSONString and fromList methods in the templates (issue #33). Classes now have a print method, which lists all members (and their datatypes) and available functions in a nice way (issue #39). A QueryCondition object can now also be created with a named list (issue #29). Warnings for function geo_age are now more clear (issue #48). Function find_by_ids can now also take a vector of ids as argument (issue #41). Map of tomatoes now added to tomato vignette (issue #27). Reduced R package size etc., (issue #31).

What I did not do Schematic code example for clients: Since we have now a Getting Started using the wrapper functions and instanciating clients is in the advanced parts, I believe this is not necessary anymore (issue #26). Returning data.frame for get_distinct_values_per_group and count_distinct_values_per_group. This is now done in the wrappers. * More ideomatic code for specifying query parameters: I think the way to pass query parameters as a list is sufficient, see also issue #40.

I hope you agree with me that these changes significantly improved the usage of this package. Thanks again for taking the time to review.

Best,

Hannes

naturalis/nbaR documentation built on Nov. 12, 2023, 4:47 p.m.