Map reference array positions to grid positions and vice-versa

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-tuple 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-tuple" (or "minor n-tuple"). So for each "input position" (i.e. for each row in the input matrix), 2 n-tuples are returned: the "major n-tuple" and the "minor n-tuple". The "major n-tuple" 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-tuple" represents where exactly the "input position" falls inside the grid element reported by the "major n-tuple". The coordinates in the "minor n-tuple" 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 for converting back and forth between linear indices and matrix indices.

• array and matrix 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
#> $major
#>      [,1] [,2]
#> [1,]    1    1
#> [2,]    2    1
#> [3,]    7    4
#> [4,]    7    4
#> [5,]    7    4
#> 
#> $minor
#>      [,1] [,2]
#> [1,]    2    5
#> [2,]    1    1
#> [3,]    1    3
#> [4,]    2    1
#> [5,]    2    3
#> 

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

majmin <- mapToGrid(Mindex, grid2, linear=TRUE)
majmin
#> $major
#> [1]  1  2 28 28 28
#> 
#> $minor
#> [1] 10  1  5  2  6
#> 
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
#>     major minor
#> 1       1     1
#> 2       1     2
#> 3       2     1
#> 4       2     2
#> 5       2     3
#> 6       2     4
#> 7       2     5
#> 8       3     1
#> 9       4     1
#> 10      5     1
#> 11      6     1
#> 12      6     2
#> 13      6     3
#> 14      7     1
#> 15      7     2
#> 16      1     3
#> 17      1     4
#> 18      2     6
#> 19      2     7
#> 20      2     8
#> 21      2     9
#> 22      2    10
#> 23      3     2
#> 24      4     2
#> 25      5     2
#> 26      6     4
#> 27      6     5
#> 28      6     6
#> 29      7     3
#> 30      7     4
#> 31      1     5
#> 32      1     6
#> 33      2    11
#> 34      2    12
#> 35      2    13
#> 36      2    14
#> 37      2    15
#> 38      3     3
#> 39      4     3
#> 40      5     3
#> 41      6     7
#> 42      6     8
#> 43      6     9
#> 44      7     5
#> 45      7     6
#> 46      1     7
#> 47      1     8
#> 48      2    16
#> 49      2    17
#> 50      2    18
#> 51      2    19
#> 52      2    20
#> 53      3     4
#> 54      4     4
#> 55      5     4
#> 56      6    10
#> 57      6    11
#> 58      6    12
#> 59      7     7
#> 60      7     8
#> 61      1     9
#> 62      1    10
#> 63      2    21
#> 64      2    22
#> 65      2    23
#> 66      2    24
#> 67      2    25
#> 68      3     5
#> 69      4     5
#> 70      5     5
#> 71      6    13
#> 72      6    14
#> 73      6    15
#> 74      7     9
#> 75      7    10
#> 76      8     1
#> 77      8     2
#> 78      9     1
#> 79      9     2
#> 80      9     3
#> 81      9     4
#> 82      9     5
#> 83     10     1
#> 84     11     1
#> 85     12     1
#> 86     13     1
#> 87     13     2
#> 88     13     3
#> 89     14     1
#> 90     14     2
#> 91     22     1
#> 92     22     2
#> 93     23     1
#> 94     23     2
#> 95     23     3
#> 96     23     4
#> 97     23     5
#> 98     24     1
#> 99     25     1
#> 100    26     1
#> 101    27     1
#> 102    27     2
#> 103    27     3
#> 104    28     1
#> 105    28     2
#> 106    22     3
#> 107    22     4
#> 108    23     6
#> 109    23     7
#> 110    23     8
#> 111    23     9
#> 112    23    10
#> 113    24     2
#> 114    25     2
#> 115    26     2
#> 116    27     4
#> 117    27     5
#> 118    27     6
#> 119    28     3
#> 120    28     4
#> 121    22     5
#> 122    22     6
#> 123    23    11
#> 124    23    12
#> 125    23    13
#> 126    23    14
#> 127    23    15
#> 128    24     3
#> 129    25     3
#> 130    26     3
#> 131    27     7
#> 132    27     8
#> 133    27     9
#> 134    28     5
#> 135    28     6

## 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)
#> $major
#>      [,1] [,2]
#> [1,]    1    1
#> [2,]    1    1
#> [3,]    1    1
#> [4,]    2    1
#> [5,]    2    1
#> [6,]    2    2
#> [7,]    2    2
#> 
#> $minor
#>      [,1] [,2]
#> [1,]    1    1
#> [2,]    2    1
#> [3,]    3    1
#> [4,]    1    1
#> [5,]    1    2
#> [6,]    1    1
#> [7,]   12    9
#> 
mapToGrid(Mindex, grid4, linear=TRUE)
#> $major
#> [1] 1 1 1 2 2 6 6
#> 
#> $minor
#> [1]   1   2   3   1  16   1 132
#>