cxr_er_fit {cxr}R Documentation

General optimization for effect-response models

Description

Estimates parameters of user-specified models of competitive effects and responses. NOTE: including covariates on competitive effects is still under development, in this version it is suggested not to use that feature.

Usage

cxr_er_fit(
  data,
  model_family = c("BH"),
  covariates = NULL,
  optimization_method = c("Nelder-Mead", "BFGS", "CG", "ucminf", "L-BFGS-B", "nlm",
    "nlminb", "Rcgmin", "Rvmmin", "spg", "bobyqa", "nmkb", "hjkb", "nloptr_CRS2_LM",
    "nloptr_ISRES", "nloptr_DIRECT_L_RAND", "DEoptimR", "GenSA"),
  lambda_cov_form = c("none", "global"),
  effect_cov_form = c("none", "global"),
  response_cov_form = c("none", "global"),
  initial_values = list(lambda = 1, effect = 1, response = 1, lambda_cov = 0, effect_cov
    = 0, response_cov = 0),
  lower_bounds = NULL,
  upper_bounds = NULL,
  fixed_terms = NULL,
  bootstrap_samples = 0
)

Arguments

data

either a list of dataframes or a single dataframe. if 'data' is a list, each element is a dataframe with the following columns:

  • fitness: fitness metric for each observation

  • neighbours: named columns giving the number of neighbours of each column the names of the list elements are taken to be the names of the focal species.

If 'data' is a dataframe, it also needs a 'focal' column. Regardless of the data structure, all focal species need to have the same number of observations (i.e. same number of rows), and the set of neighbour species needs to be the same as the set of focal species, so that the neighbours columns correspond to the names of the list elements or, if 'data' is a dataframe, to the values of the 'focal' column. Future versions will relax this requirement.

model_family

family of model to use. Available families are BH (Beverton-Holt), LV (Lotka-Volterra), RK (Ricker), and LW (Law-Watkinson). Users may also define their own families and models (see vignette 4).

covariates

a data structure equivalent to 'data', in which each column are the values of a covariate.

optimization_method

numerical optimization method.

lambda_cov_form

form of the covariate effects on lambda. Either "none" (no covariate effects) or "global" (one estimate per covariate).

effect_cov_form

form of the covariate effects on competitive effects. Either "none" (no covariate effects) or "global" (one estimate per covariate)

response_cov_form

form of the covariate effects on competitive responses. Either "none" (no covariate effects) or "global" (one estimate per covariate)

initial_values

list with components "lambda","effect","response", and optionally "lambda_cov", "effect_cov", "response_cov", specifying the initial values for numerical optimization. Single values are allowed.

lower_bounds

optional list with single values for "lambda", "effect","response", and optionally "lambda_cov", "effect_cov", "response_cov".

upper_bounds

optional list with single values for "lambda", "effect","response", and optionally "lambda_cov", "effect_cov", "response_cov".

fixed_terms

optional list specifying which model parameters are fixed.

bootstrap_samples

number of bootstrap samples for error calculation. Defaults to 0, i.e. no error is calculated.

Value

an object of class 'cxr_er_fit' which is a list with the following components:

Examples


# fit three species at once
data("neigh_list")
# these species all have >250 observations
example_sp <- c("BEMA","LEMA","HOMA")
sp.pos <- which(names(neigh_list) %in% example_sp)
data <- neigh_list[sp.pos]
n.obs <- 250
# keep only fitness and neighbours columns
for(i in 1:length(data)){
  data[[i]] <- data[[i]][1:n.obs,c(2,sp.pos+2)]#2:length(data[[i]])]
}

# covariates: salinity
data("salinity_list")
salinity <- salinity_list[example_sp]
# keep only salinity column
for(i in 1:length(salinity)){
  salinity[[i]] <- salinity[[i]][1:n.obs,2:length(salinity[[i]])]
}

initial_values = list(lambda = 1, 
                     effect = 1, 
                     response = 1
                     # lambda_cov = 0, 
                     # effect_cov = 0, 
                     # response_cov = 0
)
lower_bounds = list(lambda = 0, 
                   effect = 0, 
                   response = 0
                   # lambda_cov = 0, 
                   # effect_cov = 0, 
                   # response_cov = 0
)
upper_bounds = list(lambda = 100, 
                    effect = 10, 
                    response = 10
                   # lambda_cov = 0, 
                   # effect_cov = 0, 
                   # response_cov = 0
)

er_3sp <- cxr_er_fit(data = data,
                     model_family = "BH",
                     # fit without covariates, 
                     # as it may be very computationally expensive
                     # covariates = salinity,
                     optimization_method = "bobyqa",
                     lambda_cov_form = "none",
                     effect_cov_form = "none",
                     response_cov_form = "none",
                     initial_values = initial_values,
                     lower_bounds = lower_bounds,
                     upper_bounds = upper_bounds,
                     # syntaxis for fixed values
                     # fixed_terms = list("response"),
                     bootstrap_samples = 3)
# brief summary
summary(er_3sp)


[Package cxr version 1.1.1 Index]