ecomem: Function for quantifying ecological memory within a...
In msitter/EcoMem: Functions to Estimate Ecological Memory

Description Usage Arguments Details Value Author(s) See Also Examples

Estimates ecological memory functions for a specified subset of covariates and a continuous response within a linear model framework. The function is a wrapper to ecomemMCMC which implements Markov chain Monte Carlo (MCMC) simulation to fit a Bayesian hierarchical model estimating ecological memory.

ecomem(formula, data, mem.vars, L, timeID, groupID = NA,
       starting = NULL, smooth = NULL, n.post = 1000, thin = 10,
       burn.in = 5000, n.step = 5, n.chains = 3, parallel = TRUE,
       max.cpu = NULL, inputs.only = FALSE, ...)

`formula`	an object of class `formula` providing a symbolic representation of the linear regression model to be fit.
`data`	a data frame including the response, explanatory, group, and time index variables.
`mem.vars`	an optional character vector indicating the subset of explanatory variables for which ecological memory functions should be estimated (memory variables).
`L`	an integer or an integer vector specifying the maximum lag for memory variables. If a vector is specified, its dimension must match the number of memory variables specified in `mem.vars`.
`timeID`	a character value indicating the time index variable within `data`.
`groupID`	an optional character value indicating a group index variable within `data`. Only one `groupID` variable is allowed.
`starting`	optional list of starting values for model parameters. If specified, the length of the list must match `n.chains`. Each element of the `starting` list must be a named list with names and dimensions corresponding to model parameters. Valid names include `beta`, `sig.y`, `mem`, and `tau.sq` (if `smooth = NULL`). The `mem` element, must be a list with length equal to the number of memory variables with elements `eta` and `w` providing starting values for spline basis function coefficients and memory function weights, respectively.
`smooth`	an optional vector with length equal to the number of memory variables specifying penalty parameters for penalized spline regression used to estimate ecological memory functions. If included, `tau.sq` is fixed within the model.
`n.post`	an optional scalar indicating the number of desired posterior MCMC samples post `burn.in`. Total number of samples is given by `burn.in` + `thin`*`n.post`. The default is set to 1000.
`thin`	an optional scalar indicating the thinning interval for posterior samples. The default is set to 10.
`burn.in`	an optional scalar indicating the number of burn-in samples for MCMC chains. The default is set to 5000.
`n.step`	an optional scalar indicating the number of basis function coefficient updates taken per iteration of the MCMC sampler. The default is set to 5.
`n.chains`	an optional scalar indicating the number of MCMC chains. The default is set to 3.
`parallel`	an optional `logical` indicating whether MCMC chains should be run in parallel. If `TRUE` (default), `n.chains` are run in parallel using `snowfall`.
`max.cpu`	an optional scalar indicating the maximum number of CPUs to utilize. Only evaluated if `parallel = TRUE`. The default CPU number is equal to `n.chains`.
`inputs.only`	an optional `logical` indicating whether model should be fit using MCMC within the `ecomem` function. If `TRUE` inputs for `ecomemMCMC` are returned, but no posterior samples. The default is set to `FALSE`.
`...`	currently no additional arguments.

Unequally-spaced time points are not supported. The timeID variable should include equally-spaced, sequential time points within each group. Modeled time periods for different groups may be non-overlapping, but the spacing of time points must be consistent among groups. Time points with NA values for the response and/or explanatory variables are dropped from the analysis. NA values are not supported in the timeID and groupID index variables.

Explanatory variable observations for L time points prior to the response are needed to fit the regression model when estimating ecological memory functions for a subset of covariates. If explanatory variable observations are not available for L time points prior to the response, the observation is not evaluated as part of the regression model. This is particularly important during model initialization. If explanatory variable observations are available prior to the initial response (first time point), the first max(L) responses for each group (if groupID is non-NULL) within data should be set to NA. Otherwise, the first max(L) response observations within each group will not be evaluated as part of the regression model.

An object of class ecomem, which is a list with the following elements:

`post.samps`	a list of posterior samples with length equal to `n.chains`. Each element is a named list with names corresponding to model parameters (`beta`, `sig.y`, `eta`, `w`, `X.tilde`, `tau.sq`). Returned only if `inputs.only = FALSE` (default).
`inputs`	a list of MCMC inputs with length equal to `n.chains`. Each element is a named list containing `inputs`, `priors`, and `starting` to be passed to `ecomemMCMC`. Returned only if `inputs.only = TRUE`.
`data`	a data frame containing data used to fit the regression model including a response variable with the first `max(L)` within each group set to `NA` and scaled values for all continuous explanatory variables.
`n`	an integer value indicating the number of reponse observations used to fit the regression model across all groups.

Malcolm S. Itter malcolm.itter@helsinki.fi

ecomemGLM

## Not run: 

####################################
#### Continuous covariate ##########
####################################

## Simulate some time series data

set.seed(1)

# Maximum lag
L = 10

# Sample size
n = 1000

# Total number of time points
TT = n + L

# Generate weights
w = exp(-0.5*(0:L))/sum(exp(-0.5*(0:L)))

# Simulate a single continuous covariate
x = scale(rnorm(TT,(1:TT)/1000+0.05*cos(
    2*pi*10*(1:TT)/TT),2.4),center=FALSE)

# Form matrix containing lagged covariate values
x.lag = t(sapply(1:n,function(i){
  x[(L+1):1 + i - 1]
}))

# Calculate weighted covariate values
x.tilde = x.lag%*%w

# Form design matrix
X = cbind(rep(1,n),x.tilde)

# Set model parameter values
beta = c(1.3,-0.4)
sig.y = 0.1

# Simulate from ecological memory model
y = c(rep(NA,L),rnorm(n,X%*%beta,sig.y))

# Form model data frame
data = data.frame(time=1:TT,x=x,y=y)

## Run ecomem function

mod = ecomem(y~x,data=data,mem.vars="x",L=L,timeID="time")

## Assess model convergence

post.samps = mem2mcmc(mod)
plot(post.samps,ask=T)

## Process results

coef.summ = memsum(mod)

p = plotmem(mod)
print(p)

####################################
#### Discrete covariate ############
####################################

## Simulate some time series data

set.seed(1)

# Maximum lag
L = 5

# Sample size
n = 500

# Total number of time points
TT = n + L

# Generate weights
w = exp(-0.95*(0:L))/sum(exp(-0.95*(0:L)))

# Simulate a single binary covariate
x = rbinom(TT,1,0.05)

# Form matrix containing lagged covariate values
x.lag = t(sapply(1:n,function(i){
  x[(L+1):1 + i - 1]
}))

# Calculate weighted covariate values
x.tilde = x.lag%*%w

# Form design matrix
X = cbind(rep(1,n),x.tilde)

# Define model parameters
beta = c(2.5,3.4)
sig.y = 0.2

# Simulate from ecological memory model
y = c(rep(NA,L),rnorm(n,X%*%beta,sig.y))

# Form model data frame
data = data.frame(time=1:TT,x=x,y=y)

## Run ecomem function

mod = ecomem(y~x,data=data,mem.vars="x",L=L,timeID="time")

## Assess model convergence

post.samps = mem2mcmc(mod)
plot(post.samps,ask=T)

## Process results

coef.summ = memsum(mod)

p = plotmem(mod)
print(p)

## End(Not run)