Map and extract data: Functions for remapping, changing the resolution, and extracting from 2-D or 3-D data.

Description

S3 functions remap maps a variable (var) (a matrix or array) with x, y (and z) coordinates to a matrix or array with coordinates given by xto, yto (and zto). x, y, z, xto, yto and zto are all vectors. The functions interpolate to all combinations of xto, yto and zto. Simple 2-D linear interpolation is used. Result is a matrix or array.

Function changeres changes the resolution of a variable (var) (a matrix or array) with x, y (and z) coordinates. If var is a matrix, then x, y can be either a vector or a matrix; if var is an array, then x, y, z should all be vectors. Simple 2-D linear interpolation is used. Result is a matrix or array.

S3-functions extract map a variable (var) from a matrix with (x, y) coordinates or from an array with (x, y, z) coordinates to the xy coordinate pair xyto or xyz coordinate triplets xyzto by linear interpolation. Result is a vector.

transect takes a cross section across an array (var). Result is a matrix.

mapsigma maps a matrix or array var containing values defined at (x, sigma) (or (x, y, sigma)) coordinates to (x, depth) (or (x, y, depth)) coordinates. The depths corresponding to the sigma values in var are in an input matrix or array called sigma with same dimensions as var. The result is a matrix or array which will contain NAs where the depth-coordinates extend beyond the sigma values.

Usage

remap        (var, ...)
  
# S3 method for matrix
remap(var, x, y, xto = NULL, yto = NULL, 
          na.rm = TRUE, ...)
# S3 method for array
remap(var, x, y, z, xto = NULL, yto = NULL, zto = NULL, 
          na.rm = TRUE, ...)
changeres    (var, ...)
  
# S3 method for matrix
changeres(var, x, y, resfac, na.rm = TRUE, ...)
# S3 method for array
changeres(var, x, y, z, resfac, na.rm = TRUE, ...)
extract    (var, ...)
# S3 method for matrix
extract(var, x, y, xyto, ...)
# S3 method for array
extract(var, x, y, z, xyzto, ...)
transect(var, x, y, z, to, margin = "xy", ...)
mapsigma   (var, ...)
  
# S3 method for matrix
mapsigma(var = NULL, sigma, signr = 2, x = NULL,  
    depth = NULL, numdepth = NULL, xto = NULL, resfac = 1, ...)
    
# S3 method for array
mapsigma(var = NULL, sigma, signr = 3, x = NULL, y = NULL, 
    depth = NULL, numdepth = NULL, xto = NULL, yto = NULL, 
    resfac = 1, ...)
transectsigma(var = NULL, sigma, x, y, to, depth = NULL, 
                numdepth = NULL, resfac = 1, ...)

Value

remap.matrix:

var: The higher or lower resolution matrix with dimension = c(length(xto), length(yto)).
x: The x coordinates, corresponding to first dimension of var (input argument xto).
y: The y coordinates, corresponding to second dimension of var (input argument yto).

remap.array:

var: The higher or lower resolution array, with dimension = c(length(xto), length(yto), length(zto)).
x: The x coordinates, corresponding to first dimension of var (input argument xto).
y: The y coordinates, corresponding to second dimension of var (input argument yto).
z: The z coordinates, corresponding to third dimension of var (input argument zto).

extract.matrix:

var: The higher or lower resolution object, with dimension = c(nrow(xyto), dim(var)[3]).
xy: The pairs of (x,y) coordinates (input argument xyto).

extract.array:

var: The higher or lower resolution object, with dimension = c(nrow(xyzto), dim(var)[3]).
xyz: The triplets of (x,y,z) coordinates (input argument xyzto).

mapsigma:

var: A matrix with columns in depth-coordinates.
depth: The depth-coordinates, also known as 'z'-coordinates, referring to the dimension of var as specified by signr.
x: The 'x'-coordinates referring to the first dimension of var, except for the depth.
y: Only if var is an array, the 'y'-coordinates referring to the second dimension of var, except for the depth.

Arguments

var: Matrix or array with values to be mapped to other coordinates (remap), or to lower or higher resolution (changeres), or whose values have to be extracted (extract, transect), or which has to be mapped from sigma to depth coordinates (mapsigma). For transect and transectsigma, var has to be an array.
x: Vector with original x-coordinates of the matrix or array var to be mapped. Length should be = first dimension of var.
y: Vector with original y-coordinates of the matrix or array var to be mapped. Length should be = second dimension of var.
z: Vector with original z-coordinates of the array var to be mapped. Length should be = third dimension of var.
xto: Vector with x-coordinates to which var should be mapped. The elements in xto should be embraced by the elements in x (it is not allowed to extrapolate outside of the region). If NULL then the range of x is covered, with the same number of points.
yto: Vector with y-coordinates to which var should be mapped. The elements in yto should be embraced by the elements in y (it is not allowed to extrapolate outside of the region). If NULL then the range of y is covered, with the same number of points.
zto: Vector with z-coordinates to which var should be mapped. The elements in zto should be embraced by the elements in z (it is not allowed to extrapolate outside of the region). If NULL then the range of z is covered, with the same number of points.
xyto: Two-columned matrix, with first and second column specifying the x- respectively y-coordinates to which the matrix var should be mapped. The elements should be embraced by the elements in x (first column) and y (second column) (it is not allowed to extrapolate outside of the region).
xyzto: Three-columned matrix, specifying the x-, y- and z-coordinates to which the array var should be mapped. The elements should be embraced by the elements in x, y and z (it is not allowed to extrapolate outside of the region).
to: Two-columned matrix, specifying the values along the margin coordinates of the transect to be taken on the array var. The elements should be embraced by the elements in x, y and z (it is not allowed to extrapolate outside of the region).
margin: String with the names of the coordinates in the matrix to, and along which the transect is to be taken on the array var. One of "xy", "xz", "yz". If "xy", then the first and second column in input to represent x and y values respectively, and the transect will select all z values corresponding with these inputs.
sigma: The sigma coordinates, a matrix or array with the same dimension as var. The sigma coordinates should refer to the column as defined by signr.
signr: The position of the sigma coordinates, in the matrix or array. The default is the second or third dimension in var for a matrix and array respectively.
depth: The depth (often referred to as 'z') coordinates to which matrix var has to be mapped. If NULL then seq(min(sigma), max(sigma), length.out = numdepth).
numdepth: Only used when depth= NULL, the length of the depth vector to which the matrix var has to be mapped. If NULL then the length will be equal to ncol(var) (if var is a matrix), or dim(var)[3] in case var is an array.
resfac: Resolution factor, one value or a vector of two or three numbers, for the x, y- and z- values respectively. A value > 1 will increase the resolution. For instance, if resfac equals 3 then for each adjacent pair of x- and y- values, var will be interpolated to two intermediary points. This uses simple linear interpolation. If resfac is one number then the resolution will be increased similarly in x, y- and z-direction. In case of mapsigma, resfac is overruled if xto, yto or zto is specified.
na.rm: How to treat NAs in the matrix or array var. If TRUE, they are ignored while interpolating; this will make the size of NA regions smaller; if FALSE, the size of the NA region will increase.
...: any other arguments.

Details

S3-function remap can be used to increase or decrease the resolution of a matrix or array var, or to zoom in on a certain area. It returns an object of the same class as var (i.e. a matrix or array).

S3-function transect takes a slice from an array; it returns a matrix.

S3-function extract returns a vector with one value corresponding to each row in xyto or xyzto.

mapsigma should be used to make images from data that are in sigma coordinates.

Examples

Run this code

# save plotting parameters
 pm <- par("mfrow")

## =======================================================================
## Simple examples
## =======================================================================
 M <- matrix(nrow = 2, data = 1:4)
 remap(M, x = 1:2, y = 1:2, 
   xto = seq(1, 2, length.out = 3), yto = 1:2) 
 
 changeres(M, x = 1:2, y = 1:2, resfac = c(2, 1))
 changeres(M, x = 1:2, y = 1:2, resfac = 2)

# x and or y are a matrix.
 changeres(var = M, x = M, y = 1:2, resfac = c(2, 1))
 changeres(M, x = M, y = 1:2, resfac = 2)

  
## =======================================================================
## Use remap to add more detail to a slice3D plot
## =======================================================================

 par(mfrow = c(1, 1))
 x <- y <- z <- seq(-4, 4, by = 0.5)
 M <- mesh(x, y, z)

 R <- with (M, sqrt(x^2 + y^2 + z^2))
 p <- sin(2*R) /(R+1e-3)

 slice3D(x, y, z, ys = seq(-4, 4, by = 2), theta = 85, 
   colvar = p, pch = ".", clim = range(p))

 xto <- yto <- zto <- seq(-1.2, 1.2, 0.3)
 Res <- remap (p, x, y, z, xto, yto, zto)

# expand grid for scatterplot
 Mt  <- mesh(Res$x, Res$y, Res$z)

 scatter3D(x = Mt$x, y = Mt$y, z = Mt$z, colvar = Res$var, 
   pch = ".", add = TRUE, cex = 3, clim = range(p))

# same in rgl:
 if (FALSE) {
   plotrgl()
 }

# extract specific values from 3-D data
 xyzto <- matrix(nrow = 2, ncol = 3, data = c(1,1,1,2,2,2), byrow = TRUE)
 extract(var = p, x, y, z, xyzto = xyzto)

# a transect
 to <- cbind(seq(-4, 4, length.out = 20), seq(-4, 4, length.out = 20))
 image2D( transect(p, x, y, z, to = to)$var)

## =======================================================================
## change the resolution of a 2-D image
## =======================================================================

 par(mfrow = c(2, 2))
 nr <- nrow(volcano)
 nc <- ncol(volcano)

 x  <- 1 : nr
 y  <- 1 : nc
 image2D(x = x, y = y, volcano, main = "original")

# increasing the resolution
 x2 <- seq(from = 1, to = nr, by = 0.5)
 y2 <- seq(from = 1, to = nc, by = 0.5)

 VOLC1 <- remap(volcano, x = x, y = y, xto = x2, yto = y2)$var
 image2D(x = x2, y = y2, z = VOLC1, main = "high resolution")

# low resolution
 xb <- seq(from = 1, to = nr, by = 2)
 yb <- seq(from = 1, to = nc, by = 3)
 VOLC2 <- remap(volcano, x, y, xb, yb)$var
 image2D(VOLC2, main = "low resolution")

# zooming in high resolution
 xc <- seq(10, 40, 0.1)
 yc <- seq(10, 40, 0.1)

 VOLC3 <- remap(volcano,x, y, xc, yc)$var
 image2D(VOLC3, main = "zoom")

# Get one value or a grid of values
 remap(volcano, x, y, xto = 2.5,     yto = 5)
 remap(volcano, x, y, xto = c(2, 5), yto = c(5, 10))

# Specific values
 extract(volcano, x, y, xyto = cbind(c(2, 5), c(5, 10)))
 
## =======================================================================
## take a cross section or transect of volcano
## =======================================================================
 
 par(mfrow = c(2, 1)) 
 image2D(volcano, x = 1:nr, y = 1:nc)
 xyto <- cbind(seq(from = 1,  to = nr, length.out = 20),
               seq(from = 20, to = nc, length.out = 20))
 points(xyto[,1], xyto[,2], pch = 16)

 (Crossection <- extract (volcano, x = 1:nr, y = 1:nc,
                             xyto = xyto))

 scatter2D(xyto[, 1], Crossection$var, colvar = Crossection$var, 
   type = "b", cex = 2, pch = 16)

## =======================================================================
##  mapsigma: changing from sigma coordinates into depth-coordinates
## =======================================================================

 par(mfrow = c(2, 2))
 var <- t(matrix (nrow = 10, ncol = 10, data = rep(1:10, times = 10)))
 image2D(var, ylab = "sigma", main = "values in sigma coordinates",
       clab = "var")

 # The depth at each 'column' 
 Depth <- approx(x = 1:5, y = c(10, 4, 5, 6, 4), 
                 xout = seq(1,5, length.out = 10))$y
 Depth <- rep(Depth, times = 10)
 
# Sigma coordinates
 sigma <- t(matrix(nrow = 10, ncol = 10, data = Depth, byrow = TRUE) * 
                seq(from = 0, to = 1, length = 10))
 matplot(sigma, type = "l", main = "sigma coordinates", 
         xlab = "sigma", ylab = "depth", ylim = c(10, 0))

# Mapping to the default depth coordinates
 varz <- mapsigma(var = var, sigma = sigma)
 image2D(varz$var, y = varz$depth, NAcol = "black", ylim = c(10, 0), 
       clab = "var", ylab = "depth", 
       main = "depth-coord, low resolution")

# Mapping at higher resolution of depth coordinates
 varz <- mapsigma(var, sigma = sigma, resfac = 10)
 image2D(varz$var, y = varz$depth, NAcol = "black", ylim = c(10, 0), 
       clab = "var", ylab = "depth", 
       main = "depth-coord, high resolution")

## =======================================================================
##  mapsigma: mapping to depth for data Sylttran (x, sigma, time)
## =======================================================================

# depth values 
 D <- seq(-1, 20, by = 0.5)
 dim(Sylttran$visc)

# sigma coordinates are the second dimension (signr)
# resolution is increased for 'x' and decreased for 'time'
 
 visc <- mapsigma(Sylttran$visc, x = Sylttran$x, y = Sylttran$time,
  sigma = Sylttran$sigma, signr = 2, depth = D, resfac = c(2, 1, 0.4))

# changed dimensions 
 dim(visc$var)

 image2D(visc$var, x = visc$x, y = -visc$depth, ylim = c(-20, 1), 
  main = paste("eddy visc,", format(visc$y, digits = 2), " hr"), 
  ylab = "m", xlab = "x", clab = c("","m2/s"), 
  clim = range(visc$var, na.rm = TRUE))
  
 par(mfrow = c(1, 1))
# make depth the last dimension
 cv <- aperm(visc$var, c(1, 3, 2))

# visualise as slices
 slice3D(colvar = cv, x = visc$x, y = visc$y, z = -visc$depth, 
   phi = 10, theta = 60, ylab = "time",
   xs = NULL, zs = NULL, ys = visc$y, NAcol = "transparent")

# restore plotting parameters
 par(mfrow = pm)