feat: add get_rap_table() unified interface to tabular data API endpoints

[s-appleby]

I wanted to use the tabular data API to access cover, coverMeteorology, and production estimates from RAP, so I made some edits to your 16-day production script to work with each of them. This addresses issue #12 as planned there.

I adhered to all your naming conventions, and updated the descriptions/list of columns for each function to match the various APIs. I ran tests on each using a multi-polygon sf object, and compared the results with those obtained from the RAP web map using the same polygon shapefiles, and everything seems to match up (with tiny differences in the estimates, presumably due to the conversion between sf vector and terra raster formats).

I also built the package and tested the new functions... they seem to work as intended and the help documentation seems to render as expected.

In any case, feel free to use these or not!

[brownag]

Hi @s-appleby, thanks for your interest in rapr and your contribution.

For #12 I wanted to abstract out the internal logic from get_rap_production16day_table() into a reusable function. Your current implementation adds copies of nearly the same code, changing only the endpoint. I would prefer not to have to maintain these as separate functions and documentation if their internals are so similar.

I probably did not do a very good job of laying out the breadcrumbs in the issue.

Thinking about it a bit more now: the interface I want is an exported get_rap_table() function that allows for specifying an endpoint and version number (similar to how get_rap() works). Then the get_rap_production16day_table, get_rap_cover_table, get_rap_coverMeterology_table, get_rap_production_table, etc. functions would be thin wrappers around that. We can then have all functions exported, but in the same .Rd file (as all of their arguments are the same, with exception of get_rap_table which will take endpoint and version as well). It would be best to put all of these in the same .R file as well. For each function's roxygen block we can include customization for the return type data content and details tags as needed.

I appreciate the assistance moving along with these planned features. Either you can refactor this PR yourself based on above specs (let me know if you have any questions), or I can merge your PR and rework it myself. Regardless, please add yourself, with ORCID, as contributor in the DESCRIPTION file Authors@R section

[s-appleby]

Hi @brownag, thanks for the feedback! I had that exact thought last night (at least about the single get_rap_table() function with an additional argument for the endpoint). Not sure if the other wrapper functions (i.e. get_rap_production_table) make sense given the straightforward usage of get_rap_table(), but they'd certainly be simple to create/maintain.

I'll dive into this tonight for a bit and see if I can come up with a get_rap_table() solution as you described and a wrapper to replace the existing get_rap_production16day_table() to avoid breaking anyone's existing code -- can easily add the other wrappers as well if that's the way forward.

In short: I'll work on get_rap_table() this week (hopefully done tonight), so don't merge this PR yet. Thanks!

[brownag]

Excellent. Good points, we are thinking the same way. I agree we probably do not need the thin wrappers. I would be fine with deprecating get_rap_production16day_table() in favor of get_rap_table() with an endpoint specified and then have all examples use the new interface. Looking forward to it, and thanks for taking it on.

[s-appleby]

The get_rap_table() function is complete, along with documentation and a wrapper function to keep get_rap_production16day_table() available for past users.

It is, of course, based on the original 16 day production specific function, with changes to allow different APIs to be called and format the results correctly when presented with only a single record per response. I kept the arguments as similar to get_rap() as possible to avoid confusion when moving between the two functions (including changing "name" to "names"). I included a version argument, but as it seems the API is only available for "V3" a the moment it's really just there for future use, and the function intentionally throws an error if any other version is specified.

I spent some time working on the documentation to keep it readable and still provide all the necessary information, hopefully it comes across clearly!

I've tested get_rap_table() with several sf polygons (with one or multiple features), combinations of years, mis-spelled arguments, etc. and the function performs (or fails) as expected. I also ran a few polygons through the new get_rap_production16day_table() and it (unsurprisingly for a simple wrapper function) performs as expected.

Hope this is as helpful for others as it's been for me... really streamlines requesting these estimates for lots of study plots at the same time, glad I found your package!

[brownag]

THanks very much for your contribution, Scott @s-appleby