In ices-tools-prod/icesSAG: Stock Assessment Graphs Database Web Services

-blue.svg)

CRAN status:

icesSAG

icesSAG provides R functions that access the web services of the ICES Stock Assessment Graphs database.

icesSAG is implemented as an R package and is currently hosted on r-universe and available on CRAN.

Installation

The stable version of icesSAG can be installed from CRAN using the install.packages command:

install.packages("icesSAG", repos = "https://cloud.r-project.org")

or a potentially more recent, but less stable version installed from r-universe:

install.packages("icesSAG", repos = "https://ices-tools-prod.r-universe.dev")

Usage

For a summary of the package:

library(icesSAG)
?icesSAG

Examples

options(icesSAG.messages = FALSE)
options(icesSAG.use_token = FALSE)
library(icesSAG)
library(ggplot2)

To download the summary data for all sandeel stocks published in 2018 use:

summary_data <- getSAG(stock = "sandeel", year = 2023)
head(summary_data)
ggplot(summary_data[complete.cases(summary_data[c("Year", "recruitment")]),],
       aes(x=Year, y=recruitment, group = fishstock, colour = fishstock)) +
    geom_line()

verbose web service calls

If you want to see all the web service calls being made set this option

sag_messages(TRUE)

The result will be

codKeys <- findAssessmentKey("cod", year = 2017)

which allows you to investigate the actual web service data if you are interested: https://sag.ices.dk/SAG_API/api/StockList?year=2017

Authorised access via tokens

ICES provides public access to the results of published stock assessments. If you are an ICES stock assessor and wish to access unpublished results, or to upload your results, this can be done using token authentication.

This is easy to set up, simply run the following line and all future requests to the SAG database will be authenticated.

sag_use_token(TRUE)

uploading data

To upload the results of a stock assessment to SAG you must provide two pieces of information, Stock information, such as stock code, assessment year and reference points, and yearly results, such as landings and estimated fishing mortality. There are two helper functions to create the required objects.

stockInfo()

returns a list (it requires a stock code, assessment year and contact email as a minimum), with the correctly named elements. And,

stockFishdata()

returns a data.frame (it requires year as default) with the correctly named columns

A simple (almost) minimal example is:

sag_messages(FALSE)

info <-
  stockInfo(
    StockCode = "whg.27.7a",
    AssessmentYear = 2021,
    ContactPerson = "[e-mail]",
    StockCategory = 3,
    Purpose = "Unofficial",
    ModelType = "A",
    ModelName = "XSA"
  )
fishdata <- stockFishdata(1950:2020)

# simulate some landings for something a bit intesting
set.seed(1232)
fishdata$Landings <- 10^6 * exp(cumsum(cumsum(rnorm(nrow(fishdata), 0, 0.1))))

# you can create an XML file to upload yourself
xml <- createSAGxml(info, fishdata)
# here we use a temporary file to store the XML, but you can safe this to your output or report folder
tempfile <- tempfile(fileext = ".xml")
cat(xml, file = tempfile)

# this file can then be uploaded using the SAG webservices
key <- uploadStock(tempfile, upload = TRUE)

# if you want to just check the file and not upload:
uploadStock(tempfile, upload = FALSE)

You can check that the data was uploaded by searching for our stock. Note you will need to make sure the icesSAG.use_token option is set to TRUE

sag_use_token(TRUE)
findAssessmentKey('whg.27.7a', 2020, full = TRUE)

Displaying graphs

We can also look at the landings graph created from the data that were uploaded, NOTE you may need to modify the settings at sag.ices.dk.

plot(getLandingsGraph(key))

or download all four summary graphs and display them in a 2x2 grid.

graphs <- getSAGGraphs(key)
plot(graphs)

References

ICES Stock Assessment Graphs database: https://sg.ices.dk

ICES Stock Assessment Graphs web services: https://sg.ices.dk/webservices.aspx

Development

icesSAG is developed openly on GitHub.

Feel free to open an issue there if you encounter problems or have suggestions for future versions.

The current development version can be installed using:

library(devtools)
install_github("ices-tools-prod/icesSAG@development")

ices-tools-prod/icesSAG documentation built on June 13, 2025, 12:51 p.m.