# Functions for remapping, changing the resolution, and extracting from 2-D or 3-D data. 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 `NA`s where the depth-coordinates extend beyond the sigma values. ```r remap (var, ...) ## S3 method for class 'matrix' remap(var, x, y, xto = NULL, yto = NULL, na.rm = TRUE, ...) ## S3 method for class 'array' remap(var, x, y, z, xto = NULL, yto = NULL, zto = NULL, na.rm = TRUE, ...) changeres (var, ...) ## S3 method for class 'matrix' changeres(var, x, y, resfac, na.rm = TRUE, ...) ## S3 method for class 'array' changeres(var, x, y, z, resfac, na.rm = TRUE, ...) extract (var, ...) ## S3 method for class 'matrix' extract(var, x, y, xyto, ...) ## S3 method for class 'array' extract(var, x, y, z, xyzto, ...) transect(var, x, y, z, to, margin = "xy", ...) mapsigma (var, ...) ## S3 method for class 'matrix' mapsigma(var = NULL, sigma, signr = 2, x = NULL, depth = NULL, numdepth = NULL, xto = NULL, resfac = 1, ...) ## S3 method for class '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, ...) ``` ## 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 `NA`s 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. ## Returns `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. ## See Also Sylt3D for other examples of mapping. ## Examples ```r # 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: ## Not run: plotrgl() ## End(Not run) # 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) ```

mapping function