R: Functions for remapping, changing the resolution, and...

Map and extract data {OceanView} | R Documentation

## 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 `NA`s where the depth-coordinates extend beyond the sigma values.

### Usage

    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.

### 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.

### See Also

Sylt3D for other examples of mapping.

### Examples

    # 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)

[Package OceanView version 1.0.6 Index]