cxr_er_fit: General optimization for effect-response models

In cxr: A Toolbox for Modelling Species Coexistence in R

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:

• model_name: string with the name of the fitness model

• model: model function

• data: data supplied

• taxa: names of the taxa fitted

• covariates: covariate data supplied

• optimization_method: optimization method used

• initial_values: list with initial values

• fixed_terms: list with fixed terms

• lambda: fitted values for lambdas, or NULL if fixed

• effect: fitted values for competitive effects, or NULL if fixed

• response: fitted values for competitive responses, or NULL if fixed

• lambda_cov: fitted values for effect of covariates on lambdas, or NULL if fixed

• effect_cov: fitted values for effect of covariates on competitive effects, or NULL if fixed

• response_cov: fitted values for effect of covariates on competitive responses, or NULL if fixed

• lambda_standard_error: standard errors for lambdas, if calculated

• effect_standard_error: standard errors for competitive effects, if calculated

• response_standard_error: standard errors for competitive responses, if calculated

• lambda_cov_standard_error: standard errors for effect of covariates on lambdas, if calculated

• effect_cov_standard_error: standard errors for effect of covariates on competitive effects, if calculated

• response_cov_standard_error: standard errors for effect of covariates on competitive responses, if calculated

• log_likelihood: log-likelihood of the fits

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)

cxr documentation built on Oct. 27, 2023, 1:08 a.m.