Composite {s2dv}

Compute composites

Description

Composite a multi-dimensional array which contains two spatial and one temporal dimensions, e.g., (lon, lat, time), according to the indices of mode/cluster occurrences in time. The p-value by t-test is also computed.

Usage

Composite(
  data,
  occ,
  time_dim = "time",
  space_dim = c("lon", "lat"),
  lag = 0,
  eno = FALSE,
  K = NULL,
  fileout = NULL,
  ncores = NULL
)

Arguments

data

A numeric array containing two spatial and one temporal dimensions.

occ

A vector of the occurrence time series of mode(s)/cluster(s). The length should be the same as the temporal dimension in 'data'. (*1) When one wants to composite all modes, e.g., all K = 3 clusters then for example occurrences could look like: 1 1 2 3 2 3 1 3 3 2 3 2 2 3 2. (*2) Otherwise for compositing only the 2nd mode or cluster of the above example occurrences should look like 0 0 1 0 1 0 0 0 0 1 0 1 1 0 1.

time_dim

A character string indicating the name of the temporal dimension in 'data'. The default value is 'time'.

space_dim

A character vector indicating the names of the spatial dimensions in 'data'. The default value is c('lon', 'lat').

lag

An integer indicating the lag time step. E.g., for lag = 2, +2 occurrences will be used (i.e., shifted 2 time steps forward). The default value is 0.

eno

A logical value indicating whether to use the effective sample size (TRUE) or the total sample size (FALSE) for the number of degrees of freedom. The default value is FALSE.

K

A numeric value indicating the maximum number of composites. The default value is NULL, which means the maximum value provided in 'occ' is used.

fileout

A character string indicating the name of the .sav output file The default value is NULL, which means not to save the output.

ncores

An integer indicating the number of cores to use for parallel computation. The default value is NULL.

Value

A list containing:

$composite

A numeric array of the spatial dimensions and new dimension 'K' first, followed by the same dimensions as parameter 'data'. The length of dimension 'K' is parameter 'K'.

$p.val

A numeric array with the same dimension as $composite. It is the p-value of the composites obtained through a t-test that accounts for the serial dependence of the data.

Examples

blank <- array(0, dim = c(20, 10, 30))
x1 <- blank
t1 <- blank
f1 <- blank

for (i in 1:20) {
 x1[i, , ] <- i
}

for (i in 1:30) {
 t1[, , i] <- i
}

# This is 2D propagating sin wave example, where we use f1(lon, lat, time) 
# wave field. Compositing (like using stroboscopicc light) at different
# time steps can lead to modification or cancelation of wave pattern.

for (i in 1:20) {
 for (j in 1:30) {
   f1[i, , j] <- 3 * sin(2 * pi * x1[i, , j] / 5. - 2 * pi * t1[i, , j] / 6.)
 }
}
names(dim(f1)) <- c('lon', 'lat', 'time')
occ <- rep(0, 30)
occ[c(2, 5, 8, 11, 14, 17, 20, 23)] <- 1
res <- Composite(data = f1, occ = occ)
filled.contour(res$composite[, , 1])

occ <- rep(0, 30)
occ[c(3, 9, 15, 21)] <- 1
res <- Composite(data = f1, occ = occ)
filled.contour(res$composite[, , 1])

# Example with one missing composite in occ:
data <- 1:(4 * 5 * 6)
dim(data) <- c(lon = 4, lat = 5, case = 6)
occ <- c(1, 1, 2, 2, 3, 3) 
res <- Composite(data, occ, time_dim = 'case',  K = 4)