eicm.fit {eicm}

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)
)

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.

Value

A fitted eicm object.

Note

If estimating latent variables and species interactions, use eicm instead.

See Also

eicm, confint.eicm, plot.eicm

Examples

# 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)


# 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)