mapToGrid {DelayedArray} | R Documentation

## Map reference array positions to grid positions and vice-versa

### Description

Use `mapToGrid()` to map a set of reference array positions to grid positions. Use `mapToRef()` for the reverse mapping.

### Usage

    mapToGrid(Mindex, grid, linear=FALSE)

    mapToRef(major, minor, grid, linear=FALSE)

### Arguments

`Mindex` | An M-index containing absolute positions, that is, positions with respect to the underlying array (i.e. to the reference array of `grid`). For convenience, `Mindex` can also be specified as an integer vector with one element per dimension in the underlying array, in which case it will be treated like a 1-row matrix. Note that no bounds checking is performed, that is, values in the j-th column of `Mindex` can be < 1 or > `refdim(grid)[j]`. What those values will be mapped to is undefined.
`grid` | An ArrayGrid object.
`linear` | `TRUE` or `FALSE`. Controls the format of the output for `mapToGrid` and the input for `mapToRef`. By default (i.e. when `linear` is `FALSE`), the major and minor indices returned by `mapToGrid` (or taken by `mapToRef`) are both M-indices (a.k.a. matrix indices). When `linear` is set to `TRUE`, they are both returned (or taken) as L-indices (a.k.a. linear indices).
`major, minor` | The `major` and `minor` components as returned by `mapToGrid`.

### Value

- For `mapToGrid()`: A list with 2 components, `major` and `minor`.

  Each row in input matrix `Mindex` is an n-uplet that contains the coordinates of an absolute position.

  By default (i.e. when `linear` is `FALSE`), the 2 components of the returned list are integer matrices of the same dimensions as the input matrix. A row in the `major` (or `minor`) matrix is called a "major n-uplet" (or "minor n-uplet"). So for each "input position" (i.e. for each row in the input matrix), 2 n-uplets are returned: the "major n-uplet" and the "minor n-uplet". The "major n-uplet" contains the coordinates of the "input position" in the grid coordinate system, that is, the coordinates of the grid element where the position falls in. The "minor n-uplet" represents where exactly the "input position" falls inside the grid element reported by the "major n-uplet". The coordinates in the "minor n-uplet" are relative to this grid element.

  When `linear` is `TRUE`, the `major` and `minor` components are returned as linear indices. In this case, both are integer vectors containing 1 linear index per "input position".

- For `mapToRef()`: A numeric matrix like one returned by `base::arrayInd` describing positions relative to the reference array of `grid`.

### See Also

- ArrayGrid for the formal representation of grids and viewports.

- `Lindex2Mindex` and `Mindex2Lindex` in this package (DelayedArray) for converting back and forth between linear indices and matrix indices.

- array objects in base R.

### Examples

    ## Create an arbitrary-spaced grid on top of a 15 x 9 matrix:
    grid2 <- ArbitraryArrayGrid(list(c(2L, 7:10, 13L, 15L), c(5:6, 6L, 9L)))

    ## Create a set of reference array positions:
    Mindex <- rbind(c( 2, 5),  # bottom right corner of 1st grid element
                    c( 3, 1),  # top left corner of 2nd grid element
                    c(14, 9),  # top right corner of last grid element
                    c(15, 7),  # bottom left corner of last grid element
                    c(15, 9))  # bottom right corner of last grid element

    ## Map them to grid positions:
    majmin <- mapToGrid(Mindex, grid2)
    majmin

    ## Reverse mapping:
    Mindex2 <- mapToRef(majmin$major, majmin$minor, grid2)
    stopifnot(all.equal(Mindex2, Mindex))

    majmin <- mapToGrid(Mindex, grid2, linear=TRUE)
    majmin
    Mindex2 <- mapToRef(majmin$major, majmin$minor, grid2, linear=TRUE)
    stopifnot(all.equal(Mindex2, Mindex))

    ## Map all the valid positions:
    all_positions <- seq_len(prod(refdim(grid2)))
    Mindex <- arrayInd(all_positions, refdim(grid2))
    majmin <- data.frame(mapToGrid(Mindex, grid2, linear=TRUE))
    majmin

    ## Sanity checks:
    min_by_maj <- split(majmin$minor,
                        factor(majmin$major, levels=seq_along(grid2)))
    stopifnot(identical(lengths(min_by_maj, use.names=FALSE), lengths(grid2)))
    stopifnot(all(mapply(isSequence, min_by_maj, lengths(min_by_maj))))
    Mindex2 <- mapToRef(majmin$major, majmin$minor, grid2, linear=TRUE)
    stopifnot(identical(Mindex2, Mindex))

    ## More mapping:
    grid4 <- RegularArrayGrid(c(50, 20), spacings=c(15L, 9L))
    Mindex <- rbind(c( 1,  1),
                    c( 2,  1),
                    c( 3,  1),
                    c(16,  1),
                    c(16,  2),
                    c(16, 10),
                    c(27, 18))

    mapToGrid(Mindex, grid4)
    mapToGrid(Mindex, grid4, linear=TRUE)

[Package DelayedArray version 0.20.0 Index]