Skip to contents

Make a custom management procedure (MP)

Source: R/interim_MP.R, R/z_MPs.R
make_MP.Rd

Function operator that creates a management procedure (MP) by combining an assessment model (function of class Assess) with a harvest control rule (function of class HCR). The resulting function can then be tested in closed-loop simulation via MSEtool::runMSE().

  • Use make_MP to specify constant TAC between assessments; the frequency of assessments is specified in OM@interval.

  • Use make_projection_MP to set catches according to a schedule set by projections, specify assessment frequency in argument assessment_interval and ensure that OM@interval <- 1.

  • Use make_interim_MP to use an interim procedure to adjust the TAC between assessments using an index (Huynh et al. 2020), with the frequency of assessments specified in argument assessment_interval when making the MP; ensure that OM@interval <- 1.

Usage

make_interim_MP(
  .Assess = "SCA",
  .HCR = "HCR_MSY",
  AddInd = "VB",
  assessment_interval = 5,
  type = c("buffer", "mean", "loess", "none"),
  type_par = NULL,
  diagnostic = c("min", "full", "none"),
  ...
)

make_projection_MP(
  .Assess = "SCA",
  .HCR = "HCR_MSY",
  assessment_interval = 5,
  Ftarget = expression(Assessment@FMSY),
  proj_args = list(process_error = 1, p_sim = 1),
  diagnostic = c("min", "full", "none"),
  ...
)

make_MP(.Assess, .HCR, diagnostic = c("min", "full", "none"), ...)

Arguments

.Assess

Assessment model, a function of class Assess.

.HCR

Harvest control rule, a function of class HCR. Currently not used in projection MPs.

AddInd

A vector of integers or character strings indicating the indices to be used in the assessment model. Integers assign the index to the corresponding index in Data@AddInd, "B" (or 0) represents total biomass in Data@Ind, "VB" represents vulnerable biomass in Data@VInd, and "SSB" represents spawning stock biomass in Data@SpInd. For the interim procedure, the function will use the first index in AddInd.

assessment_interval

The time interval for when the assessment model is applied (number of years). In all other years, the interim procedure is applied.

type

How the index is used to calculate the TAC in the interim procedure. See details.

type_par

A control parameter for the interim procedure. See details.

diagnostic

A character string describing if any additional diagnostic information from the assessment models will be collected during the closed-loop simulation. "min" (minimal) will collect information on convergence (default) and "full" will also collect the model estimates of biomass and F generated by .Assess. "none" skips this step.

...

Additional arguments to be passed to .Assess and .HCR.

Ftarget

An expression that the MP will evaluate to identify the F used in the projection. See projection and example.

proj_args

Additional arguments for projection.

Value

A function of class MP.

Details

make_interim_MP creates an MP that runs the interim procedure (updating the TAC according to index observations in between periodic assessment intervals. Always ensure to set: OM@interval <- 1. The assessment frequency is specified in argument assessment_interval.

In the year when the assessment is applied, the TAC is set by fitting the model and then running the harvest control rule. Between assessments, the TAC is updated as $$ \textrm{TAC}_{y+1} = C_{\textrm{ref}} (I_y + b \times s)/(I_{\textrm{ref}} + b \times s) $$ where Cref is the TAC calculated from the most recent assessment, Iref is the value of the index when Cref was calculated (see Equations 6 and 7 of Huynh et al. 2020). The value of I_y depends on type, with b and s equal zero unless type = "buffer":

  • "buffer" - I_y is the most recent index with b is specifed by type_par (default = 1), and s is the standard deviation of index residuals from the most recent assessment.

  • "mean" - I_y is the mean value of the index over the most recent type_par years (default = 3).

  • "loess" - I_y is the most recent index predicted by a loess smoother applied over the entire time series of the index. Use type_par to adjust the span parameter (default = 0.75).

  • "none" - I_y is the most recent index. Index values are not adjusted in the interim procedure.

References

Huynh et al. 2020. The interim management procedure approach for assessed stocks: Responsive management advice and lower assessment frequency. Fish Fish. 21:663–679. doi:10.1111/faf.12453

See also

HCR_ramp HCR_MSY diagnostic retrospective_AM

Examples

# \donttest{
# Interim MPs
MP_buffer_5 <- make_interim_MP(assessment_interval = 5)
MP_buffer_10 <- make_interim_MP(assessment_interval = 10)
OM <- MSEtool::testOM
OM@interval <- 1

MSE <- MSEtool::runMSE(OM, MPs = c("MP_buffer_5", "MP_buffer_10")) 
#> ✔ Checking MPs
#> Error: Some MPs are not a functions of class `MP`: MP_buffer_5, MP_buffer_10
# }
# A statistical catch-at-age model with a 40-10 control rule
SCA_40_10 <- make_MP(SCA, HCR40_10)

# An SCA that will produce convergence diagnostics
SCA_40_10 <- make_MP(SCA, HCR40_10, diagnostic = "min")

# MP with an SCA that uses a Ricker stock-recruit function.
SCA_Ricker <- make_MP(SCA, HCR_MSY, SR = "Ricker")
show(SCA_Ricker)
#> function (x, Data, reps = 1, diagnostic = "min") 
#> {
#>     dependencies <- "Data@Cat, Data@Ind, Data@Mort, Data@L50, Data@L95, Data@CAA, Data@vbK, Data@vbLinf, Data@vbt0, Data@wla, Data@wlb, Data@MaxAge, Data@steep, Data@CV_Ind, Data@sigmaR, Data@CV_Cat, Data@Mort, Data@CV_Mort, Data@steep, Data@CV_steep, Data@vbLinf, Data@vbK, Data@vbt0, Data@wla, Data@wlb, Data@MaxAge, Data@L50, Data@L95"
#>     do_Assessment <- SCA(x = x, Data = Data, SR = "Ricker")
#>     Rec <- HCR_MSY(Assessment = do_Assessment, reps = reps)
#>     if (diagnostic != "none") 
#>         Rec@Misc <- Assess_diagnostic(x, Data, do_Assessment, 
#>             include_assessment = FALSE)
#>     if (!is.null(do_Assessment@info$Misc)) 
#>         Rec@Misc <- c(Rec@Misc, do_Assessment@info$Misc)
#>     return(Rec)
#> }
#> <environment: 0x55c04a4cc7a8>
#> attr(,"class")
#> [1] "MP"

# \donttest{
# TAC is calculated annually from triennial assessments with projections between
# assessments with F = 0.75 FMSY
# Projections by default assume no process error.
OM <- MSEtool::testOM
OM@interval <- 1
pMP <- make_projection_MP(SCA, assessment_interval = 3, 
                          Ftarget = expression(0.75 * Assessment@FMSY),
                          proj_args = list(process_error = 1))
# }