diff --git a/NAMESPACE b/NAMESPACE index 4875852..d218ca9 100644 --- a/NAMESPACE +++ b/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) diff --git a/NEWS b/NEWS index ed44386..6bdd890 100644 --- a/NEWS +++ b/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. diff --git a/R/findKey.R b/R/findKey.R new file mode 100644 index 0000000..ed2a568 --- /dev/null +++ b/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 +} diff --git a/R/getFishStockReferencePoints.R b/R/getFishStockReferencePoints.R index 1458c76..857ab41 100644 --- a/R/getFishStockReferencePoints.R +++ b/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. #' diff --git a/R/getSAG.R b/R/getSAG.R new file mode 100644 index 0000000..ad727de --- /dev/null +++ b/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 +} diff --git a/R/getSummaryTable.R b/R/getSummaryTable.R index ea4aad2..7c2f2d3 100644 --- a/R/getSummaryTable.R +++ b/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. #' diff --git a/R/icesSAG-package.R b/R/icesSAG-package.R index 73ecfc0..2fea8f9 100644 --- a/R/icesSAG-package.R +++ b/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. diff --git a/man/findKey.Rd b/man/findKey.Rd new file mode 100644 index 0000000..870721e --- /dev/null +++ b/man/findKey.Rd @@ -0,0 +1,37 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/findKey.R +\name{findKey} +\alias{findKey} +\title{Find a Key} +\usage{ +findKey(stock, year, published = TRUE, full = FALSE) +} +\arguments{ +\item{stock}{a stock name, e.g. cod-347d, or NULL to process all stocks.} + +\item{year}{the assessment year, e.g. 2015, or 0 to process all years.} + +\item{published}{whether to include only years where status is "Published".} + +\item{full}{whether to return a data frame with all stock list columns.} +} +\value{ +A vector of keys (default) or a data frame if full is TRUE. +} +\description{ +Find a lookup key corresponding to a stock in a given assessment year. +} +\examples{ +summary <- getSAG("cod-347d", 2015) +refpts <- getSAG("cod-347d", 2015, "refpts") + +} +\author{ +Arni Magnusson. +} +\seealso{ +\code{\link{getListStocks}} gets a list of stocks. + +\code{\link{icesSAG-package}} gives an overview of the package. +} + diff --git a/man/getFishStockReferencePoints.Rd b/man/getFishStockReferencePoints.Rd index 6d6c8ca..98d0d6a 100644 --- a/man/getFishStockReferencePoints.Rd +++ b/man/getFishStockReferencePoints.Rd @@ -28,9 +28,11 @@ refpts Colin Millar and Scott Large. } \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. } diff --git a/man/getSAG.Rd b/man/getSAG.Rd new file mode 100644 index 0000000..0327ce5 --- /dev/null +++ b/man/getSAG.Rd @@ -0,0 +1,46 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/getSAG.R +\name{getSAG} +\alias{getSAG} +\title{Get Any SAG Data} +\usage{ +getSAG(stock, year, data = "summary", combine = TRUE) +} +\arguments{ +\item{stock}{a stock name, e.g. cod-347d, or NULL to process all stocks.} + +\item{year}{the assessment year, e.g. 2015, or 0 to process all years.} + +\item{data}{the data of interest, either "summary" or "refpts"} + +\item{combine}{whether to combine the list output to a data frame.} +} +\value{ +A data frame (default) or a list if \code{combine} is \code{TRUE}. +} +\description{ +This function combines the functionality of getListStocks, +getFishStockReferencePoints, and getSummaryTable. +It supports querying many years and quarters in one function call. +} +\note{ +Only years with "Published" status are returned. +} +\examples{ +summary <- getSAG("cod-347d", 2015) +refpts <- getSAG("cod-347d", 2015, "refpts") + +} +\author{ +Arni Magnusson. +} +\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. +} + diff --git a/man/getSummaryTable.Rd b/man/getSummaryTable.Rd index 89d0dce..ef2ac3b 100644 --- a/man/getSummaryTable.Rd +++ b/man/getSummaryTable.Rd @@ -13,7 +13,8 @@ getSummaryTable(key) A data frame. } \description{ -Get a summary table of historical stock size, recruitment, and fishing pressure. +Get summary results of historical stock size, recruitment, and fishing +pressure. } \examples{ stocklist <- getListStocks(2015) @@ -29,9 +30,11 @@ attributes(sumtab)$notes Colin Millar and Scott Large. } \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. } diff --git a/man/icesSAG-package.Rd b/man/icesSAG-package.Rd index 3afc6be..7b6f3f5 100644 --- a/man/icesSAG-package.Rd +++ b/man/icesSAG-package.Rd @@ -12,9 +12,14 @@ for the Exploration of the Sea) Stock Assessment Graphs (SAG) database. \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{