Basics

Welcome to the PlanBsmooth wiki!

This is a simple R package to standardize the Plan B smooth approach for the groundfish operational assessments in 2017. It is a work in progress. I welcome feedback, you can use the issues section directly, send me an email, or stop by my office.

To get started, you'll want to grab the latest and greatest version of the package: devtools::install_github("cmlegault/PlanBsmooth")

and then load it and some necessary packages (you'll need to install them first if you haven't already):
library(PlanBsmooth)
library(ggplot2)
library(dplyr)
library(tidyr)

I've supplied three example data files in the data directory. You can copy these to your computer and then set up the names in the following manner:
my.data.dir <- "C:/Users/chris.legault/Desktop/runPlanBsmooth/data"
gbcod.raw.file.name <- "gbcod"
gbcod.adios.file.name <- "ADIOS_SV_164712_GBK_NONE_strat_mean"
my.out.dir <- "C:/Users/chris.legault/Desktop/runPlanBsmooth/plots/"

The process is to first get the data into a data frame with variables Year and avg. You can do this using your own csv file as so:
raw.avg <- ReadRaw(my.data.dir, gbcod.raw.file.name) # accepting defaults

or you can be explicit in defining each option, as with this example of importing an ADIOS! file:
gbcod.avg <- ReadADIOS(data.dir = my.data.dir,
adios.file.name = gbcod.adios.file.name,
od = my.out.dir,
standardize = FALSE,
usesurvey = NA,
shiftfallflag = TRUE,
narmavgflag = FALSE,
saveplots = FALSE,
nameplots = "")

There are times when you do not want to use all the surveys available to create the average, for example due to a particular survey not catching old fish. The usesurvey option in ReadRaw and ReadADIOS allow the user to select which surveys to average by supplying a vector of either TRUE/FALSE for each available survey. For example,
ccyt.test <- ReadADIOS(data.dir = my.data.dir,
adios.file.name = "ADIOS_SV_172909_CCGOM_NONE_strat_mean",
od = my.out.dir,
standardize = FALSE,
usesurvey = NA,
shiftfallflag = TRUE,
narmavgflag = FALSE,
saveplots = TRUE,
nameplots = "")
will use all four surveys to create the average. Both ReadRaw and ReadADIOS print to screen the surveys available in the order needed for the usesurvey variable. Alternatively, you can look at the file "adios_converted_data_172909_CCGOM.csv" in the output directory to see the ordering of the surveys. They follow the ADIOS! standard of being sorted by Purpose Code then Survey. So in this example the four surveys are ordered NMFS fall, NMFS spring, MADMF fall, MADMF spring. If you want to compute the average using only the two NMFS surveys, use:
ccyt.avg <- ReadADIOS(data.dir = my.data.dir,
adios.file.name = "ADIOS_SV_172909_CCGOM_NONE_strat_mean",
od = my.out.dir,
standardize = FALSE,
usesurvey = c(TRUE, TRUE, FALSE, FALSE), # use only the 2 NMFS surveys
shiftfallflag = TRUE,
narmavgflag = FALSE,
saveplots = FALSE,
nameplots = "")

If one or more of the surveys is missing in a given year, the default setting for narmavgflag (FALSE) will create a missing value for the average of that year. If you want to compute the average ignoring the missing survey value, set narmavgflag to TRUE. The shiftfallflag allows the user to determine whether the Fall survey is shifted ahead a year to be averaged with the subsequent Spring survey (TRUE) or left in the year it occurred (FALSE).

If you have a network connection made, you can access the ADIOS! directory directly using
adios.dir <- "//net/home0/pdy/pub/STOCKEFF/ADIOS/ADIOS_SV/website/webfiles"
then a simple call accepting defaults is
gbcod.avg <- ReadADIOS(adios.dir, gbcod.adios.file.name)

Once you have the data frame, it is just a single call to get the multiplier for the terminal year:
gbcod.res <- ApplyPlanBsmooth(gbcod.avg, my.title="Georges Bank Cod")
or defining each variable explicitly:
gbcod.res <- ApplyPlanBsmooth(dat = gbcod.avg,
od = my.out.dir,
my.title = "Georges Bank Cod",
terminal.year = NA,
nyears = 33,
loess.span = 0.3,
saveplots = FALSE,
showplots = TRUE,
nameplots = "")

The variable gbcod.res is a list with all the components of the Plan B smooth approach (data, loess fit with standard errors, data and log linear fit for most recent three years, and multiplier). The multiplier is what is used to modify the recent three year average of catch (used in GB cod) or quota.

Future developments include 1) adding a function to read in a time series of catch or quota, to allow the final calculation to occur, 2) adding a function to conduct a retrospective analysis, 3) adding a wrapper to conduct a number of sensitivity analyses (e.g., changing the number of years or span in the loess), and 4) improving the graphics so that the files and settings are recorded somehow as part of the saved figure. Other suggestions welcome.