New functions findKey() and getSAG()

NAMESPACE

@@ -1,9 +1,11 @@
 # Generated by roxygen2: do not edit by hand
 
 S3method(plot,ices_standardgraph)
+export(findKey)
 export(getFishStockReferencePoints)
 export(getLandingsGraph)
 export(getListStocks)
+export(getSAG)
 export(getSummaryTable)
 importFrom(RCurl,basicTextGatherer)
 importFrom(RCurl,curlPerform)

NEWS

@@ -1,8 +1,13 @@
 --------------------------------------------------------------------------------
-icesSAG 1.1-0 (2016-08-21)
+icesSAG 1.1-0 (2016-10-29)
 --------------------------------------------------------------------------------
-o New argument 'stock' in functions getListStocks(), getSummaryTable(), and
-  getFishStockReferencepoints().
+o Added function findKey() to look up a unique stock list key.
+
+o Added function getSAG() to import summary results and reference points,
+  without finding a lookup key first.
+
+o Changed argument in functions getSummaryTable() and
+  getFishStockReferencepoints() from 'year' to 'key'.
 
 o Improved XML parsing, so both leading and trailing white space is removed.
 

R/findKey.R

@@ -0,0 +1,48 @@
+#' Find a Key
+#'
+#' Find a lookup key corresponding to a stock in a given assessment year.
+#'
+#' @param stock a stock name, e.g. cod-347d, or NULL to process all stocks.
+#' @param year the assessment year, e.g. 2015, or 0 to process all years.
+#' @param published whether to include only years where status is "Published".
+#' @param full whether to return a data frame with all stock list columns.
+#'
+#' @return A vector of keys (default) or a data frame if full is TRUE.
+#'
+#' @seealso
+#' \code{\link{getListStocks}} gets a list of stocks.
+#'
+#' \code{\link{icesSAG-package}} gives an overview of the package.
+#'
+#' @author Arni Magnusson.
+#'
+#' @examples
+#' summary <- getSAG("cod-347d", 2015)
+#' refpts <- getSAG("cod-347d", 2015, "refpts")
+#'
+#' @export
+
+findKey <- function(stock, year, published = TRUE, full = FALSE)
+{
+  # check web services are running
+  if (!checkSAGWebserviceOK()) return (FALSE)
+
+  # get stock list
+  url <-
+    sprintf(
+      "https://standardgraphs.ices.dk/StandardGraphsWebServices.asmx/getListStocks?year=%i",
+      year)
+  out <- lapply(url,
+                function(u) {
+                  out <- curlSAG(u)
+                  parseSAG(out)
+                })
+  out <- do.call(rbind, out)
+
+  # filter and format
+  if (!is.null(stock)) out <- out[out$FishStockName %in% stock,]
+  if (published) out <- out[out$Status == "Published",]
+  if (!full) out <- out$key
+
+  out
+}

R/getFishStockReferencePoints.R

@@ -7,9 +7,11 @@
 #' @return A data frame.
 #'
 #' @seealso
-#' \code{\link{getListStocks}} gets a list of stocks.
+#' \code{\link{getSAG}} supports querying many years and quarters in one
+#'   function call.
 #'
-#' \code{\link{getSummaryTable}} gets a summary table of historical stock size.
+#' \code{\link{getListStocks}} and \code{\link{getSummaryTable}} get a list of
+#'   stocks and summary results.
 #'
 #' \code{\link{icesSAG-package}} gives an overview of the package.
 #'

R/getSAG.R

@@ -0,0 +1,61 @@
+#' Get Any SAG Data
+#'
+#' This function combines the functionality of getListStocks,
+#' getFishStockReferencePoints, and getSummaryTable.
+#' It supports querying many years and quarters in one function call.
+#'
+#' @param stock a stock name, e.g. cod-347d, or NULL to process all stocks.
+#' @param year the assessment year, e.g. 2015, or 0 to process all years.
+#' @param data the data of interest, either "summary" or "refpts"
+#' @param combine whether to combine the list output to a data frame.
+#'
+#' @note Only years with "Published" status are returned.
+#'
+#' @return A data frame (default) or a list if \code{combine} is \code{TRUE}.
+#'
+#' @seealso
+#' \code{\link{getListStocks}}, \code{\link{getSummaryTable}}, and
+#'   \code{\link{getFishStockReferencePoints}} get a list of stocks, summary
+#'   results, and reference points.
+#'
+#' \code{\link{findKey}} finds lookup keys.
+#'
+#' \code{\link{icesSAG-package}} gives an overview of the package.
+#'
+#' @author Arni Magnusson.
+#'
+#' @examples
+#' summary <- getSAG("cod-347d", 2015)
+#' refpts <- getSAG("cod-347d", 2015, "refpts")
+#'
+#' @export
+
+getSAG <- function(stock, year, data = "summary", combine = TRUE) {
+  # select web service operation and parser
+  data <- match.arg(data, c("summary", "refpts"))
+  operation <- switch(data,
+                      summary = "getSummaryTable",
+                      refpts = "getFishStockReferencePoints")
+  parseFunction <- switch(data,
+                          summary = parseSummary,
+                          refpts = parseSAG)
+
+  # check web services are running
+  if (!checkSAGWebserviceOK()) return (FALSE)
+
+  # find lookup key
+  key <- findKey(stock, year)
+
+  # get data requested by user
+  url <-
+    sprintf(
+      "https://standardgraphs.ices.dk/StandardGraphsWebServices.asmx/%s?key=%i",
+      operation, key)
+  out <- lapply(url,
+                function(u) {
+                  out <- curlSAG(u)
+                  parseFunction(out)
+                })
+  if (combine) out <- do.call(rbind, out)
+  out
+}

R/getSummaryTable.R

@@ -1,15 +1,18 @@
 #' Get a Summary Table of Historical Stock Size
 #'
-#' Get a summary table of historical stock size, recruitment, and fishing pressure.
+#' Get summary results of historical stock size, recruitment, and fishing
+#' pressure.
 #'
 #' @param key the unique identifier of the stock assessment
 #'
 #' @return A data frame.
 #'
 #' @seealso
-#' \code{\link{getListStocks}} gets a list of stocks.
+#' \code{\link{getSAG}} supports querying many years and quarters in one
+#'   function call.
 #'
-#' \code{\link{getFishStockReferencePoints}} gets biological reference points.
+#' \code{\link{getListStocks}} and \code{\link{getFishStockReferencePoints}} get
+#'   a list of stocks and reference points.
 #'
 #' \code{\link{icesSAG-package}} gives an overview of the package.
 #'

R/icesSAG-package.R

@@ -13,9 +13,14 @@
 #' @details
 #' \emph{Get dataset:}
 #' \tabular{ll}{
-#'   \code{\link{getListStocks}}               \tab list of stocks\cr
-#'   \code{\link{getSummaryTable}}             \tab historical stock size\cr
-#'   \code{\link{getFishStockReferencePoints}} \tab reference points
+#'   \code{\link{getSummaryTable}}             \tab summary results\cr
+#'   \code{\link{getFishStockReferencePoints}} \tab reference points\cr
+#'   \code{\link{getSAG}}                      \tab any data
+#' }
+#' \emph{Look up codes:}
+#' \tabular{ll}{
+#'   \code{\link{findKey}}       \tab find key\cr
+#'   \code{\link{getListStocks}} \tab list of stocks
 #' }
 #'
 #' @author Colin Millar, Scott Large, and Arni Magnusson.