icesSAG

Provides R functions that access the web services of the ICES Stock Assessment Graphs database to advance and share scientific understanding of marine ecosystems and the services they provide and to use this knowledge to generate state-of-the-art advice for meeting conservation, management, and sustainability goals.
https://github.com/ices-tools-prod/icessag

Category: Biosphere
Sub Category: Marine Life and Fishery

Last synced: about 18 hours ago
JSON representation

Repository metadata

R interface to Stock Assessment Graphs database web services

• Host: GitHub
• URL: https://github.com/ices-tools-prod/icessag
• Owner: ices-tools-prod
• Created: 2016-08-08T11:22:48.000Z (over 8 years ago)
• Default Branch: main
• Last Pushed: 2025-04-03T12:38:33.000Z (25 days ago)
• Last Synced: 2025-04-18T00:07:55.459Z (10 days ago)
• Language: R
• Homepage: https://sg.ices.dk/webservices.aspx
• Size: 719 KB
• Stars: 11
• Watchers: 7
• Forks: 7
• Open Issues: 84
• Releases: 11
• Metadata Files:
  • Readme: README.Rmd
  • Changelog: NEWS.md

README.Rmd

          ---
output:
  md_document:
    variant: gfm
---

![Project Status](https://www.repostatus.org/badges/latest/active.svg)
[![r-universe name](https://ices-tools-prod.r-universe.dev/badges/:name)](https://ices-tools-prod.r-universe.dev)
[![version number](https://ices-tools-prod.r-universe.dev/badges/icesSAG)](https://ices-tools-prod.r-universe.dev/icesSAG)
![branch version number](https://img.shields.io/badge/branch_version-`r packageDescription("icesSAG")$Version`-blue)
[![GitHub release](https://img.shields.io/github/release/ices-tools-prod/icesSAG.svg?maxAge=6000)]()
[![License](https://img.shields.io/badge/license-GPL%20(%3E%3D%202)-blue.svg)](https://www.gnu.org/licenses/gpl-3.0.en.html)

CRAN status:
[![CRAN_Status_Badge](https://www.r-pkg.org/badges/version/icesSAG)](https://cran.r-project.org/package=icesSAG)
![CRAN RStudio mirror downloads](https://cranlogs.r-pkg.org/badges/icesSAG)
![CRAN RStudio mirror downloads](https://cranlogs.r-pkg.org/badges/grand-total/icesSAG)

[](http://ices.dk)

### icesSAG

icesSAG provides R functions that access the
[web services](https://sg.ices.dk/webservices.aspx) of the [ICES](https://www.ices.dk)
[Stock Assessment Graphs](https://sg.ices.dk) database.

icesSAG is implemented as an [R](https://www.r-project.org) package and
is currently hosted on [r-universe](https://ices-tools-prod.r-universe.dev)
and available on [CRAN](https://cran.r-project.org/package=icesSAG).

### Installation


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

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

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

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

### Usage


For a summary of the package:

```r
library(icesSAG)
?icesSAG
```

### Examples

```{r, echo = FALSE}
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:
```{r}
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

```{r echo = TRUE}
sag_messages(TRUE)
```

The result will be

```{r}
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](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.

```r
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.

```r
stockInfo()
```

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

```r
stockFishdata()
```

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

A simple (almost) minimal example is:

```{r echo = FALSE}
sag_messages(FALSE)
```

```{r}
info <-
  stockInfo(
    StockCode = "whg.27.7a",
    AssessmentYear = 2020,
    ContactPerson = "[email protected]",
    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)

# this file can be checked using the icesDatsu package
library(icesDatsu)

tempfile <- tempfile(fileext = ".xml")
cat(xml, file = tempfile)
id <- uploadDatsuFileFireAndForget(tempfile, 126)

getDataFieldsDescription(126)

icesVocab::getCodeList("AssessmentPurpose")$Key


errs <- getScreeningSessionMessages(id)

if (!identical(errs, list( "Session has no messages!"))) {
  stop("There were errors in the screening session, please correct and try again")
}

x <- sag_post(sag_api("uploadStock"), body = list(sessionId = id), )

id <- 45896

  out <-
    POST(
      sag_api("uploadStock"),
      body = as.character(id),
      encode = "json",
  #    content_type("application/json-patch+json"),
      add_headers(Authorization = paste("Bearer", ices_token())),
      verbose()
    )


sag_use_token(TRUE)
getListStocks("whg.27.7a", year = 2020)


# or upload directly - not currently working...
# key <- uploadStock(info, fishdata)
```

```{r echo = FALSE}
key <- 19014
```

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

```{r}
sag_use_token(TRUE)
findAssessmentKey('whb-comb', 1996, full = TRUE)
```

### Displaying graphs

We can also look at the landings graph created from the data that were uploaded

```{r, landings-plot}
plot(getLandingsGraph(key))
```

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

```{r, summary-plot}
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](https://github.com/ices-tools-prod/icesSAG).

Feel free to open an [issue](https://github.com/ices-tools-prod/icesSAG/issues)
there if you encounter problems or have suggestions for future versions.

The current development version can be installed using:

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

        

---

Owner metadata

• Name: ICES tools (production)
• Login: ices-tools-prod
• Email: [email protected]
• Kind: organization
• Description: Tools that are operational and maintained by the ICES Secretariat
• Website: https://www.ices.dk/data/tools/Pages/Software.aspx
• Location: Copenhagen, Denmark
• Twitter:
• Company:
• Icon url: https://avatars.githubusercontent.com/u/20533792?v=4
• Repositories: 34
• Last ynced at: 2024-03-27T06:02:50.294Z
• Profile URL: https://github.com/ices-tools-prod

---

GitHub Events

Total

• Create event: 3
• Release event: 1
• Issues event: 34
• Watch event: 1
• Delete event: 7
• Member event: 1
• Issue comment event: 43
• Push event: 41
• Pull request event: 1
• Fork event: 1

Last Year

• Create event: 3
• Release event: 1
• Issues event: 34
• Watch event: 1
• Delete event: 7
• Member event: 1
• Issue comment event: 43
• Push event: 41
• Pull request event: 1
• Fork event: 1

---

Committers metadata

Last synced: 7 days ago

Name	Email	Commits
colin millar	c****r@g****m	256
Arni Magnusson	a****a@h****s	44
slarge	l****i@g****m	16
Colin Millar	c****n@i****k	10
Adriana Villamor	a****r@i****l	7
Adriana	v****0@g****m	1

Committer domains:

• ices.dk: 1
• hafro.is: 1

---

Issue and Pull Request metadata

Last synced: 2 days ago

More stats: https://issues.ecosyste.ms/repositories/lookup?url=https://github.com/ices-tools-prod/icessag

---

---

---

Package metadata

• Total packages: 1
• Total downloads:
  • cran: 638 last-month
• Total dependent packages: 0
• Total dependent repositories: 3
• Total versions: 11
• Total maintainers: 1

---

Dependencies

Score: 12.810224664518557