added the rest of the tables. error check on flist names

#2 #

NAMESPACE

@@ -6,15 +6,19 @@ export(rcax_base)
 export(rcax_citation)
 export(rcax_escdata)
 export(rcax_filter)
+export(rcax_juvout)
 export(rcax_juvout_xport)
 export(rcax_key)
 export(rcax_nosa)
 export(rcax_nosa_xport)
 export(rcax_parse)
+export(rcax_pni)
 export(rcax_pni_xport)
 export(rcax_presmolt)
 export(rcax_presmolt_xport)
+export(rcax_rpers)
 export(rcax_rpers_xport)
+export(rcax_sar)
 export(rcax_sar_xport)
 export(rcax_superpops)
 export(rcax_table_query)

NEWS.md

@@ -1,12 +1,13 @@
 rCAX 0.6.0
 ===================
 
-* Added `rcax_pni_xport()`, `rcax_rpers_xport()`, `rcax_juvout_xport()`, `rcax_presmolt_xport()`, `rcax_presmolt()`
+* Added `rcax_pni_xport()`, `rcax_rpers_xport()`, `rcax_juvout_xport()`, `rcax_presmolt_xport()`, `rcax_presmolt()`, `rcax_pni()`, `rcax_sar()`, `rcax_rpers()`, `rcax_presmolt()`
 * Added template roxygen for all xport and basetable functions. Now details and description elements are identical. 
 * Dynamically find a nmfs_id or popid for the examples so that the examples never return an empty table.
 * in `rcax_table_query()` set rownames to NULL in returned tables
 * Added `ggplot2` to Suggests in DESCRIPTION file since I use it in some examples and will use in vignettes.
 * removed {stringr} and `|>` dependency
+* Added a check that all the flist names appear in the table. Requires an extra GET call but the call will fail otherwise if cols do not match.
 
 rCAX 0.5.0
 ===================

R/rcax_juvout.R

@@ -0,0 +1,55 @@
+#' Return Juvenile Outmigration base table
+#'  
+#' @export
+#' @template info
+#' @template tableargs
+#' @template basetablefuns
+#' @seealso `rcax_juvout_xport()`, `rcax_table_query()`, `rcax_filter()`, `rcax_key()`
+#' @examples 
+#' # return popid of first record
+#' # Note the part after $ is case sensitive
+#' id <- rcax_juvout(qlist=list(limit=1))$popid
+#' 
+#' a <- rcax_juvout(
+#'          flist=list(popid=id),
+#'          cols=c("popid", "outmigrationyear", "totalnatural")
+#'          )
+#' head(a)
+#' 
+#' # First 3 columns
+#' rcax_juvout(qlist=list(limit=3))[,1:3]
+#' 
+#' # to print the first 5 column names
+#' rcax_juvout(type="colnames")[1:5]
+#' 
+#' # to print the first 5 column names as they appear
+#' # in Excel files downloaded from https://www.streamnet.org/data/hli/
+#' tab <- rcax_juvout(qlist=list(limit=1))
+#' colnames(tab)[1:5]
+#' 
+rcax_juvout <- function(
+    tablename = "JuvenileOutmigrants",
+    flist = NULL,
+    qlist = NULL, 
+    cols = NULL,
+    sortcols = c("outmigrationyear", "popid"),
+    type = c("data.frame", "colnames"), 
+    GETargs = list(table_id = NULL, recordloc = "records", key = NULL, parse = TRUE), ...) {
+  # Error checking. Most happens in rcax_table_query.
+  assert_is(flist, 'list')
+  assert_is(qlist, 'list')
+
+  if(("popid" %in% names(flist)) & ("popid" %in% names(qlist))){
+     cat("popid appears in both flist and qlist. Ignoring the value in qlist.\n")
+    qlist$popid <- NULL
+  }
+
+  # API call and table filtering and sorting
+  rcax_table_query(
+    tablename = tablename, 
+    flist = flist, qlist = qlist, 
+    cols = cols, sortcols = sortcols,
+    type = type, 
+    GETargs = list(recordloc = "records"), ...)
+
+}

R/rcax_pni.R

@@ -0,0 +1,56 @@
+#' Return PNI base table
+#'    
+#' @export
+#' @template info
+#' @template tableargs
+#' @template basetablefuns
+#' @seealso `rcax_pni_xport()`, `rcax_table_query()`, `rcax_filter()`, `rcax_key()`
+#' @examples 
+#' # return popid of first record
+#' # Note the part after $ is case sensitive
+#' id <- rcax_pni(qlist=list(limit=1))$popid
+#' 
+#' # Return the table for this id
+#' a <- rcax_pni(
+#'          flist=list(popid=id),
+#'          cols=c("popid", "spawningyear", "pniej")
+#'          )
+#' head(a)
+#' 
+#' # First 3 columns
+#' rcax_pni(qlist=list(limit=3))[,1:3]
+#' 
+#' # to print the first 5 column names
+#' rcax_pni(type="colnames")[1:5]
+#' 
+#' # to print the first 5 column names as they appear
+#' # in Excel files downloaded from https://www.streamnet.org/data/hli/
+#' tab <- rcax_pni(qlist=list(limit=1))
+#' colnames(tab)[1:5]
+#' 
+rcax_pni <- function(
+    tablename = "PNI",
+    flist = NULL,
+    qlist = NULL, 
+    cols = NULL,
+    sortcols = c("spawningyear", "popid"),
+    type = c("data.frame", "colnames"), 
+    GETargs = list(table_id = NULL, recordloc = "records", key = NULL, parse = TRUE), ...) {
+  # Error checking. Most happens in rcax_table_query.
+  assert_is(flist, 'list')
+  assert_is(qlist, 'list')
+
+  if(("popid" %in% names(flist)) & ("popid" %in% names(qlist))){
+     cat("popid appears in both flist and qlist. Ignoring the value in qlist.\n")
+    qlist$popid <- NULL
+  }
+
+  # API call and table filtering and sorting
+  rcax_table_query(
+    tablename = tablename, 
+    flist = flist, qlist = qlist, 
+    cols = cols, sortcols = sortcols,
+    type = type, 
+    GETargs = list(recordloc = "records"), ...)
+
+}

R/rcax_rpers.R

@@ -0,0 +1,55 @@
+#' Return RperS base table
+#'  
+#' @export
+#' @template info
+#' @template tableargs
+#' @template basetablefuns
+#' @seealso `rcax_rpers_xport()`, `rcax_table_query()`, `rcax_filter()`, `rcax_key()`
+#' @examples 
+#' # return popid of first record
+#' # Note the part after $ is case sensitive
+#' id <- rcax_rpers(qlist=list(limit=1))$popid
+#' 
+#' a <- rcax_rpers(
+#'          flist=list(popid=id),
+#'          cols=c("popid", "broodyear", "rpers")
+#'          )
+#' head(a)
+#' 
+#' # First 3 columns
+#' rcax_rpers(qlist=list(limit=3))[,1:3]
+#' 
+#' # to print the first 5 column names
+#' rcax_rpers(type="colnames")[1:5]
+#' 
+#' # to print the first 5 column names as they appear
+#' # in Excel files downloaded from https://www.streamnet.org/data/hli/
+#' tab <- rcax_rpers(qlist=list(limit=1))
+#' colnames(tab)[1:5]
+#' 
+rcax_rpers <- function(
+    tablename = "RperS",
+    flist = NULL,
+    qlist = NULL, 
+    cols = NULL,
+    sortcols = c("broodyear", "popid"),
+    type = c("data.frame", "colnames"), 
+    GETargs = list(table_id = NULL, recordloc = "records", key = NULL, parse = TRUE), ...) {
+  # Error checking. Most happens in rcax_table_query.
+  assert_is(flist, 'list')
+  assert_is(qlist, 'list')
+
+  if(("popid" %in% names(flist)) & ("popid" %in% names(qlist))){
+     cat("popid appears in both flist and qlist. Ignoring the value in qlist.\n")
+    qlist$popid <- NULL
+  }
+
+  # API call and table filtering and sorting
+  rcax_table_query(
+    tablename = tablename, 
+    flist = flist, qlist = qlist, 
+    cols = cols, sortcols = sortcols,
+    type = type, 
+    GETargs = list(recordloc = "records"), ...)
+
+}

R/rcax_sar.R

@@ -0,0 +1,55 @@
+#' Return SAR base table
+#'  
+#' @export
+#' @template info
+#' @template tableargs
+#' @template basetablefuns
+#' @seealso `rcax_sar_xport()`, `rcax_table_query()`, `rcax_filter()`, `rcax_key()`
+#' @examples 
+#' # return popid of first record
+#' # Note the part after $ is case sensitive
+#' id <- rcax_sar(qlist=list(limit=1))$popid
+#' 
+#' a <- rcax_sar(
+#'          flist=list(popid=id),
+#'          cols=c("popid", "outmigrationyear", "sar")
+#'          )
+#' head(a)
+#' 
+#' # First 3 columns
+#' rcax_sar(qlist=list(limit=3))[,1:3]
+#' 
+#' # to print the first 5 column names
+#' rcax_sar(type="colnames")[1:5]
+#' 
+#' # to print the first 5 column names as they appear
+#' # in Excel files downloaded from https://www.streamnet.org/data/hli/
+#' tab <- rcax_sar(qlist=list(limit=1))
+#' colnames(tab)[1:5]
+#' 
+rcax_sar <- function(
+    tablename = "SAR",
+    flist = NULL,
+    qlist = NULL, 
+    cols = NULL,
+    sortcols = c("outmigrationyear", "popid"),
+    type = c("data.frame", "colnames"), 
+    GETargs = list(table_id = NULL, recordloc = "records", key = NULL, parse = TRUE), ...) {
+  # Error checking. Most happens in rcax_table_query.
+  assert_is(flist, 'list')
+  assert_is(qlist, 'list')
+
+  if(("popid" %in% names(flist)) & ("popid" %in% names(qlist))){
+     cat("popid appears in both flist and qlist. Ignoring the value in qlist.\n")
+    qlist$popid <- NULL
+  }
+
+  # API call and table filtering and sorting
+  rcax_table_query(
+    tablename = tablename, 
+    flist = flist, qlist = qlist, 
+    cols = cols, sortcols = sortcols,
+    type = type, 
+    GETargs = list(recordloc = "records"), ...)
+
+}

R/rcax_table_query.R

@@ -61,12 +61,24 @@ rcax_table_query <- function(
   if(is.null(GETargs$table_id))
     stop("Something wrong. GETargs$table_id is NULL. Perhaps tablename is misspelled? Check the CAX table names from a call to `rcax_tables()`. Alternatively the sysdata `caxtabs` might be out of date. In which case, you will need to look up the correct table_id and pass that into `GETargs`.")
 
+  # error check the flist because it will return a 500 if col is bad
+  if(type!="colnames" && !is.null(flist) && length(flist)!=0){
+    tmp <- list(table_id = GETargs$table_id, limit=1)
+    tabcols <- colnames(rcax_parse(rcax_GET("ca", GETargs$key, query = tmp, ...), TRUE)[[GETargs$recordloc]])
+    if(!all(names(flist) %in% tabcols)){
+      badcols <- names(flist)[!(names(flist) %in% tabcols)]
+      stop(paste("Not all flist names appear in the table. The bad names are:", paste0(badcols, collapse=", "), "\n Use type='colnames' to print the column names."), call. = FALSE)
+    }
+  }
+
   # set up query list
   query_list <- list(table_id = GETargs$table_id)
   if(!is.null(qlist)) query_list <- c(query_list, qlist)
-  if(!is.null(flist)) query_list <- c(query_list, list(filter=rcax_filter(flist)))
   # if just returning colnames, set limit to 1
-  if(type=="colnames") query_list$limit <- 1
+  if(type=="colnames") 
+    query_list$limit <- 1
+  else
+    if(!is.null(flist)) query_list <- c(query_list, list(filter=rcax_filter(flist)))
 
   # Make API call
   tab <- rcax_parse(rcax_GET("ca", GETargs$key, query=query_list, ...), GETargs$parse)

README.md

@@ -5,23 +5,33 @@ rCAX <img src="man/figures/logo.png" align="right" width="20%" />
 
 ## Installation
 
-Install the latest GitHub release
+Install the latest GitHub release. You only need to do this once.
 
 ```r
+install.packages("remotes") # needed for the next line
 remotes:::install_github("nwfsc-math-bio/rCAX@*release")
 ```
 
 ## 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).
+### Set up your API key
 
-Read the [Basic functions vignette](https://nwfsc-math-bio.github.io/rCAX/articles/basics.html) to get started. There are two main functions `rcax_nosa()` and `rcax_tables()`. `rcax_nosa()` downloads a NOSA table. `rcax_tables()` downloads the CAX table names and ids.
+First you need to get a pull api key from StreamNet. Once you have a key, run 
+```
+install.packages("usethis") # needed for the next line
+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).
+
+### Download a table
+
+Read the [Basic functions vignette](https://nwfsc-math-bio.github.io/rCAX/articles/basics.html) to get started and see examples.
 
-To filter (subset) the query, you use a filter list and passed into the table functions as `flist`. Example, to retrieve only NOSA data for popid 7, use
+For example, to retrieve the NOSA data for popid 7, use
 ```
 library(rCAX)
 fl <- list(popid=7)
-a <- rcax_nosa(flist=fl)
+a <- rcax_nosa_xport(flist=fl)
 ```
 
 ## Contributing

docs/pkgdown.yml

@@ -6,7 +6,7 @@ articles:
   api_get: api_get.html
   basics: basics.html
   terms: terms.html
-last_built: 2022-12-06T19:51Z
+last_built: 2022-12-07T00:38Z
 urls:
   reference: https://nwfsc-math-bio.github.io/rCAX/reference
   article: https://nwfsc-math-bio.github.io/rCAX/articles