grotag_boot {fishboot}R Documentation

Bootstrapped tag-and-recapture growth analysis

Description

This function performs bootstrapped fitting of the von Bertalanffy growth function (VBGF) with estimated growth parameters (L_{inf}, K and t_0) from tag-and-recapture data, based on the function grotag, that estimates VBGF parameters according to Francis (1988). The output is an object containing the parameters L_{inf} and K, as well as the growth performance index Phi’ (named PhiL).

This function resamples the input.data data by rows (i.e., by recapture date) several times (nresamp times, default: nresamp = 200). Then, a VBGF curve is fitted to each resampled data set. The output (a list of class lfqBoot) will store results (e.g., VGBGF function parameters K and Linf) in a data.frame accessible through $bootRaw. The $bootRaw table also includes the growth performance index Phi', seasonal parameters u and w (sensu Francis, 1988), which are equal to C (sensu Pauly and Gaschütz, 1979) and and ts (sensu Mildenberger et al., 2017). The $bootRaw table also includes seed values and system time.

Usage

grotag_boot(
  L1 = NULL,
  L2 = NULL,
  T1 = NULL,
  T2 = NULL,
  alpha = NULL,
  beta = NULL,
  design = list(nu = 0, m = 0, p = 0, sea = 0),
  stvalue = list(sigma = 0.9, nu = 0.4, m = -1, p = 0.1, u = 0.4, w = 0.4),
  upper = list(sigma = 5, nu = 1, m = 2, p = 1, u = 1, w = 1),
  lower = list(sigma = 0, nu = 0, m = -2, p = 0, u = 0, w = 0),
  gestimate = TRUE,
  st.ga = NULL,
  st.gb = NULL,
  st.galow = NULL,
  st.gaup = NULL,
  st.gblow = NULL,
  st.gbup = NULL,
  control = list(maxit = 10000),
  input.data = NULL,
  seed = NULL,
  nresamp = 200,
  na_action = c("nothing", "narm", "force"),
  time_lim = 5 * 60
)

Arguments

L1, L2, T1, T2

Name of the columns to be extracted from input.data and used by the grotag function for the arguments L1, L2, T1 and T2, respectively. See Details.

alpha

numeric value giving an arbitrary length alpha.

beta

numeric value giving an arbitrary length beta (beta > alpha).

design

list specifying the design of the model to estimate. Use 1 to designate whether a parameter(s) should be estimated. Type of parameters are:

  • nu: growth variability (1 parameter).

  • m: bias parameter of measurement error (1 parameter).

  • p: outlier probability (1 parameter).

  • sea: seasonal variation (2 parameters: u and w).

Model 1 of Francis is the default settings of 0 for nu, m, p and sea.

stvalue

Starting values of sigma(s) and depending on the design argument, nu, m, p, u, and w used as input in the nonlinear estimation (function optim) routine.

upper, lower

Upper and lower limits of the model parameters' (nu, m, p, u, and w) region to be investigated.

gestimate

logical specifying whether starting values of ga and gb (growth increments of alpha and beta) should be estimated automatically. TRUE by default.

st.ga, st.gb

If gestimate=FALSE, user-specified starting value for ga and gb respectively.

st.galow, st.gaup

If gestimate=FALSE, user-specified lower and upper limits for st.ga used in optimization.

st.gblow, st.gbup

If gestimate=FALSE, user-specified lower and upper limits for st.gb used in optimization.

control

Additional controls passed to the optimization function optim.

input.data

A growth increment object of the class data.frame.

seed

seed value for random number reproducibility (if it NULL by default, it will set internally as seed = as.numeric(Sys.time())).

nresamp

numeric; the number of permutations to run (Default: nresamp = 200).

na_action

character that defines the action that the function will execute if there is a row with NA:

  • nothing: the function will return the results including the NAs (default).

  • narm: after having the results, it will only returns the rows without NAs. See Details.

  • force: The function will start an iterative process changing the internal seed values until it fulfills the nresamp. It works just together time_lim argument. See Details.

time_lim

If na_action = "force", it defines the maximum time (in seconds) that the function will last resampling until it achieves a result output with no-NaN rows.

Details

There are 2 ways to specify the main input arguments (related to the size and timing of the mark-recapture): (1) in the classical way, i.e. by defining L1, L2, T1 and T2 as numeric vectors as indicated in the grotag documentation or (2) through a data.frame indicated in the input.data argument. In the latter case, the arguments L1, L2, T1 and T2 must be 1-length character vectors and they will serve to indicate the column names of the corresponding variables. If only one value is specified for input.data and any of the other arguments is NULL, a default name equal to the variable name will be assigned (e.g. L1 <- “L1”).

na_action = "force" should be used carefully, as it is not always due to bootstrap data selection factors, but also to an inadequate selection of the estimation parameters that the NA values are obtained. Also, the search time may depend on the size of the input set, if you have many thousands of individuals or if (in addition) the value of nresamp is high, it is possible that the function will take a long time before obtaining complete results. time_lim avoids falling into an infinite loop by limiting the time used by this process to 5 minutes, but this value is referential and may be insufficient due to the factors mentioned above.

Value

A data.frame of fitted VBGF parameters (columns) by resampling (rows). It includes a column (seed) with seed values set prior to each resampling call.

References

Examples

# Load example DB from fishmethods package
data(bonito, package = "fishmethods")

## Run the example cited on ?grotag
 #  fishmethods::grotag(L1 = bonito$L1,
 #                   L2 = bonito$L2,
 #                   T1 = bonito$T1,
 #                   T2 = bonito$T2,
 #                   alpha   = 35, beta = 55,
 #                   design  = list(nu = 1, m = 1,p = 1, sea = 1),
 #                   stvalue = list(sigma = 0.9, nu = 0.4, m = -1, p = 0.2, u = 0.4, w = 0.4),
 #                   upper   = list(sigma = 5, nu = 1, m = 2, p = 0.5, u = 1, w = 1),
 #                   lower   = list(sigma = 0, nu = 0, m = -2, p = 0.0, u = 0, w = 0),
 #                   control = list(maxit = 1e4))

# Run the example using grotag_boot
res <- grotag_boot(L1 = bonito$L1,
                   L2 = bonito$L2,
                   T1 = bonito$T1,
                   T2 = bonito$T2,
                   alpha   = 35, beta = 55,
                   design  = list(nu = 1, m = 1,p = 1, sea = 1),
                   stvalue = list(sigma = 0.9, nu = 0.4, m = -1, p = 0.2, u = 0.4, w = 0.4),
                   upper   = list(sigma = 5, nu = 1, m = 2, p = 0.5, u = 1, w = 1),
                   lower   = list(sigma = 0, nu = 0, m = -2, p = 0.0, u = 0, w = 0),
                   control = list(maxit = 1e4), seed = 18,
                   nresamp = 3, na_action = "nothing")

res

[Package fishboot version 1.0.2 Index]