fitCLS_map: Map-level CLS for time series

Description

fitCLS_map is used to fit conditional least squares regression to each spatial location (pixel) within spatiotemporal data.

Usage

fitCLS_map(
  Y,
  coords,
  formula = "y ~ t",
  X.list = list(t = 1:ncol(Y)),
  lag.y = 1,
  lag.x = 0,
  resids.only = FALSE
)

Value

fitCLS_map returns a list object of class "mapTS".

The output will always contain at least these elements:

call: the function call

coords

the coordinate matrix or dataframe

residuals

time series residuals: rows correspond to pixels (coords)

When resids.only = FALSE, the output will also contain the following components. Matrices have rows that correspond to pixels and columns that correspond to time points and vector elements correspond to pixels.

coefficients: a numeric matrix of coefficeints

SEs

a numeric matrix of coefficient standard errors

tstats

a numeric matrix of t-statistics for coefficients

pvals

a numeric matrix of p-values for coefficients t-tests

MSEs

a numeric vector of MSEs

logLiks

a numeric vector of log-likelihoods

fitted.values

a numeric matrix of fitted values

An attribute called "resids.only" is also set to match the value of resids.only

Arguments

Y: a spatiotemporal response variable: a numeric matrix or data frame where columns correspond to time points and rows correspond to pixels.
coords: a numeric coordinate matrix or data frame, with two columns and rows corresponding to each pixel
formula: a model formula, passed to fitCLS(): the left side of the formula should always be "y" and the right hand side should refer to variables in X.list
X.list: a named list of temporal or spatiotemporal predictor variables: elements must be either numeric vectors with one element for each time point or a matrix/data frame with rows corresponding to pixels and columns corresponding to time point. These elements must be named and referred to in formula
lag.y: the lag between y and y.0, passed to fitCLS()
lag.x: the lag between y and predictor variables, passed to fitCLS()
resids.only: logical: should output beyond coordinates and residuals be withheld? Useful when passing output to fitCor()

Details

fitCLS_map is a wrapper function that applies fitCLS() to many pixels.

The function loops through the rows of Y, matched with rows of spatiotemporal predictor matrices. Purely temporal predictors, given by vectors, are used for all pixels. These predictor variables, given by the right side of formula are sourced from named elements in X.list.

Examples

Run this code


# simulate dummy data
time.points = 9 # time series length
map.width = 5 # square map width
coords = expand.grid(x = 1:map.width, y = 1:map.width) # coordinate matrix
## create empty spatiotemporal variables:
X <- matrix(NA, nrow = nrow(coords), ncol = time.points) # response
Z <- matrix(NA, nrow = nrow(coords), ncol = time.points) # predictor
# setup first time point:
Z[, 1] <- .05*coords[,"x"] + .2*coords[,"y"]
X[, 1] <- .5*Z[, 1] + rnorm(nrow(coords), 0, .05) #x at time t
## project through time:
for(t in 2:time.points){
  Z[, t] <- Z[, t-1] + rnorm(map.width^2)
  X[, t] <- .2*X[, t-1] + .1*Z[, t] + .05*t + rnorm(nrow(coords), 0 , .25)
}

# # visualize dummy data (NOT RUN)
# library(ggplot2);library(dplyr)
# data.frame(coords, X) %>%
#   reshape2::melt(id.vars = c("x", "y")) %>%
#   ggplot(aes(x = x, y = y, fill = value)) +
#   geom_tile() +
#   facet_wrap(~variable)

# fit CLS, showing all output
fitCLS_map(X, coords, formula = y ~ t, resids.only = TRUE)

# fit CLS with temporal and spatiotemporal predictors
(CLS.map <- fitCLS_map(X, coords, formula = y ~ t + Z,
                       X.list = list(t = 1:ncol(X), Z = Z),
                       resids.only = FALSE))
## extract some values
CLS.map$coefficients # coefficients
CLS.map$logLik # log-likelihoods

## Methods
summary(CLS.map)
residuals(CLS.map)
coefficients(CLS.map)