library(knitr)
## Global options
opts_chunk$set(echo    =!TRUE,
               eval    =TRUE,
               cache   =!FALSE,
               cache.path="cache/",
               prompt  =FALSE,
               comment =NA,
               message =FALSE,
               tidy    =FALSE,
               warnings=FALSE,
               fig.height=4.5,
               fig.width =4.5,
               fig.path  ="tex/")
warn=options()$warn
options(warn=-1)
library(ggplot2)
library(kobe)

theme_set(theme_bw())
options(digits=3)
options(warn=warn)

Introduction

Installation

Quick Start

Stock Assessment

Current Status

Projections

Management Strategy Evaluation

More information

References

Introduction {#Introduction}

The Tuna Regional Fisheries Management Organisations (tRFMOs^longnote) are intergovernmental organisations that are responsible for data collection, provision of scientific advice, and the management of tuna and tuna-like species. As a step towards harmonisation the tRFMOs have agreed on a common management advice framework, known as the Kobe Framework (@kell2016quantification).

Commission for the Conservation of Southern Bluefin Tuna (CCSBT), 
Inter-American Tropical Tuna Commission (IATTC), 
International Commission for the Conservation of Atlantic Tunas (ICCAT), 
Indian Ocean Tuna Commission (IOTC) and 
Western and Central Pacific Fisheries Commission (WCPFC).

Under the Kobe Framework two main main visualisation tools are used to provide scientific advice, a phase plot and a strategy matrix. The phase plots shows current stock status and exploitation rate relative to reference points such as $B_{MSY}$ and $F_{MSY}$. While the strategy matrix presents the the probability of meeting management objectives under different management options such as a total allowable catch (TAC).

Assessment advice within the tRFMOs is based on a range of models; for example integrated models such as Stock Synthesis (SS; @methot2013stock) and Multifan-CL (@hampton2001spatially), virtual population analysis (VPA), and biomass dynamic models.

The kobe R package has methods for reading in results from the main stock assessment methods and when running Managment Strategy Evaluation (MSE), computing summary statistics and for plotting.

Back to Top

Installation {#Installation}

The simplest way to obtain kobe is to install it from CRAN by using the following command in the R console:

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

The repos options can be changed depending on personal preferences and includes options such as choosing the directories in which to install the packages see help(install.packages) for more details.

Back to Top

Quick Start {#QuickStart}

So that users may have a better idea of what functions are available, which one to choose, or where to seek help, this section provides a general overview of the package. In particular it highlights the various elements, what they do, and provides some examples of usage. More details are given in later sections.

First, load the kobe package:

library(kobe)

There is an example dataset for Atlantic yellowfin, used for illustration and as a test dataset, alternatively users can load their own data.

data(yft)

The dataset contains historical estimates of biomass relative to $B_{MSY}$ (stock) and exploitation level relative to $F_{MSY}$ (harvest) for 3 assessment methods and 2 scenarios based on choice of catch per unit effort (CPUE) used to calibrate the models. In each case parameter uncertainty was estimated using bootstrap simulation and so there are 100 replicates (iter).

library(kobe)
data(yft)
head(yft)

Plotting

Plotting is done using ggplot2 which provides a powerful alternative paradigm for creating both simple and complex plots in R using the ideas the Grammar of Graphics ^[Wilkinson, L. 1999. The Grammar of Graphics, Springer. doi 10.1007/978-3-642-21551-3_13.] The idea of the grammar is to specify the individual building blocks of a plot and then to combine them to create the graphic desired^[http://tutorials.iq.harvard.edu/R/Rgraphics/Rgraphics.html].

The ggplot functions expects a data.frame for its first argument, data; then a geometric object geom that specifies the actual marks put on to a plot and an aesthetic that is "something you can see" have to be provided. Examples of geometic Objects (geom) include points (geom_point, for scatter plots, dot plots, etc), lines (geom_line, for time series, trend lines, etc) and boxplot (geom_boxplot, for, well, boxplots!). Aesthetic mappings are set with the aes() function and, examples include, position (i.e., on the x and y axes), color ("outside" color), fill ("inside" color), shape (of points), linetype and size.

The phase plot plots stock status against fishing mortality relative to target reference points as a two-dimensional phase plot.

library(ggplot2)

kobePhase(subset(yft,year==2014))+
  geom_point(aes(stock,harvest))

Split-apply-combine

kobe contains a variety of functions to summarise assessment results. These can be used with the plyr package to provide summaries by scenario and year. plyr has methods for running split-apply-combine procedures, e.g. first splitting a dataset into subsets, then running a function for each subset and then recombining the results back into a single object.

library(plyr)

An example of estimating the quantiles of the current estimates of stock status by method and scenario

trks=ddply(yft, .(method,scenario), with, quantile(stock))

plyr functions have a simple naming convention. The first two letters of the function tells the input and output data types, respectively. The one above takes a data.frame and returns a data.frame.

trks=ddply(yft, .(method,scenario,year), with, quantile(stock))

The first argument, yft, is the input data frame and contains all the data from the last year in the assessment. The next argument are the variables to subset by over which the statistics will be computed, and the third processes the data.frame by each subset. with creates an environment constructed from data in which to run quantile.

head(trks)
ggplot(trks)+
  geom_line(aes(year,`50%`,
                col  =method,
                group=paste(method,scenario)))

Back to Top

Advice Framework

Stock Assessment

read.kobe()
?read.kobe
library(mpb)

kobe()

Current Status

The phase plot identifies quadrants (regions) where the stock is overfished (biomass or SSB is less than $B_{MSY}$) or overfishing is occurring ($F < F_{MSY}$ ) and a target region (where both $SSB > SSB_{MSY} and F < F_{MSY}). In the case of biomass dynamic stock assessment model results biomass may be used instead of SSB. The target region is also called the green quadrant, referring to the colour scheme typically used. The plots can be used to indicate for example when management plans to recover the stock to the target region should be implemented.

yft2014=subset(yft,year==2014)
kobePhase(yft2014)+
  geom_point(aes(stock,harvest,col=method))+
  facet_grid(method~scenario)
library(plyr)
trks=ddply(yft,.(method,scenario,year), 
           function(x) trks(x$stock,x$harvest,prob=c(0.5)))

We can then add the medians of the historic assessments to the phase plots by adding layers to the \code{ggplot2} object \code{kp}, i.e. \code{geom_path} adds an extra layer plotting the time series medians and \code{geom_point} the medians in the last assessment year. We then plot the results by assessment using \code{facet_wrap} to split them into multiple panels. Finally we get rid of the legend for \code{run} since runs are plotted by panel.

kobePhase() + 
   geom_point(aes(stock,harvest), data=subset(yft,year==2014),col="cyan")+
   geom_path( aes(stock,harvest), data=trks) +
   facet_wrap(method~scenario) 

\caption{Phase plot of fishng mortality and stock status reletive to $F_{MSY}$ and $B_{MSY}$, large point and lines are the medians from the assessment and the panels correspond to each run.} \end{center}\end{figure}

Densities

shade
smry

Calculates the probability of an obervations occurring in a 2D cell using HPDregionplot given a sample calculates the bivariate region of highest marginal posterior density for two variables, using kde2d from MASS to calculate a bivariate density.

prob

Calculates the Densities of obervation in a 2D cell using Two-dimensional kernel density estimation with an axis-aligned bivariate normal kernel, evaluated on a square grid.

density

Calculates the frequency of an obervation in a 2D cell

freq
interp

Has the stock recovered yet? i.e. stock>=1 and harvest<=1 in the current or an earlier time step in other words has it been in the green Kobe quadrant.

recovered

Marginal Densities

The phase plots show the cross correlations between stock and harvest, but many points overlay each other so it is hard to determine the actual probabilities or densities. To overcome this difficulty contours showing the bivariate probabilities can be plotted using \code{kobeP} e.g.

geom_path(aes(x,y,group=level),colour="blue",
                    data=ddply(subset(sims,year==2010 & TAC==15000),.(Run), 
                               function(pts) kobeProb(pts$stock,pts$harvest,prob=c(0.7,.5,.25)))) +
                    facet_wrap(~Run) + 
                    theme(legend.position = "none")
kobe:::kobePhaseMar(transform(yft2014,run=paste(scenario,method))[,c("stock","harvest","run")])
kobe:::kobePhaseMar2(transform(yft2014,run=paste(scenario,method))[,c("stock","harvest","run")])
kobe:::kobePhaseMar3(transform(yft2014,run=paste(scenario,method))[,c("stock","harvest","run")])
pie.dat=ddply(subset(sims,year==2010 & TAC==15000),.(Run),kobeSmry,o=T)
pie.dat=ddply(melt(pie.dat,id.vars="Run"),.(Run,variable),
function(x) data.frame(value=mean(x$value)))
## pie charts
ggplot(subset(pie.dat,value>0), aes(x =factor(1), y=value, fill = variable)) +
geom_bar(width=1,stat="identity") +
coord_polar(theta="y") +
labs(fill= ' Kobe Quadrant ' ) + xlab( '' ) + ylab( '' )+
scale_fill_manual(values=c("red","green","yellow"))+
facet_wrap(~Run)+
scale_x_discrete(breaks=NULL)+
scale_y_continuous(breaks=NULL)

Projections

Strategy Matrix

The strategy matrix lays out the probability of meeting management objectives under different options, this may include if desired ending overfishing or rebuilding overfished stocks. An intention is to facilitate the application of the PA by providing Commissions with a basis to evaluate and adopt management options at various levels of risk, enabling management taken accounting for uncertainty.

library(akima)
Interp=function(x,levels=seq(0.0,1.0,0.05),
               col   =c(colorRampPalette(c("red4","red"))(12),colorRampPalette(c("yellowgreen","darkgreen"))(8)),
               nIterp=101){

  x=x[!is.na(x[,1]) & !is.na(x[,2]) & !is.na(x[,3]),]

  ##### smooth
  t.<-interp(x[,1],x[,2],x[,3],
                    xo=seq(min(x[,1]),   max(x[,1]), length=nIterp),
                    yo=seq(min(x[,2]),   max(x[,2]), length=nIterp),
                    duplicate="mean")


  res=cbind(expand.grid(x=t.$x,y=t.$y),z=cut(t.$z,levels,include.lowest=T),w=c(t.$z))
  res$col=col[as.numeric(res$z)]

  res}

kobe2012=subset(yft,year %in% 2013:2022)

pdat=subset(ddply(kobe2012,.(year,TAC),kobeSmry),
            select=c(year,TAC,green,underFished,underFishing))
pdat=melt(pdat,id.vars=c("year","TAC"))
pdat=ddply(pdat, .(variable), function(x) Interp(data.frame(x$year,x$TAC,x$value)))

col.=c(colorRampPalette(c("red4","red"))(12),
       colorRampPalette(c("yellowgreen","darkgreen"))(8))

k2p = ggplot(aes(x=x,y=y,z=w),data=pdat)                 +
           geom_tile(aes(x,y,fill=z))                    +
           scale_fill_manual(values=col.,guide="none")   +
           stat_contour(aes(colour= ..level..),size=1.2,  
                            breaks=c(0.6,0.7,0.8,0.9))   +
           scale_colour_gradient(low="grey", high="black", 
                                 breaks=c(0.6,0.7,0.8,0.9),
                                  labels=c(0.6,0.7,0.8,0.9),limits=c(0.6,1))    +
           facet_wrap(~variable,ncol=1)                       +
           xlab("Year")+ylab("TAC") 
k2p

Three Kobe matrices Tables~\ref{tab:k2sm1}, \ref{tab:k2sm3} and \ref{tab:k2sm3} summarise the probabilities (by the ranges of 50-59 \%, 60- 69 \%, 70-79 \%, 80-89 \% and greater or equal to 90 \%) for different levels of catch across multiple years of

t.=ddply(subset(sims,year %in% 2013:2022),.(year,TAC),  kobeSmry)

k2smTab=list()
k2smTab[[1]]=cast(subset(t., year %in% 2013:2022),TAC~year,value="underFishing")
k2smTab[[2]]=cast(subset(t., year %in% 2013:2022),TAC~year,value="underFished")
k2smTab[[3]]=cast(subset(t., year %in% 2013:2022),TAC~year,value="green")

Decision Tables

Back to Top

Management Strategy Evaluation

aav
pid
dRate
hinge
iav
incr

Harvest Control Rules

hcr= data.frame(stock  =c(0.0 ,0.1 , 0.6,2.0), 
                harvest=c(0.01,0.01, 0.7,0.7))
kobePhase()+
  geom_line(aes(stock,harvest),data=hcr,col="orange",size=2)

Summary Statistics

When using MSE a variety of performance measures (related to catch levels and catch variability) as well as stock status are required.

Back to Top

Example

Back to Top

\newthought{Doh!} ...

More information

    library(devtools)
    install_github('flr/kobe')

Software Versions

Author information

Laurence KELL. laurie@seaplusplus.co.uk

References {#References}

Back to Top



laurieKell/kobe documentation built on Sept. 9, 2023, 9:47 p.m.