transport_track {transport}

Create a Dynamic Visualization of a Transference Plan Between Two pgrids

Description

Given two objects source and target of class pgrid and a transference plan, typically the result of a call to transport, create an animation of the dynamic transference plan (a.k.a. displacement interpolation)

Usage

  transport_track(source, target, tplan, K = 50, scmult = 1, smooth = FALSE,
     H = matrix(c(1,0,0,1),2,2), create.file = c("none","gif_im"), 
     file.name = "Rtransport.gif", fps = 20, cut = FALSE,
     col=grey((0:1000)/1000),width=800,height=800)

Arguments

source, target

objects of class pgrid.

tplan

a transference plan between source and target, typically an optimal transference plan obtained by a call to transport.

K

the number of intermediate frames to be produced between source and target.

scmult

the factor by which the number of pixels in each dimension is multiplied to obtain a smoother rendering of the dynamic transference plan.

smooth

logical. Whether a kernel smoothing or a linear binning procedure is used to generate the images. Defaults to FALSE.

H

the bandwith matrix used to perform the two dimensional kernel density estimation or the linear binning respectively.

create.file

the file type to be created or "none" to return only an array of intermediate mass distributions.

file.name

the path for the output file. Ignored if create.file is "none".

fps

the number of frames per second in the generated gif. The default is 20 frames per second.

cut

logical. Whether the boundary pixels are cut off. Currently the only way to deal with the edge effect (see Details).

col

the vector of RGB colours which is used to generate the gif, if create.file is not "none". See the documentation of image for more details.

width

interger specifying the width of the images used to generate the output gif, if create.file is not "none".

height

interger specifying the width of the images used to generate the output gif, if create.file is not "none".

Details

The intermediate frames are produced by the interpolation formula [(1-t)\mathrm{pr}_1 + t\mathrm{pr}_2]_{\#} \pi, where \pi is the transference plan, \mathrm{pr}_1 and \mathrm{pr}_2 are the first and second coordinate projections of \mathbf{R}^2 \times \mathbf{R}^2 onto \mathbf{R}^2, and t \in \{0,1/(K+1), \ldots, K/(K+1),1\}. If \pi is an optimal transference plan this yields the displacement interpolation, at least if we assume as underlying cost function the Euclidean metric to the p-th power, where p = 1,2.

The kernel smoothing procedure gives usually nicer animations, but takes several orders of magnitudes longer.

There are currently visible edge effects in both the kernel smoothing and the linear binning procedure that lead to darker pixels at the boundary of the image. The cut parameter may be used to remove the boundary pixels completely and thus produce a smaller output. The edge will be dealt with more adequatly in future versions.

Conversion to an animated gif is performed by a system call to the convert tool of ImageMagick. The latter may have to be installed first.

Value

An array containing the various interpolation images.

Unless create.file="none", the function is mainly used for its side effect (saving a file to the specified path). So the array is returned invisibly.

Warning

Running this function with smooth=TRUE and even moderate K can take a long time!

Author(s)

Florian Heinemann [e-mail]
(slightly modified by Dominic Schuhmacher [e-mail])

See Also

Function transport for computing optimal transference plans.

Examples

if (requireNamespace("ks", quietly = TRUE)) {
  tplan <- transport(random32a,random32b)
  series <- transport_track(random32a, random32b, tplan, scmult=3, create.file="none")
  dev.new(width=16,height=8)
  oldpar <- par(mfrow=c(5,10), mai=rep(0.01,4))
  for (i in 1:50) { 
    image(series[,,i], col=grey(seq(0,1,0.005)), asp=1, axes=FALSE,zlim=c(min(series),max(series)))
  }
  par(oldpar)
}