eicm.fit: Estimate a EICM model

Description

Estimates the parameter values of a EICM model from the provided observation data. This is the low-level estimation function. Users should use eicm instead, particularly if estimating latent variables and species interactions.

Usage

eicm.fit(
  occurrences,
  env = NULL,
  traits = NULL,
  intercept = TRUE,
  n.latent = 0,
  forbidden = NULL,
  allowed = NULL,
  mask.sp = NULL,
  exclude.prevalence = 0,
  options = NULL,
  initial.values = NULL,
  regularization = c(ifelse(n.latent > 0, 0.5, 0), 1),
  regularization.type = "hybrid",
  fast = FALSE,
  n.cores = 1,
  optim.method = "L-BFGS-B",
  optim.control = list(trace = 1, maxit = 10000, ndeps = 1e-04, factr = ifelse(fast,
    1e-04, 1e-06)/.Machine$double.eps)
)

Value

A fitted eicm object.

Arguments

occurrences: a binary (0/1) sample x species matrix, possibly including NAs.
env: an optional sample x environmental variable matrix, for the known environmental predictors.
traits: an optional species x trait matrix. Currently, it is only used for excluding species interactions a priori.
intercept: logical specifying whether to add a column for the species-level intercepts.
n.latent: the number of latent variables to estimate.
forbidden: a formula (or list of) defining which species interactions are not to be estimated. See details. This constraint is cumulative with other constraints (mask.sp and exclude.prevalence).
allowed: a formula (or list of) defining which species interactions are to be estimated. See details. This constraint is cumulative with other constraints (mask.sp and exclude.prevalence).
mask.sp: a scalar or a binary square species x species matrix defining which species interactions to exclude (0) or include (1) a priori. If a scalar (0 or 1), 0 excludes all interactions, 1 allows all interactions. If a matrix, species in the columns affect species in the rows, so, setting mask.sp[3, 8] <- 0 means that species #8 is assumed a priori to not affect species #3. This constraint is cumulative with other constraints (forbidden and exclude.prevalence).
exclude.prevalence: exclude species interactions which are caused by species with prevalence equal or lower than this value. This constraint is cumulative with other constraints (forbidden and mask.sp)
options: a eicm.options object defining options for fitting. Usually not needed, use forbidden, mask.sp and exclude.prevalence instead.
initial.values: the starting values for all parameters. Used only for speeding up fitting when there are previous estimates available.
regularization: a two-element numeric vector defining the regularization lambdas used for environmental coefficients and for species interactions respectively. See details.
regularization.type: one of "lasso", "ridge" or "hybrid", defining the type of penalty to apply. Type "hybrid" applies ridge penalty to environmental coefficients and LASSO to interaction coefficients.
fast: a logical defining whether to do a fast - but less accurate - estimation, or a normal estimation.
n.cores: the number of CPU cores to use in the L-BFGS-B optimization. This may be reduced to prevent excessive memory usage.
optim.method: the optimization function to use. Should be set to the default.
optim.control: the optimization parameters to use. Should be set to the defaults.

Details

By default, all species interactions are estimated. Uers can control which species interactions are to be estimated with the arguments forbidden, mask.sp and exclude.prevalence, which place cumulative restrictions on which interactions to estimate. See vignette("eicm") for commented examples.

Examples

Run this code

# Simulate some random occurrence data
nenv <- 2
nsp <- 10
nsamples <- 200

env <- matrix(rnorm(nenv * nsamples), ncol=nenv, nrow=nsamples)
env.coefs <- matrix(runif((nenv + 1) * nsp, -4, 4), nrow=nsp)
sp.coefs <- matrix(0, nrow=nsp, ncol=nsp)
sp.coefs[3, 5] <- 3
sp.coefs[4, 8] <- 2

# Define a true model
truemodel <- as.eicm(env=env, env.coefs=env.coefs, sp.coefs=sp.coefs)

# realize the model
simulated.data <- predict(truemodel, nrepetitions=1)

# \donttest{
# fit the model without species interactions
fittedNoInt <- eicm.fit(simulated.data, env, mask.sp=0)

# fit the model with all species interactions
fittedInt <- eicm.fit(simulated.data, env, mask.sp=1)

# compute confidence intervals for all parameters
fittedInt <- confint(fittedInt, ncores=2)

# plot estimated parameters and confidence intervals
plot(fittedInt, type="confint", truemodel=truemodel)
# }