cxr_pm_fit: General optimization for population models

In cxr: A Toolbox for Modelling Species Coexistence in R

General optimization for population models

Description

Estimates parameters of user-specified population dynamics models.

Usage

cxr_pm_fit(
  data,
  focal_column = NULL,
  model_family,
  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"),
  alpha_form = c("none", "global", "pairwise"),
  lambda_cov_form = c("none", "global"),
  alpha_cov_form = c("none", "global", "pairwise"),
  initial_values = list(lambda = 0, alpha_intra = 0, alpha_inter = 0, lambda_cov = 0,
    alpha_cov = 0),
  lower_bounds = NULL,
  upper_bounds = NULL,
  fixed_terms = NULL,
  bootstrap_samples = 0
)

Arguments

data	dataframe with observations in rows and two sets of columns: fitness: fitness metric for the focal individual neighbours: numeric columns with user-defined names, giving number of neighbours for each group
focal_column	optional integer or character giving the column with neighbours from the same species as the focal one. This field is necessary if "alpha_intra" is specified in initial_values, lower_bounds, upper_bounds, or fixed_terms.
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	optional named matrix or dataframe with observations (rows) of any number of environmental covariates (columns).
optimization_method	numerical optimization method.
alpha_form	what form does the alpha parameter take? one of "none" (no alpha in the model), "global" (a single alpha for all pairwise interactions), or "pairwise" (one alpha value for every interaction).
lambda_cov_form	form of the covariate effects on lambda. Either "none" (no covariate effects) or "global" (one estimate per covariate).
alpha_cov_form	form of the covariate effects on alpha. One of "none" (no covariate effects), "global" (one estimate per covariate on every alpha), or "pairwise" (one estimate per covariate and pairwise alpha)
initial_values	list with components "lambda","alpha_intra","alpha_inter","lambda_cov", "alpha_cov", specifying the initial values for numerical optimization. Single values are allowed.
lower_bounds	optional list with single values for "lambda","alpha_intra","alpha_inter","lambda_cov", "alpha_cov".
upper_bounds	optional list with single values for "lambda","alpha_intra","alpha_inter","lambda_cov", "alpha_cov".
fixed_terms	optional list of numeric vectors specifying the value of fixed model parameters, among "lambda","alpha_intra","alpha_inter","lambda_cov", and "alpha_cov".
bootstrap_samples	number of bootstrap samples for error calculation. Defaults to 0, i.e. no error is calculated.

Value

an object of class 'cxr_pm_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

• focal_ID: name/ID of the focal taxa, if provided in 'focal_column'

• covariates: covariate data supplied

• optimization_method: optimization method used

• initial_values: list with initial values

• fixed_terms: list with fixed terms

• lambda: fitted value for lambda, or NULL if fixed

• alpha_intra: fitted value for intraspecific alpha, or NULL if fixed

• alpha_inter: fitted value for interspecific alpha, or NULL if fixed

• lambda_cov: fitted value(s) for lambda_cov, or NULL if fixed.

• alpha_cov: fitted value(s) for alpha_cov, or NULL if fixed. These are structured as a list with one element for each covariate.

• lambda_standard_error: standard error for lambda, if computed

• alpha_intra_standard_error: standard error for intraspecific alpha, if computed

• alpha_inter_standard_error: standard error for interspecific alpha, if computed

• lambda_cov_standard_error: standard error for lambda_cov, if computed

• alpha_cov_standard_error: standard error for alpha_cov, if computed

• log_likelihood: log-likelihood of the fit

Examples

data("neigh_list")
my.sp <- "BEMA"
# data for a single species, keep only fitness and neighbours columns
sp_data <- neigh_list[[my.sp]][2:ncol(neigh_list[[1]])]

  sp_fit <- cxr_pm_fit(data = sp_data,
                       focal_column = my.sp,
                       optimization_method = "bobyqa",
                       model_family = "BH",
                       alpha_form = "pairwise",
                       lambda_cov_form = "none",
                       alpha_cov_form = "none",
                       initial_values = list(lambda = 1,alpha_intra = 0.1,alpha_inter = 0.1),
                       lower_bounds = list(lambda = 0,alpha_intra = 0,alpha_inter = 0),
                       upper_bounds = list(lambda = 100,alpha_intra = 1,alpha_inter = 1),
                       bootstrap_samples = 3)
  summary(sp_fit)

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