Title:	Shiny Apps to Support Capacity Building on Harvest Control Rules
Version:	1.0.2
Author:	Finlay Scott [aut, cre], Pacific Community (SPC) [cph]
Maintainer:	Finlay Scott <finlays@spc.int>
Description:	Three Shiny apps are provided that introduce Harvest Control Rules (HCR) for fisheries management. 'Introduction to HCRs' provides a simple overview to how HCRs work. Users are able to select their own HCR and step through its performance, year by year. Biological variability and estimation uncertainty are introduced. 'Measuring performance' builds on the previous app and introduces the idea of using performance indicators to measure HCR performance. 'Comparing performance' allows multiple HCRs to be created and tested, and their performance compared so that the preferred HCR can be selected.
License:	GPL (≥ 3)
URL:	https://github.com/PacificCommunity/ofp-sam-ample
Encoding:	UTF-8
RoxygenNote:	7.2.3
Suggests:	knitr, rmarkdown, bookdown, testthat (≥ 3.1.5)
Config/testthat/edition:	3
Depends:	shiny (≥ 1.7.3)
Imports:	markdown, graphics, grDevices, RColorBrewer, stats, R6 (≥ 2.5.1), scales (≥ 1.2.1), shinyjs (≥ 2.1.0), ggplot2 (≥ 3.4.0), shinyscreenshot (≥ 0.2.0)
VignetteBuilder:	knitr
NeedsCompilation:	no
Packaged:	2023-09-28 21:46:33 UTC; Finlays
Repository:	CRAN
Date/Publication:	2023-09-29 07:40:09 UTC

AMPLE: A package of Shiny apps that introduce Harvest Control Rules (HCR) for fisheries management.

Description

AMPLE provides three Shiny apps that introduce Harvest Control Rules (HCR) for fisheries management. 'Introduction to HCRs' provides a simple overview to how HCRs work. Users are able to select their own HCR and step through its performance, year by year. Biological variability and estimation uncertainty are introduced. 'Introduction to indicators' builds on the previous app and introduces the idea of using performance indicators to evaluate HCR performance. 'Comparing performance' allows multiple HCRs to be created and tested, and their performance compared so that the preferred HCR can be selected.

Harvest Control Rules are used as part of a fishery harvest strategy. This package was put together as part of capacity building efforts by the Pacific Community (SPC) to develop fishery harvest strategies for tuna stocks in the western and central Pacific Ocean (WCPO), working with the Western and Central Pacific Fisheries Commission (WCPFC). For more information on tuna harvest strategies in the WCPO please see LINKs.

AMPLE functions

Too launch the apps use the functions: intro_hcr(), measuring_performance() and comparing_performance().

Acknowledgement

With thanks to Andre Punt. Also thanks to Winston Chang for help with the R6 class / Shiny reactivity.

Author(s)

Maintainer: Finlay Scott finlays@spc.int (ORCID)

Other contributors:

• Pacific Community (SPC) [copyright holder]

See Also

Useful links:

• https://github.com/PacificCommunity/ofp-sam-ample

mpParamsSetterUI

Description

The interface for the HCR options. The parameter selection inputs shown in the app are conditional on the selected type of HCR. Some of the inputs have initial values that can be set using the function arguments.

Does the setting part of the MP params module. Returns a list of MP params based on the MP inputs.

Creates the MP params list based on the MP selection from the Shiny UI. Defined outside of a reactive environment above so we can use it non-reactively (helpful for testing).

Usage

mpParamsSetterUI(
  id,
  mp_visible = NULL,
  title = "Select the type of HCR you want to test.",
  init_thresh_max_catch = 140,
  init_thresh_belbow = 0.5,
  init_constant_catch = 50,
  init_constant_effort = 1
)

mpParamsSetterServer(id, get_stoch_params = NULL)

mp_params_switcheroo(input, est_sigma = 0, est_bias = 0)

Arguments

Value

A taglist

A list of HCR options.

stochParamsSetterUI

Description

stochParamsSetterUI() is the UI part for the stochasticity options. Stochasticity is included in the projections in two areas: biological variability (e.g. recruitment) and estimation error (to represent the difference between the 'true' status of the stock and the estimated status that is used by the HCR). Estimation error includes bias and variability. The arguments to this function allow only some of these elements to be shown.

stochParamSetterServer() does the server side stuff for the stochasticity options.

set_stoch_params() sets up default values for the stochasticity parameters. Defined as a separate function so it can be used for testing outside of a reactive environment.

Usage

stochParamsSetterUI(
  id,
  show_var = FALSE,
  show_biol_sigma = TRUE,
  show_est_sigma = TRUE,
  show_est_bias = TRUE,
  init_biol_sigma = 0,
  init_est_sigma = 0,
  init_est_bias = 0
)

stochParamsSetterServer(id)

set_stoch_params(input)

Arguments

Value

A taglist

A list of stochasticity options.

R6 Class representing a stock

Description

A stock object has life history parameters, fields and methods for a biomass dynamic model.

Details

A stock has biomass, effort, catch and hcr_ip and hcr_op fields as well as the life history parameters. The population dynamics are a simple biomass dynamic model. The Stock class is used for the Shiny apps in the AMPLE package.

Public fields

Methods

Public methods

• Stock$new()

• Stock$reset()

• Stock$reactive()

• Stock$fill_history()

• Stock$fill_catch_history()

• Stock$fill_biomass()

• Stock$as_data_frame()

• Stock$project()

• Stock$relative_cpue()

• Stock$relative_effort()

• Stock$replicate_table()

• Stock$time_periods()

• Stock$performance_indicators()

• Stock$pi_table()

• Stock$clone()

Method new()

Create a new stock object, with fields of the right dimension and NA values (by calling the reset() method. See the reset() method for more details.

Usage

Stock$new(stock_params, mp_params, niters = 1)

Arguments

Returns

A new Stock object.

Method reset()

Resets an existing stock object, by remaking all fields (possibly with different dimensions for the array fields) . Fills up the catch, effort and biomass fields in the historical period based on the stock history and life history parameters in the stock_params argument. This is a reactive method which invalidates a reactive instance of this class after it is called.

Usage

Stock$reset(stock_params, mp_params, niters)

Arguments

Returns

A new Stock object.

Method reactive()

Method to create a reactive instance of a Stock.

Usage

Stock$reactive()

Returns

a reactiveExpr.

Method fill_history()

Fills the historical period of the stock

Usage

Stock$fill_history(stock_params, mp_params)

Arguments

Method fill_catch_history()

Fill up the historical period of catches with random values to simulate a catch history

Usage

Stock$fill_catch_history(stock_params)

Arguments

Method fill_biomass()

Fills the biomass in the next timestep based on current biomass and catches The surplus production model has the general form: Bt+1 = Bt + f(Bt) - Ct Where the production function f() is a Pella & Tomlinson model with shape f(Bt) = r/p Bt * (1 - (Bt/k)^p) Here p is fixed at 1 to give a Schaefer model cpue = Ct / Et = qBt

Usage

Stock$fill_biomass(ts, iters = 1:dim(self$biomass)[1])

Arguments

Method as_data_frame()

Produces a data.frame of some of the array-based fields, like biomass. Just used for testing purposes.

Usage

Stock$as_data_frame()

Method project()

Projects the stock over the time steps given and updates the biomass, HCR ip / op and catches It uses a simple biomass dynamic model where the catches or fishing effort are set every time step by the harvest control rule.

Usage

Stock$project(timesteps, mp_params, iters = 1:dim(self$biomass)[1])

Arguments

Returns

A stock object (a reactiveValues object with bits for the stock)

Method relative_cpue()

The catch per unit effort (CPUE, or catch rate) relative to the CPUE in the last historical period.

Usage

Stock$relative_cpue()

Returns

An array of same dims as the catch and effort fields.

Method relative_effort()

The effort relative to the effort in the last historical period.

Usage

Stock$relative_effort()

Returns

An array of same dims as the effort field.

Method replicate_table()

Summarises the final year of each iteration. Only used for the Measuring Performance app.

Usage

Stock$replicate_table(iters = 1, quantiles = c(0.05, 0.95))

Arguments

Method time_periods()

Calculates the short, medium and long term periods to calculate the performance indicators over, based on the last historic year of data and the number of years in the projection.

Usage

Stock$time_periods()

Method performance_indicators()

Gets the performance indicators across all indicators, for three time periods. Used in the Measuring Performance and Comparing Performance apps.

Usage

Stock$performance_indicators(
  iters = 1:dim(self$biomass)[1],
  quantiles = c(0.05, 0.95)
)

Arguments

Returns

A data.frame

Method pi_table()

Makes a table of the performance indicators.

Usage

Stock$pi_table(iters = 1:dim(self$biomass)[1], quantiles = c(0.05, 0.95))

Arguments

Method clone()

The objects of this class are cloneable with this method.

Usage

Stock$clone(deep = FALSE)

Arguments

stockParamsSetterUI

Description

stockParamsSetterUI() is the interface for the stock options (e.g. life history and exploitation status).

stockParamsSetterServer() does the setting of the stock parameters in the server.

get_stock_params() Sets up default values for the stock, including year range. It's a separate function so it can be used and tested outside of a reactive environment.

Usage

stockParamsSetterUI(id)

stockParamsSetterServer(id, get_stoch_params = NULL)

get_stock_params(input, biol_sigma = 0)

Arguments

Value

A taglist

A list of stock options.

assessment

Description

Function used by get_hcr_ip() to generate input data for an assessment based HCR. The input to the HCR is depletion (i.e. Biomass / K).

Usage

assessment(stock, mp_params, yr, iters = 1:dim(stock$biomass)[1])

Arguments

'Comparing HCR Performance' app launcher

Description

Launches the Comparing Performance Shiny app. See the 'Information' tab in the app for more information. Also see the package vignette (vignette("comparing_performance", package="AMPLE")) for a tutorial.

Usage

comparing_performance(...)

Arguments

Examples

## Not run: comparing_performance()

Evaluates a constant harvest control rule

Description

Evaluates a constant harvest control rule, i.e. one that ignores the stock status and just returns the constant level (catch or effort). Used by the hcr_op function.

Usage

constant(mp_params, ...)

Arguments

estimation_error

Description

Estimation error applied to the 'true' stock status to generate an 'observed' stock status used in the HCR. The error is a combination of bias and lognormally distributed noise.

Usage

estimation_error(input, sigma, bias)

Arguments

Get the input to the HCR

Description

Run the MP analyses function to generate the input to the HCR i.e. observed stock status. For example, estimated biomass from an assessment.

Usage

get_hcr_ip(stock, mp_params, yr, ...)

Arguments

Evaluates the harvest control rule.

Description

Evaluates the harvest control rule in a single year (timestep).

Usage

get_hcr_op(stock, mp_params, yr, iters = 1:dim(stock$biomass)[1])

Arguments

Value

A vector of outputs from the HCR.

Introduction to HCRs app launcher

Description

Launches the introduction to HCRs Shiny app. See the 'Information' tab in the app for more information. Also see the package vignette (vignette("intro_hcr", package="AMPLE")) for a tutorial.

Usage

intro_hcr(...)

Arguments

Examples

## Not run: intro_hcr()

Measuring performance app launcher

Description

Launches the 'Measuring Performance' Shiny app. See the 'Information' tab in the app for more information. Also see the package vignette (vignette("measuring_performance", package="AMPLE")) for a tutorial.

Usage

measuring_performance(...)

Arguments

Examples

## Not run: measuring_performance()

Evaluates a threshold harvest control rule

Description

Evaluates a threshold (i.e. hockey stick) harvest control rule. Used by the hcr_op function.

Usage

threshold(input, mp_params, ...)

Arguments

Value

A vector of the same dimension as the input.