Integro-difference equation

Description

The Integro-Difference Equation model is a linear, dynamical model used to model phenomena that evolve in space and in time. At the heart of the model is the kernel, which dictates how the process evolves from one time point to the next. Both process and parameter reduction are used to facilitate computation, and spatially-varying kernels are allowed. Data used to estimate the parameters are assumed to be readings of the process corrupted by Gaussian measurement error. Parameters are fitted by maximum likelihood, and estimation is carried out using an evolution algorithm.

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 class 'IDE'
predict(object, newdata = NULL, covariances = FALSE, ...)

Arguments

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.

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.

See Also

show_kernel for plotting the kernel

Examples

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)

#fit_results_sim1 <- fit.IDE(IDEmodel,
#                            parallelType = 1)
#ST_grid_df <- predict(fit_results_sim1$IDEmodel)

Retrieve estimated regression coefficients

Description

Takes a an object of class IDE and returns a numeric vector with the estimated regression coefficients.

Usage

## S3 method for class 'IDE'
coef(object, ...)

Arguments

See Also

IDE for more information on how to construct and fit an IDE model.

Examples

SIM1 <- simIDE(T = 5, nobs = 100, k_spat_invariant = 1)
coef(SIM1$IDEmodel)

Create a single, constant basis function

Description

Constructs an object of class Basis as defined in FRK that is constant over the entire spatial domain.

Usage

constant_basis()

Value

Object of class Basis

See Also

IDE for how to use basis functions to construct the IDE kernel

Examples

basis1 <- constant_basis()

Show IDE kernel

Description

Plotting function for visualising the IDE kernel.

Usage

show_kernel(IDEmodel, scale = 1)

Arguments

Details

The function show_kernel adapts its behaviour to the type of kernel. If the kernel is spatially-invariant, then the kernel with s evaluated at the origin is plotted. If spatially-variant, then arrows on a regular grid over the domain are plotted. The direction of the arrow is indicative of the transport direction at a specific location, while the length of the arrow is indicative of the transport intensity.

See Also

IDE for details on the IDE model.

Examples

SIM1 <- simIDE(T = 5, nobs = 100, k_spat_invariant = 0)
show_kernel(SIM1$IDEmodel)

Simulate datasets from the IDE model

Description

Generates simulations that are then used to evaluate the fitting and prediction of an IDE model.

Usage

simIDE(T = 9, nobs = 100, k_spat_invariant = 1, IDEmodel = NULL)

Arguments

Details

The domain considered is [0,1] x [0,1], and an IDE is simulated on top of a fixed effect comprising of an intercept, a linear horizontal effect, and a linear vertical effect (all with coefficients 0.2). The measurement-error variance and the variance of the additive disturbance are both 0.0001. When a spatially-invariant kernel is used, the following parameters are fixed: \theta_{p,1} = 150, \theta_{p,2} = 0.002, \theta_{p,3} = -0.1, and \theta_{p,4} = 0.1. See IDE for details on these parameters. When a spatially-varying kernel is used, \theta_{p,1} = 200, \theta_{p,2} = 0.002, and \theta_{p,3}(s), \theta_{p,4}(s) are smooth spatial functions simulated on the domain.

Value

A list containing the simulated process in s_df, the simulated data in z_df, the data as STIDF in z_STIDF, plots of the process and the observations in g_truth and g_obs, and the IDE model used to simulate the process and data in IDEmodel.

See Also

show_kernel for plotting the kernel and IDE

Examples

SIM1 <- simIDE(T = 5, nobs = 100, k_spat_invariant = 1)
SIM2 <- simIDE(T = 5, nobs = 100, k_spat_invariant = 0)