rcsurplus: Reference class surplus production model

help <- list(
    Introduction = 'Package rcsurplus lets you explore a novel surplus production model for fisheries stock
assessment. The model employs a production function that differs from the canonical logistic
(Schaefer) and Gompertz (Fox) functions, but can still be related to the Pella-Tomlinson formulation.
This function is embedded in a state-space model, where observed
catch-per-unit-effort indices and measures of fishing effort are used as input. 
You may define Bayesian prior densities for all model hyperparameters 
(carrying capacity, catchability, growth rate and error variance), 
as well as the state (annual stock biomass). 
The well-studied Namibian hake fishery is provided in a Shiny app as a case study, 
via which you can compare the canonical models (Pella-Tomlinson, Schaefer and Fox) with the new model.',
    Model1 = 'In the classical approach of Pella and Tomlinson (1969), the production function
\\(h(B_t)\\) is defined as
$$ h(B_t) = \\frac{r}{\\phi} B_t \\left[1-\\left(\\frac{B_t}{K}\\right)^{\\phi}\\right],$$
where  \\(B_t\\)  denotes biomass for year \\(t\\), 
\\(r\\) is the intrinsic rate of population growth, \\(K\\) 
is the carrying capacity of the environment and \\(\\phi\\in]0,1]\\) is a shape parameter.',
    Model2 = 'The production function is employed to describe the stochastic evolution of the
biomass of exploited stocks, $$B_{t+1} = \\left\\{B_t + h(B_t) - C_t\\right\\} e^{\\xi_t},$$
where \\(C_t\\) denotes 
annual catch  and \\(\\xi_t\\sim N[0,\\sigma] \\) 
is Gaussian noise with variance 
\\(\\sigma\\). Thus, the (process) equation for the Pella-Tomlinson formulation is
$$B_{t+1} = \\left\\{ B_t \\left[ 1+ \\frac{r}{\\phi} 
\\left(1-\\left(\\frac{B_t}{K}\\right)^{\\phi}\\right)\\right] - C_t\\right\\} e^{\\xi_t}.$$',
    Model3 = 'The Schaefer process equation is obtained by fixing \\(\\phi = 1\\),
$$B_{t+1} = \\left\\{ B_t \\left[ 1+ \\frac{r}{\\phi} \\left(1-\\frac{B_t}{K}\\right)\\right] 
- C_t \\right\\} e^{\\xi_t},$$
whereas the Fox process equation results from considering the limit \\(\\phi \\rightarrow 0\\),
$$B_{t+1} = \\left\\{ B_t \\left[ 1+ r \\left(1-\\frac{\\log B_t}{\\log K}\\right)\\right] 
- C_t \\right\\} e^{\\xi_t}.$$',
    Model4 = 'Fisheries data generally consist of commercial catch and effort records, 
from which Catch Per Unit Effort (CPUE) indices may be constructed (\\(i_t, t = 1,\\ldots,n\\)). 
The latter are assumed proportional to current biomass, that is, \\(i_t = q B_t\\),  
with \\(q\\) being a constant catchability over time. 
In other words, the value of \\(q\\) defines how many fish are caught (in the appropriate units), 
on average, for each unit of fishing effort. 
Many authors build upon this structure by inserting log-normally distributed errors, 
to reach the stochastic observation equation
$$ i_t = q_t B_t e^{\\omega _t},$$
where \\(\\omega_t \\sim N[0,\\sigma]\\). 
Note that the variance of \\(\\omega_t\\), \\(\\sigma\\), matches that of \\(\\xi_t\\). 
Although such equivalence is not required in state-space models, it is used in order to compare 
results among models cited in the literature (viz., Parent and Rivot, 2012).',
    Model5 = 'We believe there are two problems in the three process equations (Pella-Tomlinson,
Schaeferand Fox) described above. First,
they are hard to work with, as they describe a nonlinear relationship between biomasses at
consecutive time instants. Second, they include observed catch, which should only appear in
the observation equation via the CPUE index \\(i_t\\). We solve the latter issue by replacing 
\\(C_t\\) with \\((1-e^{-F_t})\\times (B_t+h(B_t))\\), 
where \\(F_t\\) denotes the fishing mortality rate, which can be 
expressed as \\(F_t=qE_t\\). In this equation, \\(q\\) represents catchability (see above) and
\\(E_t\\) stands for reported fishing effort. Unlike total catch, effort can be controlled 
by management, so we can more readily accept it as a fixed parameter.',
    Model6 = 'As for the tractability of the process equation, we introduce a novel approach.
The production function we propose is
$$ h(B_t) = \\frac{r_t}{\\phi} B_t \\left[ 1 - \\left( \\frac{B_t}{K} \\right)^{\\phi}\\right],$$
with $$r_t = \\phi \\left( \\frac{B_t}{K} \\right)^{-\\phi}.$$
This leads to the process equation
$$ B_{t+1} = B_t^{1-\\phi}K^{\\phi}e^{-F_t + \\xi_t},$$
which, unlike the three canonical models, yields linear relationships between log-biomasses 
at consecutive time instants.',
    UI = 'This user interface was designed to help understand the features of package rcsurplus.
    In section "About", you can learn about the motivation for this package, the equations
    underlying the four available models, and the fitting procedure. In section "Input", you
    can examine the Namibian hake dataset (catches, effort, and CPUE), decide which model(s) to fit, 
    define the bounds for the uniform priors 
    associated with the unknown parameters in these models, and 
    set up the Markov Chain Monte Carlo fitting method. In section "Output" you can explore the
    results of the model fit(s) you have just defined. You can inspect posterior density plots and 
    scatterplots, you can compare model estimates (posterior means and credibility intervals) with
    actual observations, and you can analyse MCMC convergence diagnostics.',
    Fitting = 'Exploration of posterior distributions of unknown parameters is accomplished 
    via Markov Chain Monte Carlo methods. For this you will need to have the software OpenBUGS 
    installed on your computer. The interface between R and OpenBUGS is provided by the package 
    R2OpenBUGS. Before you decide whether or not a model fits a data set, be sure to check that
    the MCMC chains converged and passed most diagnostics.'    
)