1 Introduction

This vignette describes the use of the mixfishtools package, which is used by WGMIXFISH for creating plot outputs for WGMIXFISH-ADVICE, Fisheries Overviews, and other associated dissemination products.

Most plotting function produce ggplot2 outputs, which can be subsequently adapted to specific formatting needs; e.g.:

p <- plot_effortFltStk(data, refTable)
p <- p + theme(text = element_text(size = 12)) # adjust font size
print(p)

All examples are created from example data files included in the mixfishtools package (e.g. stfFltSum, stfFltStkSum, stfMtStkSum). For brevity, only the final prepared data structures necessary for the respective functions are shown below, but the procedures to adapt the example data to the final structures are illustrated in the respective help page examples of each function (e.g. ?plot_catchScenStk).

2 Installation of mixfishtools

In order to install the most recent version, please install the package in one of the following ways:

# install pre-compiled package (preferred)
install.packages('mixfishtools', repo = 'https://ices-tools-prod.r-universe.dev')

# install from source
library(remotes)
install_github(repo = "ices-tools-dev/mixfishtools")

Then load the package:

library(mixfishtools)

A further package to read and embed the produced .png files:

library(mixfishtools)

3 Mixed fisheries considerations

The following section outlines the main plotting functions used for the mixed fisheries considerations documents from WGMIXFISH-ADVICE.

3.1 Headline plot of catch uptake by stock and scenario

In the following example, we will prepare two objects to be passed to the plotting function plot_catchScenStk.

The first object, data, is a data.frame containing catches by scenario and stock in the advice year. The example data stfFltStkSum is aggregated across fleets to produce this object, with variables named scenario, stock, and catch. The order of scenarios should be specified by the order of levels in the factor variable scenario.

data

The second object, adv, is a data.frame containing the advised catch by stock. The expected variable names are advice by stock. Optionally, the advice levels associated with Fmsy upper (upper) and Fmsy lower (lower) can be included. Where Fmsy upper or Fmsy lower advice levels are not applicable, one should duplicate the advice levels (e.g. no Fmsy upper advice is given for COD-NS given it’s poor status, SSB < Btrigger, in the advice year, thus the advice and upper values are the same).

adv

The two objects are then passed to plot_catchScenStk for the final plot.

p <- plot_catchScenStk(data = data, adv = adv)
# print(p)

fname <- paste0(tempfile(), ".png")
png(fname, width = 6, height = 5, units = "in", res = 400)
print(p)
out <- dev.off()

tmp <- png::readPNG(fname)
knitr::include_graphics(fname, dpi = floor(dim(tmp)[2]/6))

See ?plot_catchScenStk for further argument details.

3.2 Fleet effort restriction plot

Two main objects used by the plot_effortFltStk function: a data object and a refTable object containing information on plotting colors for added consistency across several subsequent plots.

The data object contains the effort required for each fleet to take up it’s quota share (quotaEffort) of each stock. In addition, the status quo effort (sqEffort) by fleet is provided for reference. This should be each fleet’s respective effort used for the intermediate year in the short-term forecast. Finally, The variable Limitation provides information on most- and least-limiting stocks for each fleet (lowest and highest quotaEffort, respectively), while other stocks are designated with NA.

data[1:100,]

The reference table (refTable) provides information on plotting order, and color, used by many subsequent plots to maintain consistent presentation. The variable stock should contain the ICES stock codes, which are used in through in advice documents. In this example, the optional column stock_short is used as a look-up name to replace the shortened stock names used in the North Sea mixed fishery model with the ICES stock codes. A couple non-standard stocks have been added to the North Sea refTable (“nep.fu6-9”, “Nephrops”) as several plots end up grouping Nephrops function units (FUs) for simplicity. Similar adjustments may exist for other case studies, and the refTable can be adjusted accordingly.

data("refTable")
refTable

The two objects are then passed to plot_effortFltStk for the final plot.

p <- plot_effortFltStk(data = data, refTable = refTable)

fname <- paste0(tempfile(), ".png")
png(fname, width = 8, height = 10, units = "in", res = 400)
print(p)
out <- dev.off()

tmp <- png::readPNG(fname)
knitr::include_graphics(fname, dpi = floor(dim(tmp)[2]/6))

3.3 Landing by stock plot

The typical pie-chart showing historical (observed) landings or catches by stock in the final data year can be produced with plot_landByStock. The function again requires a data object and the refTable look-up table for colors to be used by stock. The data object contains a stock variable and a value variable with either observed landings (typical) or catches (define label with ylab).

data
p <- plot_landByStock(data = data, refTable)

fname <- paste0(tempfile(), ".png")
png(fname, width = 6, height = 6, units = "in", res = 400)
print(p)
out <- dev.off()

tmp <- png::readPNG(fname)
knitr::include_graphics(fname, dpi = floor(dim(tmp)[2]/6))

3.4 Landing by metier and stock plot

The last standard plot (plot_landByMetStock) shows the historical (observed) landings or catches by stock and metier in the final data year. The function again requires a data object and the refTable look-up table for colors to be used by stock. The data object contains a stock and metier variables, as well as a value variable with either observed landings (typical) or catches (define label with ylab). Note that the definition of metier categories is not standardised and each case study may choose to use a different definition.

data
p <- plot_landByMetStock(data = data, refTable)

fname <- paste0(tempfile(), ".png")
png(fname, width = 6, height = 5, units = "in", res = 400)
print(p)
out <- dev.off()

tmp <- png::readPNG(fname)
knitr::include_graphics(fname, dpi = floor(dim(tmp)[2]/6))

4 Other plotting functions

The mixfishtools package contains several other plotting functions that may be used in the accompanying advice report, but are not yet included in the advice document.

4.1 Catch composition

data[1:100,]

4.1.1 Plot catch composition for each fleet over time

selectors <- c("year")
divider <- c("fleet")
p <- plot_catchComp(data, refTable, filters = NULL, selectors, divider, yvar = "catch")

# ggplot format adjustments
p <- p + theme(text = element_text(size = 8),
  axis.text.x = element_text(angle = 90, vjust = 0, hjust=1)) +
  facet_wrap(divider,  scales = "fixed") # remove free axes

fname <- paste0(tempfile(), ".png")
png(fname, width = 6, height = 6, units = "in", res = 400)
suppressWarnings(print(p))
out <- dev.off()

tmp <- png::readPNG(fname)
knitr::include_graphics(fname, dpi = floor(dim(tmp)[2]/6))

4.1.2 Plot landings composition for each area by country-metier combinations

selectors <- c("country", "metier")
divider <- c("area")
p <- plot_catchComp(data,refTable,filters = NULL,selectors, divider)
p <- p + theme(text = element_text(size = 8),
  axis.text.x = element_text(angle = 90, vjust = 0, hjust=1)) 

fname <- paste0(tempfile(), ".png")
png(fname, width = 7, height = 6, units = "in", res = 400)
suppressWarnings(print(p))
out <- dev.off()

tmp <- png::readPNG(fname)
knitr::include_graphics(fname, dpi = floor(dim(tmp)[2]/6))

4.1.3 Plot landings composition for each metier by country for single year

filters <- list(year = 2020) # e.g. last historical data year
selectors <- c("metier")
divider <- c("country")

p <- plot_catchComp(data, refTable, filters, selectors, divider)
p <- p + theme(text = element_text(size = 8),
  axis.text.x = element_text(angle = 90, vjust = 0, hjust=1)) 

fname <- paste0(tempfile(), ".png")
png(fname, width = 7, height = 6, units = "in", res = 400)
suppressWarnings(print(p))
out <- dev.off()

tmp <- png::readPNG(fname)
knitr::include_graphics(fname, dpi = floor(dim(tmp)[2]/6))

4.2 Over-/under-quota plot

Two main objects used by the plot_overUnderFltStk function: a data object and the refTable object.

The data object contains the catch per stock and fleet, and associated quota uptake (quotaUpt), which is the ratio of the catch to the fleet’s quota share (i.e. a value of 1.0 means full uptake). Finally, The variable Limitation provides information on most- and least-limiting stocks for each fleet (lowest and highest quotaEffort, respectively), while other stocks are designated with NA.

data[1:100,]
p <- plot_overUnderFltStk(data = df2, refTable = refTable)


fname <- paste0(tempfile(), ".png")
png(fname, width = 8, height = 10, units = "in", res = 400)
suppressWarnings(print(p))
out <- dev.off()

tmp <- png::readPNG(fname)
knitr::include_graphics(fname, dpi = floor(dim(tmp)[2]/6))

4.3 Catch alluvial plot

Two main objects used by the plot_catchAlluvial function: a data object and the refTable object.

The data object contains the catches or landings (variable value) per fleet, metier and stock. The typical refTable object is also used to, which contains the corresponding colors (col), plotting order (order) for each stock.

data[1:100,]
p <- plot_catchAlluvial(data = data, refTable = refTable, text_size = 2)

fname <- paste0(tempfile(), ".png")
png(fname, width = 6, height = 6, units = "in", res = 400)
suppressWarnings(print(p))
out <- dev.off()

tmp <- png::readPNG(fname)
knitr::include_graphics(fname, dpi = floor(dim(tmp)[2]/6))

As in the above example, labels may overlap with many levels or small contributions. The plotting function has the option to try and arrange the labels to prevent overlapping using the ggrepel package (argument: text_repel = TRUE):

p <- plot_catchAlluvial(data = data, refTable = refTable, text_size = 2, 
  text_repel = TRUE, stratum_width = 0.2, nudge_x = 0.3, mult_x = c(0.1, 0.3))

fname <- paste0(tempfile(), ".png")
png(fname, width = 6, height = 6, units = "in", res = 400)
suppressWarnings(print(p))
out <- dev.off()

tmp <- png::readPNG(fname)
knitr::include_graphics(fname, dpi = floor(dim(tmp)[2]/6))

By default, the plot contains a legend as to the fill colors of the stocks. This may be removed if the final stock stratum colors are labelled clearly enough (argument: addLegend = FALSE). The following example also defines a different fill color for the non-stock strata:

p <- plot_catchAlluvial(data = data, refTable = refTable, text_size = 2, 
  text_repel = TRUE, stratum_width = 0.2, nudge_x = 0.3, mult_x = c(0.1, 0.3), 
  addLegend = FALSE, stratum_col = "grey90")

fname <- paste0(tempfile(), ".png")
png(fname, width = 6, height = 6, units = "in", res = 400)
suppressWarnings(print(p))
out <- dev.off()

tmp <- png::readPNG(fname)
knitr::include_graphics(fname, dpi = floor(dim(tmp)[2]/6))