first draft

.Rbuildignore

@@ -0,0 +1,3 @@
+^.*\.Rproj$
+^\.Rproj\.user$
+docs

.gitignore

@@ -2,3 +2,6 @@
 .Rhistory
 .RData
 .Ruserdata
+*.Rproj
+inst/doc
+.DS_Store

DESCRIPTION

@@ -0,0 +1,29 @@
+Package: rCAX
+Type: Package
+Title: Coordinated Assessments Client
+Description: An 'API' key is required.
+Version: 0.1.0
+Authors@R: 
+    c(person(given = "Eli",
+             family = "Holmes",
+             role = c("aut", "cre"),
+             email = "eli.holmes@noaa.gov"),
+      person(given = "Mari",
+             family = "Williams",
+             role = c("aut"),
+             email = "mari.williams@noaa.gov")
+      )
+License: MIT + file LICENSE
+URL: https://github.com/nwfsc-math-bio/rCAX
+BugReports: https://github.com/nwfsc-math-bio/rCAX/issues
+Encoding: UTF-8
+Language: en-US
+Imports: crul (>= 0.3.8), jsonlite (>= 1.1)
+RoxygenNote: 7.2.1
+NeedsCompilation: no
+Author: Eli Holmes [aut, cre],
+  Mari Williams [aut]
+Suggests: 
+    knitr,
+    rmarkdown
+VignetteBuilder: knitr

LICENSE

@@ -0,0 +1,2 @@
+YEAR: 2020
+COPYRIGHT HOLDER: Scott Chamberlain

NAMESPACE

@@ -0,0 +1,13 @@
+# Generated by roxygen2: do not edit by hand
+
+export(check_key)
+export(rcax_GET)
+export(rcax_base)
+export(rcax_nosa)
+export(rcax_nosa_)
+export(rcax_parse)
+export(rcax_ua)
+export(rcax_use_cax)
+export(rcax_version)
+export(rl_citation)
+importFrom(jsonlite,fromJSON)

NEWS.md

@@ -0,0 +1,4 @@
+rCAX 0.1.0
+===================
+
+* Testing

R/rcax-package.R

@@ -0,0 +1,31 @@
+#' @title rCAX
+#' @description CAX R Client
+#' @section ids
+#'
+#' @section Authentication:
+#' You will need to request a pull key from StreamNet. You will use the same key for all your requests. 
+#' Instructions for requesting a key are here https://www.streamnet.org/resources/exchange-tools/rest-api-documentation/ 
+#' Make sure to specify what you will do with the key and that you only need pull access.
+#' After getting your key set it as CAX_KEY in your .Renviron file. Paste this text into that file.
+#' 
+#' CAX_KEY='youractualkeynotthisstring'
+#' 
+#' To find (and create if necessary) your .Renviron file, use `usethis::edit_r_environ()` 
+#' then open that file and paste in the key text. 
+#' After you edit the file, you will need to restart R. If you are in RStudio use Session > Restart R.
+#' 
+#' Keep this key private. You can pass the key in to each function via the
+#' `key` parameter, but it's better to store the key as a
+#' environment variable (`CAX_KEY`).
+#'
+#' @section Citing the CAX data:
+#' 
+#' @section CAX API Terms of Use:
+#' See 
+#'#'
+#' @importFrom jsonlite fromJSON
+#' @name rCAX-package
+#' @aliases rCAX
+#' @docType package
+#' @keywords package
+NULL

R/rcax_GET.R

@@ -0,0 +1,64 @@
+#' Make a GET call to API
+#'
+#' @export
+#' @param path what to add after the base api path
+#' @param key the api key
+#' @param ... extra info
+#' @examples \dontrun{
+#' rcax_GET('Fratercula arctica')
+#' }
+rcax_GET <- function(path, key = NULL, query=NULL, ...){
+  cli <- crul::HttpClient$new(
+    url = file.path(rcax_base(), path),
+    opts = list(useragent = rcax_ua())
+  )
+  temp <- cli$get(query = c(query, list(XApiKey = check_key(key))), ...)
+  temp$raise_for_status()
+  x <- temp$parse("UTF-8")
+  err_catcher(x)
+  return(x)
+}
+
+#' Set the base API url
+#'
+#' @export
+#' @rdname rcax_base
+rcax_base <- function() "https://api.streamnet.org/api/v1"
+
+#' Parse results from API call
+#'
+#' @param x what needs to be parsed
+#' @param parse logical true/false
+#' @export
+#' @rdname rcax_parse
+rcax_parse <- function(x, parse) {
+  jsonlite::fromJSON(x, parse)
+}
+
+#' Check to make sure key looks ok
+#'
+#' @param key the key
+#' @export
+#' @rdname check_key
+check_key <- function(key){
+  tmp <- if (is.null(key)) Sys.getenv("CAX_KEY", "") else key
+  if (tmp == "") {
+    rcax_use_cax()
+    stop("need an API key for CAX data", call. = FALSE)
+  } else {
+    tmp
+  }
+}
+
+#' Make the user agent string
+#'
+#' @export
+#' @rdname rcax_ua
+rcax_ua <- function() {
+  versions <- c(
+    paste0("r-curl/", utils::packageVersion("curl")),
+    paste0("crul/", utils::packageVersion("crul")),
+    sprintf("rCAX/%s", utils::packageVersion("rCAX"))
+  )
+  paste0(versions, collapse = " ")
+}

R/rcax_citation.R

@@ -0,0 +1,12 @@
+#' Get the citation CAX version
+#'
+#' @export
+#' @param ... Curl options passed to [crul::verb-GET]
+#' @return API citation as character string
+#' @examples \dontrun{
+#' rcax_citation()
+#' }
+rl_citation <- function(...) {
+  sprintf('Coordinated Assessments. Version %s <https://www.streamnet.org/home/data-maps/fish-hlis/>',
+          rcax_version(...))
+}

R/rcax_key.R

@@ -0,0 +1,15 @@
+#' Print message re how to get CAX API key
+#'
+#' @description Provides instruction on how to store the key.
+#'
+#' @details Contact Streamnet to request a pull key. https://www.streamnet.org/resources/exchange-tools/rest-api-documentation/
+#'
+#' @aliases rcax_use_cax
+#'
+#' @export
+#'
+rcax_use_cax <- function(){
+  message("You will need to request a pull key from StreamNet. Instructions here https://www.streamnet.org/resources/exchange-tools/rest-api-documentation/ \n\nAfter getting your key set it as CAX_KEY in your .Renviron file. Paste this text into that file.\n CAX_KEY='youractualkeynotthisstring'\n To find (and create if necessary) your .Renviron file, use `usethis::edit_r_environ()` then open that file and paste in the key text.\n\nAfter you edit the file, you will need to restart R. If you are in RStudio use Session > Restart R.")
+
+  invisible("https://www.streamnet.org/resources/exchange-tools/rest-api-documentation/")
+}

R/rcax_nosa.R

@@ -0,0 +1,25 @@
+#' Get nosa table
+#'
+#' @export
+#' @param table_id table id eg 4EF09E86-2AA8-4C98-A983-A272C2C2C7E3
+#' @param ... other query params. Enter as abc=1, def=2, etc.
+
+#' @template all
+#' @template info
+#' @examples \dontrun{
+#' rcax_nosa("4EF09E86-2AA8-4C98-A983-A272C2C2C7E3")
+#' rcax_nosa_()
+#' }
+rcax_nosa <- function(table_id, key = NULL, parse = TRUE, ...) {
+  assert_is(table_id, 'character')
+  assert_is(parse, 'logical')
+  rcax_parse(rcax_nosa_(table_id, key, ...), parse)
+}
+
+#' @export
+#' @rdname rcax_nosa
+rcax_nosa_ <- function(table_id, key = NULL, ...) {
+  assert_is(table_id, 'character')
+  assert_is(key, 'character')
+  rcax_GET("ca", key, query=qlist(list(table_id=table_id), ...))
+}

R/rcax_version.R

@@ -0,0 +1,11 @@
+#' Get the CAX API version
+#'
+#' @export
+#' @param ... Curl options passed to [crul::verb-GET]
+#' @return API version as character string
+#' @examples \dontrun{
+#' rcax_version()
+#' }
+rcax_version <- function(...) {
+  rl_parse(rcax_GET("version", NULL, ...), TRUE)$version
+}

R/utils.R

@@ -0,0 +1,74 @@
+ct <- function(l) Filter(Negate(is.null), l)
+
+err_catcher <- function(x) {
+  xx <- jsonlite::fromJSON(x)
+  if (any(vapply(c("message", "error"), function(z) z %in% names(xx),
+                 logical(1)))) {
+    stop(xx[[1]], call. = FALSE)
+  }
+}
+
+space <- function(x) gsub("\\s", "%20", x)
+
+assert_is <- function(x, y) {
+  if (!is.null(x)) {
+    if (!inherits(x, y)) {
+      stop(deparse(substitute(x)), " must be of class ",
+           paste0(y, collapse = ", "), call. = FALSE)
+    }
+  }
+}
+
+assert_n <- function(x, n) {
+  if (!is.null(x)) {
+    if (!length(x) == n) {
+      stop(deparse(substitute(x)), " must be length ", n, call. = FALSE)
+    }
+  }
+}
+
+assert_not_na <- function(x) {
+  if (!is.null(x)) {
+    if (any(is.na(x))) {
+      stop(deparse(substitute(x)), " must not be NA", call. = FALSE)
+    }
+  }
+}
+
+nir <- function(path_name, path_id, name = NULL, id = NULL, region = NULL) {
+
+  # only one of name OR id
+  stopifnot(xor(!is.null(name), !is.null(id)))
+
+  # check types
+  assert_is(name, 'character')
+  assert_is(id, c('integer', 'numeric'))
+  assert_is(region, 'character')
+
+  # can't be NA
+  assert_not_na(name)
+  assert_not_na(id)
+  assert_not_na(region)
+
+  # check lengths - only length 1 allowed for all
+  assert_n(name, 1)
+  assert_n(id, 1)
+  assert_n(region, 1)
+
+  # construct path
+  path <- if (!is.null(name)) {
+    file.path(path_name, space(name))
+  } else {
+    file.path(path_id, id)
+  }
+  if (!is.null(region)) {
+    path <- file.path(path, "region", space(region))
+  }
+
+  return(path)
+}
+
+qlist <- function(x, ...) {
+  return(c(x, ...))
+}
+

README.md

@@ -1,7 +1,39 @@
-# CAX
+rCAX
+========
 
-repo for accessing CAX
+`rCAX` is an R client for the [Coordinated Assessments API](https://www.streamnet.org/resources/exchange-tools/rest-api-documentation/). 
 
-documentation: https://www.streamnet.org/resources/exchange-tools/rest-api-documentation/
+## Installation
+
+Development version
+
+```r
+remotes::install_github("nwfsc-math-bio/rCAX")
+```
+
+## Using
+
+First you need to get a pull api key from StreamNet. Then run `usethis::edit_r_environ()` to find or create your `.Renviron` file. Open that file and paste in `CAX_KEY = "whateveryourkeyis"`. Then restart R (Session > Restart R in RStudio).
+
+There is only one function at the moment `rcax_nosa()` to download a nosa table. Needs the table id.
+
+```
+a <- rcax_nosa("4EF09E86-2AA8-4C98-A983-A272C2C2C7E3")
+```
+
+## Contributing
+
+Fork and put in a pull request.
+
+First to-dos
+
+* Figure out how to download the whole table.  `rcax_nosa()` is just getting a few lines.
+* Edit `rcax_nosa()` so it returns something with a better format. Right now just a list.
+
+## Meta
+
+* Please [report any issues or bugs](https://github.com/nwfsc-math-bio/rCAX/issues).
+* License: MIT
+* Get citation information for `rCAX` in R doing `citation(package = 'rCAX')`
+* Please note that this package is released with a [Contributor Code of Conduct](https://ropensci.org/code-of-conduct/). By contributing to this project, you agree to abide by its terms.
 
-https://www.dataquest.io/blog/r-api-tutorial/