| Title: | Stock Assessment Graphs Database Web Services |
|---|---|
| Description: | R interface to access the web services of the ICES Stock Assessment Graphs database <https://sg.ices.dk>. |
| Authors: | Colin Millar [aut, cre], Scott Large [aut], Arni Magnusson [aut], Carlos Pinto [aut], Laura Andreea Petre [aut] |
| Maintainer: | Colin Millar <[email protected]> |
| License: | GPL (>= 2) |
| Version: | 1.5.0 |
| Built: | 2024-10-24 09:15:04 UTC |
| Source: | https://github.com/ices-tools-prod/icesSAG |
R interface to access the web services of the ICES Stock Assessment Graphs database.
Get dataset:
getSummaryTable |
summary results |
getFishStockReferencePoints |
reference points |
getSAG |
any data |
Look up codes:
findAssessmentKey |
find assessment key |
getListStocks |
list of stocks |
Colin Millar, Scott Large, Arni Magnusson, Carlos Pinto and Laura Andreea Petre.
ICES Stock Assessment Graphs database: http://sg.ices.dk.
ICES Stock Assessment Graphs web services: http://sg.ices.dk/webservices.aspx.
Useful links:
Report bugs at https://github.com/ices-tools-prod/icesSAG/issues
Convert between R data (a list and a data.frame) and the XML format required for uploading data to the SAG database.
createSAGxml(info, fishdata) readSAGxml(file)createSAGxml(info, fishdata) readSAGxml(file)
info |
a list of stock information |
fishdata |
a data frame of fish data |
file |
an xml file name |
Either a list containing info and fishdata, or a string containing the xml file.
stockInfo creates a list of stock information.
stockFishdata creates a data frame of fish stock summary data.
info <- stockInfo(StockCode = "cod.27.347d", AssessmentYear = 2017, StockCategory = 1, ModelType = "A", ModelName = "SCA", ContactPerson = "[email protected]") fishdata <- stockFishdata(Year = 1990:2017, Catches = 100) xmlfile <- createSAGxml(info, fishdata) out <- readSAGxml(xmlfile)info <- stockInfo(StockCode = "cod.27.347d", AssessmentYear = 2017, StockCategory = 1, ModelType = "A", ModelName = "SCA", ContactPerson = "[email protected]") fishdata <- stockFishdata(Year = 1990:2017, Catches = 100) xmlfile <- createSAGxml(info, fishdata) out <- readSAGxml(xmlfile)
Find a lookup key corresponding to a stock in a given assessment year.
findAssessmentKey( stock = NULL, year = 0, published = TRUE, regex = TRUE, full = FALSE )findAssessmentKey( stock = NULL, year = 0, published = TRUE, regex = TRUE, full = FALSE )
stock |
a stock name, e.g. cod-347d, or cod to find all cod stocks, or NULL (default) to process all stocks. |
year |
the assessment year, e.g. 2015, or 0 to process all years. |
published |
whether to include only years where status is "Published" (applies only when non-secure web services are in use, secure web service always returns unpublished stocks). |
regex |
whether to match the stock name as a regular expression. |
full |
whether to return a data frame with all stock list columns. |
A vector of keys (default) or a data frame if full is TRUE.
Arni Magnusson and Colin Millar.
getListStocks gets a list of stocks.
icesSAG-package gives an overview of the package.
## Not run: findAssessmentKey("had.27.46a20", 2023, full = TRUE) ## End(Not run)## Not run: findAssessmentKey("had.27.46a20", 2023, full = TRUE) ## End(Not run)
Get custom columns, such as alternative biomass series or Fproxy reference points for records in the SAG database.
getCustomColumns(assessmentKey, ...)getCustomColumns(assessmentKey, ...)
assessmentKey |
the unique identifier of the stock assessment |
... |
arguments passed to |
A data frame.
Colin Millar.
getSAG supports querying many years and quarters in one
function call.
getListStocks and getFishStockReferencePoints get
a list of stocks and reference points.
icesSAG-package gives an overview of the package.
## Not run: assessmentKey <- findAssessmentKey("bli.27.5a14") customs <- getCustomColumns(assessmentKey) head(customs) ## End(Not run)## Not run: assessmentKey <- findAssessmentKey("bli.27.5a14") customs <- getCustomColumns(assessmentKey) head(customs) ## End(Not run)
Get biological reference points for all stocks in a given assessment year.
getFishStockReferencePoints(assessmentKey, ...)getFishStockReferencePoints(assessmentKey, ...)
assessmentKey |
the unique identifier of the stock assessment |
... |
arguments passed to |
A data frame.
Colin Millar.
getSAG supports querying many years and quarters in one
function call.
getListStocks and getSummaryTable get a list of
stocks and summary results.
icesSAG-package gives an overview of the package.
## Not run: assessmentKey <- findAssessmentKey("cod.27.21", year = 2023) refpts <- getFishStockReferencePoints(assessmentKey) refpts # To get all reference points in a given assessment year: keys2022 <- findAssessmentKey(year = 2022, full = TRUE) keys2022 <- keys2022[keys2022$Purpose == "Advice",] refpts2022 <- getFishStockReferencePoints(keys2022$AssessmentKey) refpts2022 ## End(Not run)## Not run: assessmentKey <- findAssessmentKey("cod.27.21", year = 2023) refpts <- getFishStockReferencePoints(assessmentKey) refpts # To get all reference points in a given assessment year: keys2022 <- findAssessmentKey(year = 2022, full = TRUE) keys2022 <- keys2022[keys2022$Purpose == "Advice",] refpts2022 <- getFishStockReferencePoints(keys2022$AssessmentKey) refpts2022 ## End(Not run)
Get a list of the most recent advice for all fish stocks.
getLatestStockAdviceList(...)getLatestStockAdviceList(...)
... |
arguments passed to |
A data frame.
Colin Millar, Scott Large, and Arni Magnusson.
getSummaryTable gets a summary table of historical stock size.
getFishStockReferencePoints gets biological reference points.
icesSAG-package gives an overview of the package.
## Not run: stocks <- getLatestStockAdviceList() ## End(Not run)## Not run: stocks <- getLatestStockAdviceList() ## End(Not run)
Get a list of fish stocks for a given assessment year.
getListStocks(year, stock = NULL, modifiedAfter = NULL, ...)getListStocks(year, stock = NULL, modifiedAfter = NULL, ...)
year |
the assessment year, e.g. 2015, or 0 to process all years. |
stock |
a stock name, e.g. lin.27.5a. |
modifiedAfter |
date-time parameter in the format "YYYY/MM/DD". If set will only return stocks assessments modified after the provided date. |
... |
arguments passed to |
A data frame.
Colin Millar.
getSummaryTable gets a summary table of historical stock size.
getFishStockReferencePoints gets biological reference points.
icesSAG-package gives an overview of the package.
## Not run: stocks <- getListStocks(2023) nshad <- getListStocks(stock = "had.27.46a20") ## End(Not run)## Not run: stocks <- getListStocks(2023) nshad <- getListStocks(stock = "had.27.46a20") ## End(Not run)
This function combines the functionality of getListStocks,
getFishStockReferencePoints, getSummaryTable
and getStockDownloadData.
It supports querying many stocks and years in one function call.
getSAG(stock, year, data = "summary", combine = TRUE, purpose = "Advice")getSAG(stock, year, data = "summary", combine = TRUE, purpose = "Advice")
stock |
a stock name, e.g. cod-347d, or cod to find all cod stocks, or NULL to process all stocks. |
year |
the assessment year, e.g. 2015, or 0 to process all years. |
data |
the data of interest, either "summary", "refpts" or "source". |
combine |
whether to combine the list output to a data frame. |
purpose |
the purpose of the entry, options are "Advice", "Bench", "InitAdvice", default is "Advice". |
A data frame (default) or a list if combine is TRUE.
Only years with "Published" status are returned.
Colin Millar.
getListStocks, getSummaryTable,
getFishStockReferencePoints, and
getStockDownloadData get a list of stocks, summary
results, reference points, and all data including custom columns.
findAssessmentKey finds lookup keys.
icesSAG-package gives an overview of the package.
## Not run: summary <- getSAG("had.27.46a20", 2022) refpts <- getSAG("had.27.46a20", 2022, "refpts") cod_summary <- getSAG("cod", 2022) cod_refpts <- getSAG("cod", 2015:2016, "refpts") cod_data <- getSAG("cod", 2017, "source-data") ## End(Not run)## Not run: summary <- getSAG("had.27.46a20", 2022) refpts <- getSAG("had.27.46a20", 2022, "refpts") cod_summary <- getSAG("cod", 2022) cod_refpts <- getSAG("cod", 2015:2016, "refpts") cod_data <- getSAG("cod", 2017, "source-data") ## End(Not run)
Get summary graphs of catches, recruitment, fishing pressure, and spawning stock biomass.
getSAGGraphs(assessmentKey, ...)getSAGGraphs(assessmentKey, ...)
assessmentKey |
the unique identifier of the stock assessment |
... |
to allow scope for back compatibility |
An array representing a bitmap.
Colin Millar and Scott Large.
getListStocks gets a list of stocks.
getFishStockReferencePoints gets biological reference points.
icesSAG-package gives an overview of the package.
## Not run: assessmentKey <- findAssessmentKey("cod", 2015) graphs <- getSAGGraphs(assessmentKey[1]) plot(graphs) # note this stock only has one graph see: # http://standardgraphs.ices.dk/ViewCharts.aspx?key=8309 ## End(Not run)## Not run: assessmentKey <- findAssessmentKey("cod", 2015) graphs <- getSAGGraphs(assessmentKey[1]) plot(graphs) # note this stock only has one graph see: # http://standardgraphs.ices.dk/ViewCharts.aspx?key=8309 ## End(Not run)
List all possible chart settings for each chart type (0 = general, 1 = Landings, ...).
getSAGTypeGraphs(...) getSAGTypeSettings(SAGChartKey, ...)getSAGTypeGraphs(...) getSAGTypeSettings(SAGChartKey, ...)
... |
arguments passed to |
SAGChartKey |
the type identifier of the SAG chart, e.g. 0, 1, 2, ... |
a data frame with SAG chart type IDs and settings IDs.
## Not run: getSAGTypeGraphs() getSAGTypeSettings(0)[-4] ## End(Not run)## Not run: getSAGTypeGraphs() getSAGTypeSettings(0)[-4] ## End(Not run)
details
getSAGSettingsForAStock(assessmentKey, ...) setSAGSettingForAStock( assessmentKey, chartKey, settingKey, settingValue, copyNextYear, ... )getSAGSettingsForAStock(assessmentKey, ...) setSAGSettingForAStock( assessmentKey, chartKey, settingKey, settingValue, copyNextYear, ... )
assessmentKey |
the unique identifier of the stock assessment |
... |
arguments passed to |
chartKey |
the type identifier of the SAG chart, e.g. 0, 1, 2, ... |
settingKey |
the type identifier of the SAG chart setting, e.g. 0, 1, 2, ... |
settingValue |
the vale of the setting |
copyNextYear |
should the settings be copied to next year (TRUE) or not (FALSE) |
A data frame with SAG chart type IDs, settings IDs and setting values.
## Not run: key <- findAssessmentKey("cod.21.1", 2017) graphs <- getSAGGraphs(key[1]) plot(graphs) getSAGSettingsForAStock(key [1]) chart1 <- getLandingsGraph(key [1]) setSAGSettingForAStock(key [2], 1, 1, "Catches of cod.21.1 in 2017", FALSE) setSAGSettingForAStock(key [2], 1, 11, 10, FALSE) plot(chart1) chart2 <- getSpawningStockBiomassGraph(key [1]) plot(chart2) setSAGSettingForAStock(key [1], 4, 1, "SSB of cod.21.1 in 2017", FALSE) plot(chart2) ## End(Not run)## Not run: key <- findAssessmentKey("cod.21.1", 2017) graphs <- getSAGGraphs(key[1]) plot(graphs) getSAGSettingsForAStock(key [1]) chart1 <- getLandingsGraph(key [1]) setSAGSettingForAStock(key [2], 1, 1, "Catches of cod.21.1 in 2017", FALSE) setSAGSettingForAStock(key [2], 1, 11, 10, FALSE) plot(chart1) chart2 <- getSpawningStockBiomassGraph(key [1]) plot(chart2) setSAGSettingForAStock(key [1], 4, 1, "SSB of cod.21.1 in 2017", FALSE) plot(chart2) ## End(Not run)
Get a graph of stock assessment output, e.g., historical stock size, recruitment, and fishing pressure.
getLandingsGraph(assessmentKey, ...) getRecruitmentGraph(assessmentKey, ...) getFishingMortalityGraph(assessmentKey, ...) getSpawningStockBiomassGraph(assessmentKey, ...) getFishMortality(assessmentKey, ...) getstock_recruitment(assessmentKey, ...) getYSSB(assessmentKey, ...) getSSBHistoricalPerformance(assessmentKey, ...) getFishingMortalityHistoricalPerformance(assessmentKey, ...) getRecruitmentHistoricalPerformance(assessmentKey, ...) getStockStatusTable(assessmentKey, ...)getLandingsGraph(assessmentKey, ...) getRecruitmentGraph(assessmentKey, ...) getFishingMortalityGraph(assessmentKey, ...) getSpawningStockBiomassGraph(assessmentKey, ...) getFishMortality(assessmentKey, ...) getstock_recruitment(assessmentKey, ...) getYSSB(assessmentKey, ...) getSSBHistoricalPerformance(assessmentKey, ...) getFishingMortalityHistoricalPerformance(assessmentKey, ...) getRecruitmentHistoricalPerformance(assessmentKey, ...) getStockStatusTable(assessmentKey, ...)
assessmentKey |
the unique identifier of the stock assessment |
... |
to allow scope for back compatibility |
An array representing a bitmap.
getListStocks gets a list of stocks.
getFishStockReferencePoints gets biological reference points.
icesSAG-package gives an overview of the package.
## Not run: assessmentKeys <- findAssessmentKey("had", 2015) landings_img <- getLandingsGraph(assessmentKeys[1]) plot(landings_img) landings_plots <- getLandingsGraph(assessmentKeys) plot(landings_plots) ## End(Not run)## Not run: assessmentKeys <- findAssessmentKey("had", 2015) landings_img <- getLandingsGraph(assessmentKeys[1]) plot(landings_img) landings_plots <- getLandingsGraph(assessmentKeys) plot(landings_plots) ## End(Not run)
Get a copy of the source data for the specified stocks.
getStockDownloadData(assessmentKey, ...)getStockDownloadData(assessmentKey, ...)
assessmentKey |
the unique identifier of the stock assessment, can be a vector |
... |
arguments passed to |
A data frame.
Colin Millar.
getSAG supports querying many years in one function call.
getListStocks and getFishStockReferencePoints get
a list of stocks and reference points.
icesSAG-package gives an overview of the package.
## Not run: assessmentKey <- findAssessmentKey("cod-2224", year = 2016) sourcedat <- getStockDownloadData(assessmentKey) head(sourcedat[[1]]) ## End(Not run)## Not run: assessmentKey <- findAssessmentKey("cod-2224", year = 2016) sourcedat <- getStockDownloadData(assessmentKey) head(sourcedat[[1]]) ## End(Not run)
Get summary results of historical stock size, recruitment, and fishing pressure.
getStockStatusValues(assessmentKey, ...)getStockStatusValues(assessmentKey, ...)
assessmentKey |
the unique identifier of the stock assessment |
... |
arguments passed to |
A data frame.
Colin Millar.
getSAG supports querying many years and quarters in one
function call.
getListStocks and getFishStockReferencePoints get
a list of stocks and reference points.
icesSAG-package gives an overview of the package.
## Not run: assessmentKey <- findAssessmentKey("had.27.46a20", year = 2022) status <- getStockStatusValues(assessmentKey) status ## End(Not run)## Not run: assessmentKey <- findAssessmentKey("had.27.46a20", year = 2022) status <- getStockStatusValues(assessmentKey) status ## End(Not run)
Get summary results of historical stock size, recruitment, and fishing pressure.
getSummaryTable(assessmentKey, ...)getSummaryTable(assessmentKey, ...)
assessmentKey |
the unique identifier of the stock assessment |
... |
arguments passed to |
A data frame.
Colin Millar.
getSAG supports querying many years and quarters in one
function call.
getListStocks and getFishStockReferencePoints get
a list of stocks and reference points.
icesSAG-package gives an overview of the package.
## Not run: assessmentKey <- findAssessmentKey("had.27.46a20", year = 2022) sumtab <- getSummaryTable(assessmentKey) head(sumtab) ## End(Not run)## Not run: assessmentKey <- findAssessmentKey("had.27.46a20", year = 2022) sumtab <- getSummaryTable(assessmentKey) head(sumtab) ## End(Not run)
Get a url, optionally using an ICES authentication token
ices_get( url, retry = TRUE, quiet = !getOption("icesSAG.messages"), verbose = FALSE, content = TRUE, use_token = getOption("icesSAG.use_token") ) ices_get_cached( url, retry = TRUE, quiet = !getOption("icesSAG.messages"), verbose = FALSE, content = TRUE, use_token = getOption("icesSAG.use_token") )ices_get( url, retry = TRUE, quiet = !getOption("icesSAG.messages"), verbose = FALSE, content = TRUE, use_token = getOption("icesSAG.use_token") ) ices_get_cached( url, retry = TRUE, quiet = !getOption("icesSAG.messages"), verbose = FALSE, content = TRUE, use_token = getOption("icesSAG.use_token") )
url |
the url to get. |
retry |
should the get request be retried if first attempt fails? default TRUE. |
quiet |
should all messages be suppressed, default FALSE. |
verbose |
should verbose output form the http request be returned? default FALSE. |
content |
should content be returned, or the full http response? default TRUE, i.e. content is returned by default. |
use_token |
should an authentication token be sent with the request? default is the value of the option icesSAG.use_token. |
content or an http response.
ices_get_cached(): cached version of ices_get
sag_api builds a SAG web service url.
icesSAG-package gives an overview of the package.
## Not run: ices_get(sag_api("StockList", year = 2022)) ## End(Not run)## Not run: ices_get(sag_api("StockList", year = 2022)) ## End(Not run)
Post to a url using an ICES authentication token
ices_post(url, body = list(), retry = TRUE, verbose = FALSE, use_token = TRUE)ices_post(url, body = list(), retry = TRUE, verbose = FALSE, use_token = TRUE)
url |
the url to get. |
body |
a list of named arguments to be sent as the body of the post request. |
retry |
should the get request be retried if first attempt fails? default TRUE. |
verbose |
should verbose output form the http request be returned? default FALSE. |
use_token |
should an authentication token be sent with the request? default is TRUE. |
content or an http response.
sag_api builds a SAG web service url.
icesSAG-package gives an overview of the package.
## Not run: ices_get(sag_api("StockList", year = 2022)) ## End(Not run)## Not run: ices_get(sag_api("StockList", year = 2022)) ## End(Not run)
utility to build a url with optional query arguments
sag_api(service, ...)sag_api(service, ...)
service |
the name of the service |
... |
name arguments will be added as queries |
a complete url as a character string
sag_api("hi", bye = 21) sag_api("StockList", year = 2021)sag_api("hi", bye = 21) sag_api("StockList", year = 2021)
There are two options of interest, 1) switch on or off the use off authenticated web service calls, and 2) switch on or off the display of messages to the console.
sag_use_token(value) sag_messages(value)sag_use_token(value) sag_messages(value)
value |
TRUE or FALSE |
invisible return of the old value.
## Not run: sag_use_token(TRUE) sag_messages(TRUE) ## End(Not run)## Not run: sag_use_token(TRUE) sag_messages(TRUE) ## End(Not run)
This function is a wrapper to data.frame(...) in which the names are forced to match with
the names required for the SAG database. See http://dome.ices.dk/datsu/selRep.aspx?Dataset=126
for more details.
stockFishdata(Year, ...)stockFishdata(Year, ...)
Year |
a vector of years. |
... |
additional information, e.g. Recruitment, StockSize, Landings, ... |
A data.frame, where all names are valid column names in the SAG database.
Colin Millar.
stockFishdata(Year = 1990:2017, Catches = 100)stockFishdata(Year = 1990:2017, Catches = 100)
This function is a wrapper to list(...) in which the names are forced to match with
the names required for the SAG database. See http://dome.ices.dk/datsu/selRep.aspx?Dataset=126
for more details.
stockInfo( StockCode, AssessmentYear, ContactPerson, StockCategory, Purpose = "Advice", ModelType, ModelName, ... )stockInfo( StockCode, AssessmentYear, ContactPerson, StockCategory, Purpose = "Advice", ModelType, ModelName, ... )
StockCode |
a stock name, e.g. cod-347d. |
AssessmentYear |
the assessment year, e.g. 2015. |
ContactPerson |
the email for the person responsible for uploading the stock data. |
StockCategory |
Category of the assessment used (see below) |
Purpose |
the purpose of the entry, options are "Advice", "Bench", "InitAdvice", default is "Advice". |
ModelType |
the type of the model used (see below for links to more information) |
ModelName |
the name (acronym) of the model used if available (see below for links to more information) |
... |
additional information, e.g. BMGT, FMSY, RecruitmentAge, ... |
A named sag.list, inheriting from a list, where all names are valid column names in the SAG database.
Colin Millar.
Links to the relevant ICES vocabularies list are here StockCode: https://vocab.ices.dk/?ref=357 StockCategory: https://vocab.ices.dk/?ref=1526 Purpose: https://vocab.ices.dk/?ref=1516 ModelType: https://vocab.ices.dk/?ref=1524 ModelName: https://vocab.ices.dk/?ref=1525
Link to the relevant format description is https://datsu.ices.dk/web/selRep.aspx?Dataset=126
info <- stockInfo(StockCode = "cod.27.47d20", AssessmentYear = 2017, StockCategory = 1, ModelType = "A", ModelName = "SCA", ContactPerson = "[email protected]") info info$mistake <- "oops" info # should have gotten a warning message ## Not run: # use icesVocab to list valid codes etc. library(icesVocab) # print the list of valid stock codes stock.codes <- getCodeList("ICES_StockCode") stock.codes[1:10,1:2] # print the list of assessment model types in the ICES vocabulary model.types <- getCodeList("AssessmentModelType") model.types[1:2] # print the list of assessment model names in the ICES vocabulary model.names <- getCodeList("AssessmentModelName") model.names$Key ## End(Not run)info <- stockInfo(StockCode = "cod.27.47d20", AssessmentYear = 2017, StockCategory = 1, ModelType = "A", ModelName = "SCA", ContactPerson = "[email protected]") info info$mistake <- "oops" info # should have gotten a warning message ## Not run: # use icesVocab to list valid codes etc. library(icesVocab) # print the list of valid stock codes stock.codes <- getCodeList("ICES_StockCode") stock.codes[1:10,1:2] # print the list of assessment model types in the ICES vocabulary model.types <- getCodeList("AssessmentModelType") model.types[1:2] # print the list of assessment model names in the ICES vocabulary model.names <- getCodeList("AssessmentModelName") model.names$Key ## End(Not run)