IDE: Construct IDE object, fit and predict

Description

The integro-difference equation (IDE) model is constructed using the function IDE, fitted using the function IDE.fit and used for prediction using the function predict.

Usage

IDE(
  f,
  data,
  dt,
  process_basis = NULL,
  kernel_basis = NULL,
  grid_size = 41,
  forecast = 0,
  hindcast = 0
)
fit.IDE(object, method = "DEoptim", fix = list(), ...)
# S3 method for IDE
predict(object, newdata = NULL, covariances = FALSE, ...)

Arguments

R formula relating the dependent variable (or transformations thereof) to covariates

data

data object of class STIDF

object of class difftime identifying the temporal discretisation used in the model

process_basis

object of class Basis as defined in the package FRK

kernel_basis

a list of four objects of class Basis as defined in the package FRK. The first corresponds to the spatial decomposition of the kernel amplitude, the second to the kernel aperture, the third to the kernel horizontal offset, and the fourth to the kernel vertical offset. If left NULL, a spatially-invariant kernel is assumed

grid_size

an integer identifying the number of grid points to use (in one dimension) for numerical integrations

forecast

an integer indicating the number of steps to forecast (where each step corresponds to one difftime)

hindcast

an integer indicating the number of steps to hindcast (where each step corresponds to one difftime)

object

object of class IDE to for fitting or predicting

method

method used to estimate the parameters. Currently only "DEoptim" is allowed, which calls an evolution algorithm from the package DEoptim

fix

list of parameters which are fixed and not estimated (e.g., list(sigma2_eps = 0.01)). Currently only the measurement-error variance (sigma2_eps) can be fixed

...

other parameters passed to DEoptim or predict

newdata

data frame or object of class STIDF containing the spatial and temporal points at which to predict

covariances

a flag indicating whether prediction covariances should be returned or not when predicting

Value

Object of class IDE that contains get and set functions for retrieving and setting internal parameters, the function update_alpha which predicts the latent states, update_beta which estimates the regression coefficients based on the current predictions for alpha, and negloglik, which computes the negative log-likelihood.

Details

The first-order spatio-temporal IDE process model used in the package IDE is given by $$Y_t(s) = \int_{D_s} m(s,x;\theta_p) Y_{t-1}(x) \; dx + \eta_t(s); \;\;\; s,x \in D_s,$$ for $t=1,2,\ldots$, where $m(s,x;\theta_p)$ is a transition kernel, depending on parameters $\theta_p$ that specify ``redistribution weights'' for the process at the previous time over the spatial domain, $D_s$, and $\eta_t(s)$ is a time-varying (but statistically independent in time) continuous mean-zero Gaussian spatial process. It is assumed that the parameter vector $\theta_p$ does not vary with time. In general, $\int_{D_s} m(s,x;\theta_p) d x < 1$ for the process to be stable (non-explosive) in time.

The redistribution kernel $m(s,x;\theta_p)$ used by the package IDE is given by $$m(s,x;\theta_p) = {\theta_{p,1}(s)} \exp\left(-\frac{1}{\theta_{p,2}(s)}\left[(x_1 - \theta_{p,3}(s) - s_1)^2 + (x_2 - \theta_{p,4}(s) - s_2)^2 \right] \right),$$ where the spatially-varying kernel amplitude is given by $\theta_{p,1}(s)$ and controls the temporal stationarity, the spatially-varying length-scale (variance) parameter $\theta_{p,2}(s)$ corresponds to a kernel scale (aperture) parameter (i.e., the kernel width increases as $\theta_{p,2}$ increases), and the mean (shift) parameters $\theta_{p,3}(s)$ and $\theta_{p,4}(s)$ correspond to a spatially-varying shift of the kernel relative to location $s$. Spatially-invariant kernels (i.e., where the elements of $\theta_p$ are not functions of space) are assumed by default. The spatial dependence, if present, is modelled using a basis-function decomposition.

IDE.fit() takes an object of class IDE and estimates all unknown parameters, namely the parameters $\theta_p$ and the measurement-error variance, using maximum likelihood. The only method currently used is the genetic algorithm in the package DEoptim. This has been seen to work well on several simulation and real-application studies on multi-core machines.

Once the parameters are fitted, the IDE object is passed onto the function predict() in order to carry out optimal predictions over some prediction spatio-temporal locations. If no locations are specified, the spatial grid used for discretising the integral at every time point in the data horizon are used. The function predict returns a data frame in long format. Change-of-support is currently not supported.

Examples

Run this code

# NOT RUN {
SIM1 <- simIDE(T = 5, nobs = 100, k_spat_invariant = 1)
IDEmodel <- IDE(f = z ~ s1 + s2,
                data = SIM1$z_STIDF,
                dt = as.difftime(1, units = "days"),
                grid_size = 41)
# }
# NOT RUN {
#fit_results_sim1 <- fit.IDE(IDEmodel,
#                            parallelType = 1)
#ST_grid_df <- predict(fit_results_sim1$IDEmodel)
# }