5 Management Procedure (MP)
A Management Procedure (MP) is a pre-agreed process defining how a fishery will be managed, with the primary role being to take fishery information and return a management recommendation. FishSimGTG allows the user to create custom MPs and simulation-test their performance using management strategy evaluation (MSE).
Evaluating an MP requires specifying the objects of the OM as well as two additional S4-type objects. As previously discussed, the OM is comprised of three required objects in S4 format:
- Life history object (
LifeHistoryObj) - Historical fishery object (
HistFisheryObj) - Time-area object (
TimeAreaObj)
With optional:
- Stochastic object (
StochasticObj)
And, producing forward-simulation (e.g., implementing an MP and evaluating its performance) requires two additional objects in S4 format:
- Management procedure or harvest strategy object (
StrategyObj) - Forward projection time period fishery object (
ProFisheryObj)
5.1 Strategy object
The StrategyObj holds a set of instructions about how the fishery will be managed.
To create a new object of class StrategyObj, use the new() function.
The user can see the elements or slots of the StrategyObj using the slotNames() function.
## [1] "title" "projectionYears" "projectionName" "projectionParams"To populate the StrategyObj, the user should start by specifying a title (title) and the number of forward projection years to simulate (projectionYears).
The projectionName is a string that directs to a named function that contains an algorithm describing how the fishery will be managed. And, projectionParams is a list of input parameters that will be utilized by the projection function defined in projectionName.
Developing the necessary code to create a custom StrategyObj can be very challenging. Before designing an MP, the user is advised to first explore Projection Modeling in section 8.1. Projection modeling differs from an MP in that projections consist of ‘static’ actions such as a size limit or constant fishing effort, whereas MPs are ‘dynamic’ responses to updated information (e.g., pre-agreed responses to observations of the fishery system), including, for example, annual adjustments to catch limits. MPs tend to be more complicated because they include a harvest control rule or decision-rule that is informed by updated information gathered from monitoring. While FishSimGTG requires custom coding to produce an MP, projection modeling can be carried out using built-in functions.
5.2 Projection fishery object
The ProFisheryObj is an S4 object of the class Fishery that holds fishery characteristics, including vulnerability, retention, and discard information. Note that both the HistFisheryObj and
ProFisheryObj utilize the same S4 object class.
HistFisheryObj and ProFisheryObj are both Fishery objects. When no changes in the fishery characteristics are anticipated during forward projections, the slots of ProFisheryObj can be set to the same values as those in HistFisheryObj
Alternatively, the user has the option to modify the HistFisheryObj object when performing forward projections. These modifications are stored in a new ProFisheryObj.
To create a new object of class Fishery, use the new() function, as follows:
The slot names of the ProFisheryObj can be seen using the slotNames() function.
## [1] "title" "vulType" "vulParams" "retType" "retParams" "retMax" "Dmort"The user can access the help file using ? symbol
ProFisheryObj can be populated as follows:
ProFisheryObj@title<-"Test"
ProFisheryObj@vulType<-"logistic"
ProFisheryObj@vulParams<-c(10.2,0.1)
ProFisheryObj@retType<-"logistic"
ProFisheryObj@retParams <- c(15, 0.1)
ProFisheryObj@retMax <- 1
ProFisheryObj@Dmort <- 0In this example, during the projections, we maintain the same vulnerability type and parameters as in the HistFisheryObj object but modify retention to follow a logistic function.
5.2.1 Fishery spatial considerations
As noted, fishery characteristics can be modified between the historical and forward projection time periods. Additionally, fishery characteristics can vary between spatial areas during forward projection. The number of ProFisheryObj specified must be equal to the number of areas defined by TimeAreaObj@areas. ProFisheryObj must be contained in a list, with examples as follows:
#Two-area OM, with no change in fishery characteristics between historical and forward projection time periods.
ProFisheryObj<-HistFisheryObj
ProFisheryObj_list = list(ProFisheryObj, ProFisheryObj)#Two-area OM, with no spatial differences in fishery characteristics during forward projection.
ProFisheryObj<-new("Fishery")
ProFisheryObj@title<-"Test"
ProFisheryObj@vulType<-"logistic"
ProFisheryObj@vulParams<-c(10.2,0.1)
ProFisheryObj@retType<-"logistic"
ProFisheryObj@retParams <- c(15, 0.1)
ProFisheryObj@retMax <- 1
ProFisheryObj@Dmort <- 0
ProFisheryObj_list = list(ProFisheryObj, ProFisheryObj)#Two-area OM, with spatial differences in fishery characteristics during forward projection.
ProFisheryObj1<-new("Fishery")
ProFisheryObj1@title<-"FisheryArea1"
ProFisheryObj1@vulType<-"logistic"
ProFisheryObj1@vulParams<-c(10.2,0.1)
ProFisheryObj1@retType<-"logistic"
ProFisheryObj1@retParams <- c(15, 0.1)
ProFisheryObj1@retMax <- 1
ProFisheryObj1@Dmort <- 0
ProFisheryObj2<-new("Fishery")
ProFisheryObj2@title<-"FisheryArea2"
ProFisheryObj2@vulType<-"logistic"
ProFisheryObj2@vulParams<-c(10.2,0.1)
ProFisheryObj2@retType<-"full"
ProFisheryObj2@retMax <- 1
ProFisheryObj2@Dmort <- 0
ProFisheryObj_list = list(ProFisheryObj1, ProFisheryObj2)5.2.2 Uncertainty in the projection fishery
Additional slots in the StochasticObj object allow for modifications to the fishery projection object. These additional slots, StochasticObj@proFisheryVul_list, StochasticObj@proFisheryRet_list, and StochasticObj@proFisheryDmort_list, are lists where the number of list items corresponds to the number of areas (TimeAreaObj@areas). Each item in the list is a matrix with \(n\) columns and 2 rows, where the rows represent the minimum and maximum values for the parameters associated with each column \(n\).
When provided, these lists replace the vulParams, retParams, and Dmort slots in the corresponding items in ProFisheryObj_list (see spatial considerations, above). For StochasticObj@proFisheryVul_list and StochasticObj@proFisheryRet_list, the number of columns in the matrix align with the required inputs for ProFisheryObj@vulType and ProFisheryObj@retType. During each iteration, the model samples values from a uniform distribution within the specified range (i.e., between the min and max values defined in the rows), allowing for uncertainty in the parameters, independently for each area.
The final slots in the StochasticObj object are StochasticObj@sameFisheryVul, StochasticObj@sameFisheryRet, and StochasticObj@sameFisheryDmort. Each slot contains a logical variable (“TRUE” or “FALSE”). If set to TRUE, arguments of StochasticObj that replace arguments of the HistFisheryObj will also replace arguments of the ProFisheryObj_list. This option is provided so that, for a given iteration, identical samples values from the corresponding uniform distribution will be applied to both the historical and projection time periods.
When StochasticObj@sameFisheryVul = TRUE, values generated for StochasticObj@histFisheryVul will be applied so that historical and projection parameter values are identical. TRUE also overrides any input in StochasticObj@proFisheryVul_list
When StochasticObj@sameFisheryRet = TRUE, values generated for StochasticObj@histFisheryRet will be applied so that historical and projection parameter values are identical. TRUE also overrides any input in StochasticObj@proFisheryRet_list
When StochasticObj@sameFisheryDmort = TRUE, values generated for StochasticObj@histFisheryDmort will be applied so that historical and projection parameter values are identical. TRUE also overrides any input in StochasticObj@proFisheryDmort_list
5.3 MP Template
FishSimGTG provides a framework for users to construct custom MPs. A StrategyObj defines a general set of instructions about the MP, including the slot StrategyObj@projectionName that holds the name of the MP. To develop an MP, the user must populate a function with the same name with an algorithm describing how the fishery will be managed. The MP function must adhere to the template structure described in the next section. The template structure ensures that the MP can integrated into the management strategy evaluation modeling process.
StrategyObj<-new("Strategy")
StrategyObj@title = "Example"
StrategyObj@projectionYears = 25
StrategyObj@projectionName = "MP1" #Must correspond to a named functionWhen a new strategy object StrategyObj is created, the function named in the slot StrategyObj@projectionName can be specified using the following template:
templateMP <- function(phase, dataObject) {
#------------------------------------
#Unpacking: required - do not delete
#------------------------------------
#Unpack dataObject - objects passed from the OM to the MP
for(r in 1:NROW(dataObject)) assign(names(dataObject)[r], dataObject[[r]])
#------------------------------------------
#Book keeping - be aware of year j indexing!
#------------------------------------------
#OM years are indexed 1:(1 + TimeAreaObj@historicalYears + StrategyObj@projectionYears)
#Indexes specified within Class Strategy are typically indexed 1:projectionYears
#To obtain the current projection year:
yr <- j - TimeAreaObj@historicalYears - 1
#To obtain the terminal year of the historical period
yrHist <- TimeAreaObj@historicalYears + 1
#-----------------------------------------------------------------
#Summary of all available objects unpacked and passed from the OM
#-----------------------------------------------------------------
#j, current time step in OM
#k, current iteration in OM
#is, initial stock (equilibrium) for iteration k, year 1, contains values returned by solveD
#lh, LHwrapper object for iteration k, contains values returned by LHwrapper
#areas, contains TimeAreaObj@areas
#ageClasses, contains the number of age classes. Obtained from lh$ageClasses. Caution: age 0 is always the first age class.
#N, abundance-at-age for iteration k. A list of length lh$gtg that contains elements array(dim=c(ageClasses, years, areas))
#selGroup, selectivity for iteration k and step j. A list of length areas with elements contains values returned by selWrapper
#selHist, selectivity for iteration k for historical time period. A list of length areas with elements contains values returned by selWrapper
#selPro, selectivity for iteration k for projection time period. A list of length areas with elements contains values returned by selWrapper
#SB, spawing biomass at the beginnning of the year, array(dim=c(years, iterations, areas))
#VB, vulnerable biomass at the beginning of the year, array(dim=c(years, iterations, areas))
#RB, retained biomass at the beginning of the year, array(dim=c(years, iterations, areas))
#catchN, annual catch in numbers in aggregate across gtg, array(dim=c(years, iterations, areas))
#catchB, annual catch in biomass in aggregate across gtg, array(dim=c(years, iterations, areas))
#discN, dead discards in numbers in aggregate across gtg, array(dim=c(years, iterations, areas))
#discB, dead discards in biomass in aggregate across gtg, array(dim=c(years, iterations, areas))
#Ftotal, fishing mortality rate, array(dim=c(years, iterations, areas))
#SPR, spawning potential ratio, for entire population, array(dim=c(years, iterations))
#relB, relative spawning biomass (depletion) for entire population, array(dim=c(years, iterations))
#recN, annual age-0 recruitment in numbers, array(dim=c(years, iterations))
#decisionData, optional data frame containing annual sampling details. (see phase 1 below)
#decisionAnnual, optional data frame containing analysis and HCR info (see phase 2 below)
#decisionLocal, mandatory data frame containing fishing mortality by area for year j and iteration k, (see phase 3 below)
#RdevMatrix, recruitment deviations, contains values returned by recDev
#Ddev, initial relative biomass deviations, contains values returned by bioDev
#TimeAreaObj
#StrategyObj
#--------------------------------------
#Phases of an MP
#--------------------------------------
#An MP can have up to 3 phases. Phase 3 is mandatory, phases 1 & 2 are optional
#The OM will call this MP 3 times in each time step:
#Phase 1: Observation model or simulated sampling/observations of the OM.
#Phase 2: Analysis and harvest control rule
#Phase 3: Calculate fishing mortality to be passed back to the OM.
########
#Phase 1 - OPTIONAL. Observation process in year j
#Phase 1 is called by the OM once for each iteration, k, and year, j.
#Used to define imperfect sampling in year j
#Returned list is appended to data frame: decisionData
if(phase==1){
#User defines computations needed.
#User defines variable names for returned list, as this info will be used in Phase 2 (HCR)
return(list()) #e.g., return(list(year = j, iteration = k, CPUE = 1.4))
}
########
#Phase 2 - OPTIONAL. Analysis, decision-rule and/or HCR
#Phase 2 is called by the OM once for each iteration, k, and year, j.
#Used to define how catches will be regulated
#Returned list is appended to data frame: decisionAnnual
if(phase==2){
#User defines computations needed (likely will rely on info saved to decisionData)
#User defines variable names for returned list, as this info will be used in Phase 3
return(list()) #e.g., return(list(year = j, iteration = k, TAC = 1400))
}
########
#Phase 3 - MANDATORY. Calculation of fishing mortality to be used by the OM
#Phase 3 is called by the OM once for each iteration, k, and year, j.
#Used to compute fishing mortality for the called k and j.
#Returned list is appended to data frame: decisionLocal and retrieved by OM to calcualte catchN, catchB, etc.
if(phase==3){
#Must contain these elements, each a vector of length areas:
year = rep(j, areas) #Time step to which fishing mortality applies
iteration = rep(k, areas) #Iteration to which fishing mortality applies
area = 1:areas #Area to which fishing mortality applies
Flocal = rep(0.2, areas) #Calculation of fishing mortality (typically a complex computation is needed, e.g., to covert TAC to F)
#Must return this list structure:
return(list(year=year, iteration=iteration, area=area, Flocal=Flocal))
}
}