SRModels               package:FLCore               R Documentation

_S_t_o_c_k-_R_e_c_r_u_i_t_m_e_n_t _m_o_d_e_l_s

_D_e_s_c_r_i_p_t_i_o_n:

     A range of stock-recruitment (SR) models commonly used in
     fisheries science are provided in FLCore.

     Each method is defined as a function returning a list with one or
     more elements as follows:

_m_o_d_e_l Formula for the model, using the slot names (_rec_ and _ssb_) to 
     refer to the usual inputs.

_l_o_g_l Function to calculate the loglikelihood of the given model when
     estimated through MLE (See 'fmle').

_i_n_i_t_i_a_l Function to provide initial values for all parameters to be
     minimization algorithms called by 'fmle' or 'nls'. If required,
     this function also have  two attributes, 'lower' and 'upper', that
     give lower and upper limits for  the parameter values,
     respectively. This is used by some of the methods defined in
     'optim', like '"L-BFGS-B"'. The _model<-_ method for
     'FLModel-class' can then be called with  _value_ being a list thus
     described, the name of the function returning such a  list, or the
     function itself. See the examples below.

_U_s_a_g_e:

       bevholt()
       bevholt.ar1()
       bevholt.c.a()
       bevholt.c.b()
             bevholt.d()
             bevholt.ndc()
             bevholt.sv()
             geomean()
             logl.ar1(rho, sigma2, obs, hat)
             ricker()
             ricker.ar1()
             ricker.c.a()
             ricker.c.b()
             ricker.d()
             ricker.sv()
             segreg()
             shepherd()
             shepherd.ar1()
             shepherd.d()
             shepherd.d.ar1()
             shepherd.ndc()
             shepherd.ndc.ar1()
             sv2ab(steepness, vbiomass, spr0, model)

_A_r_g_u_m_e_n_t_s:

     rho: Autoregression

  sigma2: Autoregression

     obs: Observed values

     hat: estimated values

steepness: Steepness.

vbiomass: Virgin biomass.

    spr0: Spawners per recruit at F=0, see 'spr0'.

   model: character vector with model name, either 'bevholt' or
          'ricker'.

_D_e_t_a_i_l_s:

     Several functions to fit commonly used SR models are available.
     They all use maximum likelihood to estimate the parameters and
     except the autoregressive models,  all use a normal log
     distribution for the residuals. Apart from the model equation 
     parameters the variance of the log-residuals is also estimated.          

_b_e_v_h_o_l_t: Beverton & Holt stock-recruitment model fit:

                       R = alpha*S / (beta + S)

     'a' is the maximum recruitment (asymptotically) and 'b' is the
     stock level needed to produce the half of maximum recruitment a/2.
     (a, b >0).

_g_e_o_m_e_a_n: Constant Recruitment model fit, equal to the historical
     geometric mean recruitment.

 R = (R_1*R_2*...*R_n)^(1/n) = exp(mean(log(R_1) + ... + log(R_n)))


_r_i_c_k_e_r: Ricker stock-recruitment model fit:

                          R = a*S*exp(-b*S)

     'a' is related to productivity and 'b' to density dependence.     
         'a' is the recruit per stock unit at small stock levels. (a, b
     > 0). 

_s_e_g_r_e_g: Segmented regression stock-recruitment model fit:

                     R = ifelse(S <= b, a*S, a*b)

     'a' is the slope of the recruitment for stock levels below 'b',
     and a*b is the mean recruitment for stock levels above 'b'. (a, b
     > 0).

_s_h_e_p_h_e_r_d: Sheperd stock-recruitment model fit:

                       R = a * S/(1 + (S/b)^c)

     Generalized Beverton & Holt and Ricker models with one covariate.
     The covariate can be used for example to account for an
     enviromental factor that influences the recruitment dynamics. In
     the equations 'c' is the shape parameter and 'X' is the covariate.

_b_e_v_h_o_l_t._c._a: Beverton & Holt stock-recruitment model with one covariate
     in the numerator.

                     R = a*(1 - c*X)*S / (b + S)


_b_e_v_h_o_l_t._c._b: Beverton & Holt stock-recruitment model with one covariate
     in thedenominator.

                     R = a*S / (b*(1 - c*X) + S)


_r_i_c_k_e_r._c._a: Ricker stock-recruitment model with one multiplicative
     covariate. 

                       R = a*(1-c*X)*S*e^{-b*S}


_r_i_c_k_e_r._c._b: Ricker stock-recruitment model with one covariate in the
     exponent. 

                       R = a*S*e^{-b*(1-c*X)*S}


     Depensatory models for Beverton and Holt, Ricker and Shepherd
     models:

_b_e_v_h_o_l_t._d: Depensatory Beverton & Holt stock-recruitment model

                        R = a*S^c / (b + S^c)

     0< a, b, c < 'Inf'.

_b_e_v_h_o_l_t._n_d_c: Depensatory Beverton & Holt stock-recruitment model

                  R = a*S^(1 + c) / (b + S^(1 + c))

     0< a, b< 'Inf' and -0.5 < c < 0.5.

_r_i_c_k_e_r._d: Depensatory Ricker stock-recruitment model. 

                          R = a*S^c*e^{-b*S}


_s_h_e_p_h_e_r_d._d: Depensatory Shepherd stock-recruitment model. 

                      R = a * S^2/(1 + (S /b)^c)


_s_h_e_p_h_e_r_d._n_d_c: Depensatory Shepherd stock-recruitment model. 

                 R = a * (S - d)/(1 + ((S - d) /b)^c)


     Beverton and Holt and Ricker stock recruitment models
     parameterized for steepness and virgin biomass:

_b_e_v_h_o_l_t._s_v: Fits Beverton and Holt stock-recruitment model
     parameterised for steepness and virgin biomass.

          a = vbiomass*4*steepness/(spr0*(5*steepness-1.0))

                b = a*spr0*(1.0 /steepness - 1.0)/4.0


_r_i_c_k_e_r._s_v: Fits a ricker stock-recruitment model parameterized for
     steepness and virgin biomass.

                       a = exp(b*vbiomass)/spr0

                 b = log(5*steepness) /(vbiomass*0.8)


     Models fitted using autoregressive residuals of first order:

_b_e_v_h_o_l_t._a_r_1, _r_i_c_k_e_r._a_r_1, _s_h_e_p_h_e_r_d._a_r_1, _s_h_e_p_h_e_r_d._d._a_r_1, _s_h_e_p_h_e_r_d._n_d_c._a_r_1: 
     Beverton and Holt, Ricker  and Shepherd stock-recruitment models 
     with autoregressive normal log residuals of first order. In the
     model fit the  corresponding stock-recruitment model is combined
     with an autoregressive normal log likelihood of first order for
     the residuals. If R_t i the observed recruitment and Rest_t  is
     the predicted recruitment, an autoregressive model of first order
     is fitted to the log-residuals, x_t = log(R_t/Rest_t).

                         x_t = rho*x_t-1 + e

     Where 'e' follows a normal distribution with mean 0, e ~ N(0,
     sigma_ar^2). 

     Some additional useful functions:

_B_e_v_h_o_l_t._S_V, _R_i_c_k_e_r._S_V: Returns the predicted values using Beverton and
     Holt  or Ricker stock recruitment model parameterized for
     steepness and virgin biomass.  The function calculates the 'a' and
     'b' parameters of the original  parameterization for these models
     for a given steepness and virgin biomass values using 'sv2ab'
     function. This then uses the original parameterization to
     calculate  the predicted recruiment.

_s_v_2_a_b: Calculates 'a' and 'b' parameters for Beverton and Holt stock
     recruitment models from the corresponding steepness, virgin
     biomass and spr0  parameters, (spr0 = spawning at recruit at F=
     0.0parameters).

     Beverton and Holt:

   a =  frac{4 cdot vbiomass cdot steepness}{spr0*(5*steepness-1)}

     {a = vbiomass*4*steepness/(spr0*(5*steepness-1))}

          b = frac{a cdot spr0 (frac{1}{steepness} - 1)}{4}

     {b = a*spr0*(1/steepness - 1)/4}

     Ricker:

                       a = exp(b*vbiomass)/spr0

          b = frac{log(5 cdot steepness)}{0.8 cdot vbiomass}

     {b = log(5*steepness)/(vbiomass*0.8)}                             

_a_b_2_s_v: Calculates steepness and virgin biomass parameters for Beverton
     and Holt or Ricker stock-recruitment relationship from the
     corresponding 'a', 'b'  and spr0 parameters.

     Beverton and Holt:

        steepness = frac{a cdot spr0}{4 cdot b + a cdot spr0}

     {steepness = a*spr0/(4*b+a*spr0)}

         vbiomass = (spr0*a*(5*steepness - 1))/(4*steepness)

     Ricker:

             steepness = 0.2 e^{0.8 cdot b cdot vbiomass}

     {steepness = 0.2*exp(b*vbiomass*0.8)}

                       vbiomass = log(spr0*a)/b


_l_o_g_l._a_r_1: Log-Likelihood of autoregressive residuals time series of
     first order. If Y_t is the observed time series and Yest_t is the
     predicted time series using certain model, the loglikelihood of
     the residuals (X_t = Y_t - Yest_t) is calculated using the
     autoregressive model parameters sigma2  and rho.

_A_u_t_h_o_r(_s):

     The FLR Team

_R_e_f_e_r_e_n_c_e_s:

     Beverton, R.J.H. and Holt, S.J. (1957) On the dynamics of
     exploited fish populations. MAFF Fish. Invest., Ser: II 19, 533.

     Needle, C.L. Recruitment models: diagnosis and prognosis.   
     Reviews in Fish Biology and Fisheries 11: 95-111, 2002.

     Ricker, W.E. (1954) Stock and recruitment. J. Fish. Res. Bd Can.
     11, 559-623.

     Shepherd, J.G. (1982) A versatile new stock-recruitment
     relationship for fisheries and the construction of sustainable
     yield curves. J. Cons. Int. Explor. Mer 40, 67-75.

_S_e_e _A_l_s_o:

     FLSR-class, FLModel-class

_E_x_a_m_p_l_e_s:

     # inspect the output of one of the model functions
     bevholt()
     names(bevholt())
     bevholt()$logl

     # once an FLSR model is in the workspace ...
     data(nsher)

     # the three model-definition slots can be modified
     # at once by calling 'model<-' with
     # (1) a list
     model(nsher) <- bevholt()

     # (2) a function returning such a list
     model(nsher) <- bevholt

     # or (3) the name of such a function
     model(nsher) <- 'bevholt'

