spagmix (version 0.3-5)

stkey: Spatiotemporal density generation via keyframe interpolation

Description

Uses the supplied spatial pixel images and scalings to linearly interpolate the behaviour of the function over time, creating a trivariate density function in space-time.

Usage

stkey(start, stop, tlim, kf = NULL, tres = 64,
      kftimes = NULL, fscales = NULL, window = NULL)

Arguments

start

The spatial pixel image corresponding to the spatial density at start of the time interval. May be unnormalised, the function internally rescales all supplied spatial images to integrate to 1.

stop

The pixel image for the end of the time interval. Must be compatible with start, in that it is defined over the same spatial domain and is of identical resolution.

tlim

A numeric vector of length 2 representing the temporal window i.e. the time interval over which the interpolation takes place.

kf

A solist of the pixel images of the keyframes between start and stop. If supplied, each image must be compatible with start and stop. If unsupplied, the resulting interpolation is performed only on start and stop

tres

The resolution of the resulting array in the time dimension (default is 64).

kftimes

A vector of times that position the interim keyframes in kf between tlim[1] and tlim[2]. Ignored if kf = NULL. If unsupplied (NULL), but kf is present, the function simply positions the images of kf at evenly spaced time points in the tlim interval.

fscales

A numeric vector of unnormalised, relative point-intensity scales. This may be provided either as of length(kf) + 2, so the point intensities assinged to each frame in the order c(start,<entries of kf>,stop), or of length tres. If unsupplied, each spatial frame is simply given equal weight. See `Details'.

window

An object of class owin giving the polygonal spatial observational window on which the density is defined. If NULL, the polygon is simply obtained from the union of pixel values in the supplied images.

Value

Like stgmix, an object of class stim giving the trivariate density. This is a list with six components:

a

The xr \(x\) yr \(x\) tres array of the specified density (where xr and yr are used here to denote the spatial resolution along the x- and y-axes; this is governed in stkey by the images initally supplied to start and stop).

v

A pixel image version of a, provided as a solist of length tres, with each member being the spatial image slice of the 3D density at each of the time-coordinate values.

xcol

Grid coordinates in the spatial x-axis (corresponds to each spatial image in v).

yrow

Grid coordinates in the spatial y-axis (corresponds to each spatial image in v).

tlay

Grid coordinates in the temporal axis (corresponds to the order of the spatial images in v).

W

A copy of window, the spatial owin upon which the density is defined.

Details

This function interpolates in a pixel-wise fashion between the im objects supplied as start and stop (and kf if supplied), placing them as keyframes at the times in tlim (for start and stop) and kftimes (for the members of kf). The final result is rescaled such that its total integrated volume over the defined spatiotemporal domain is 1, yeilding a trivariate density function.

If fscale is a vector of length tres, each element will correspond to the relative overall scaling of one of the resulting interpolated pixel images. If it is of length length(kf) + 2, the scales will correspond to start, each keyframe in kf and stop in that order. The values in this argument are only interpretable in a relative sense: for example, with a single keyframe suppled to kf (in addition to the required start and stop), then fscales = c(0.5,1,0.5) has exactly the same effect on the final result as fscales = c(1,2,1), and is interpreted as yielding a point density that reaches twice the concentration at the time of the supplied keyframe relative to the start and stop margins. Supplying fscale as a vector of length tres thus allows finer control over the relative point density over time, such as for the incorporation of harmonic seasonal variation.

Examples

# NOT RUN {
mn <- matrix(c(0,0,1,2,0.5,-1),nrow=2)
vr <- array(c(0.2,0,0,2,1,0,0,1,1,0.3,0.3,0.5),dim=c(2,2,3))
im1 <- sgmix(mn,c(1,2,1),shp1,p=c(0.4,0.3,0.3))
im2 <- sgmix(matrix(c(-3,0,0,-2,-1,2),nrow=2),c(3,1,1),shp1,p=c(0.4,0.3,0.3))
im3 <- sgmix(mn,vr,shp1,p0=0.1)

kf1 <- stkey(start=im1,stop=im2,tlim=c(5,20),window=shp1)
plot(kf1)

kf2 <- stkey(start=im1,stop=im1,tlim=c(0,15),kf=solist(im1,im1),kftimes=c(2,8),
             fscale=c(1,2,1.5,1),window=shp1)
plot(kf2,fix.range=TRUE)

kf3 <- stkey(start=im1,stop=im2,tlim=c(0,20),kf=solist(im1,im2),kftimes=c(8,12),
             fscale=c(1,2,2,1),window=shp1)
plot(kf3,fix.range=TRUE)

ff <- c(sin((1:64)/3)+1.5)
plot(ff,type="l")
kf4 <- stkey(start=im1,stop=im2,kf=solist(im3),kftimes=25,tlim=c(0,50),fscale=ff,window=shp1)
plot(kf4,fix.range=TRUE)
# }