Utilities to make capped volume boxes

makeCappedVolumeBox returns the dimensions of the biggest multidimensional box (a.k.a. hyperrectangle) that satisfies 3 constraints: (1) its volume is capped, (2) it fits in the constraining box, (3) it has the specified shape.

makeRegularArrayGridOfCappedLengthViewports makes a RegularArrayGrid object with grid elements that are capped volume boxes with the specified constraints.

These are low-level utilities used internally to support defaultAutoGrid and family.

Usage

makeCappedVolumeBox(maxvol, maxdim, shape=c("hypercube",
                                            "scale",
                                            "first-dim-grows-first",
                                            "last-dim-grows-first"))

makeRegularArrayGridOfCappedLengthViewports(refdim,
                           viewport_len,
                           viewport_shape=c("hypercube",
                                            "scale",
                                            "first-dim-grows-first",
                                            "last-dim-grows-first"))

Arguments

maxvol

The maximum volume of the box to return.

maxdim

The dimensions of the constraining box.

shape

The shape of the box to return.

refdim

The dimensions of the reference array of the grid to return.

viewport_len

The maximum length of the elements (a.k.a. viewports) of the grid to return.

viewport_shape

The shape of the elements (a.k.a. viewports) of the grid to return.

Details

makeCappedVolumeBox returns the dimensions of a box that satisfies the following constraints:

1. The volume of the box is as close as possibe to (but no bigger than) maxvol.

2. The box fits in the constraining box i.e. in the box whose dimensions are specified via maxdim.

3. The box has a non-zero volume if the constraining box has a non-zero volume.

4. The shape of the box is as close as possible to the requested shape.

The supported shapes are:

• hypercube: The box should be as close as possible to an hypercube (a.k.a. n-cube), that is, the ratio between its biggest and smallest dimensions should be as close as possible to 1.

• scale: The box should have the same proportions as the constraining box.

• first-dim-grows-first: The box will be grown along its 1st dimension first, then along its 2nd dimension, etc...

• last-dim-grows-first: Like first-dim-grows-first but starting along the last dimension.

See also

• defaultAutoGrid and family to create automatic grids to use for block processing of array-like objects.

• ArrayGrid in the S4Arrays package for the formal representation of grids and viewports.

Examples

## ---------------------------------------------------------------------
## makeCappedVolumeBox()
## ---------------------------------------------------------------------

maxdim <- c(50, 12)  # dimensions of the "constraining box"

## "hypercube" shape:
makeCappedVolumeBox(40, maxdim)
#> [1] 6 6
makeCappedVolumeBox(120, maxdim)
#> [1] 11 10
makeCappedVolumeBox(125, maxdim)
#> [1] 11 11
makeCappedVolumeBox(200, maxdim)
#> [1] 16 12

## "scale" shape:
makeCappedVolumeBox(40, maxdim, shape="scale")
#> [1] 12  3
makeCappedVolumeBox(160, maxdim, shape="scale")
#> [1] 25  6

## "first-dim-grows-first" and "last-dim-grows-first" shapes:
makeCappedVolumeBox(120, maxdim, shape="first-dim-grows-first")
#> [1] 50  2
makeCappedVolumeBox(149, maxdim, shape="first-dim-grows-first")
#> [1] 50  2
makeCappedVolumeBox(150, maxdim, shape="first-dim-grows-first")
#> [1] 50  3

makeCappedVolumeBox(40, maxdim, shape="last-dim-grows-first")
#> [1]  3 12
makeCappedVolumeBox(59, maxdim, shape="last-dim-grows-first")
#> [1]  4 12
makeCappedVolumeBox(60, maxdim, shape="last-dim-grows-first")
#> [1]  5 12

## ---------------------------------------------------------------------
## makeRegularArrayGridOfCappedLengthViewports()
## ---------------------------------------------------------------------

grid1a <- makeRegularArrayGridOfCappedLengthViewports(maxdim, 40)
grid1a
#> 9 x 2  RegularArrayGrid object on a 50 x 12 array:
#>       [,1]        [,2]        
#>  [1,]   [1-6,1-6]   [1-6,7-12]
#>  [2,]  [7-12,1-6]  [7-12,7-12]
#>  [3,] [13-18,1-6] [13-18,7-12]
#>  [4,] [19-24,1-6] [19-24,7-12]
#>  [5,] [25-30,1-6] [25-30,7-12]
#>  [6,] [31-36,1-6] [31-36,7-12]
#>  [7,] [37-42,1-6] [37-42,7-12]
#>  [8,] [43-48,1-6] [43-48,7-12]
#>  [9,] [49-50,1-6] [49-50,7-12]
as.list(grid1a)  # turn the grid into a list of ArrayViewport objects
#> [[1]]
#> 6 x 6 ArrayViewport object on a 50 x 12 array: [1-6,1-6]
#> 
#> [[2]]
#> 6 x 6 ArrayViewport object on a 50 x 12 array: [7-12,1-6]
#> 
#> [[3]]
#> 6 x 6 ArrayViewport object on a 50 x 12 array: [13-18,1-6]
#> 
#> [[4]]
#> 6 x 6 ArrayViewport object on a 50 x 12 array: [19-24,1-6]
#> 
#> [[5]]
#> 6 x 6 ArrayViewport object on a 50 x 12 array: [25-30,1-6]
#> 
#> [[6]]
#> 6 x 6 ArrayViewport object on a 50 x 12 array: [31-36,1-6]
#> 
#> [[7]]
#> 6 x 6 ArrayViewport object on a 50 x 12 array: [37-42,1-6]
#> 
#> [[8]]
#> 6 x 6 ArrayViewport object on a 50 x 12 array: [43-48,1-6]
#> 
#> [[9]]
#> 2 x 6 ArrayViewport object on a 50 x 12 array: [49-50,1-6]
#> 
#> [[10]]
#> 6 x 6 ArrayViewport object on a 50 x 12 array: [1-6,7-12]
#> 
#> [[11]]
#> 6 x 6 ArrayViewport object on a 50 x 12 array: [7-12,7-12]
#> 
#> [[12]]
#> 6 x 6 ArrayViewport object on a 50 x 12 array: [13-18,7-12]
#> 
#> [[13]]
#> 6 x 6 ArrayViewport object on a 50 x 12 array: [19-24,7-12]
#> 
#> [[14]]
#> 6 x 6 ArrayViewport object on a 50 x 12 array: [25-30,7-12]
#> 
#> [[15]]
#> 6 x 6 ArrayViewport object on a 50 x 12 array: [31-36,7-12]
#> 
#> [[16]]
#> 6 x 6 ArrayViewport object on a 50 x 12 array: [37-42,7-12]
#> 
#> [[17]]
#> 6 x 6 ArrayViewport object on a 50 x 12 array: [43-48,7-12]
#> 
#> [[18]]
#> 2 x 6 ArrayViewport object on a 50 x 12 array: [49-50,7-12]
#> 
table(lengths(grid1a))
#> 
#> 12 36 
#>  2 16 
stopifnot(maxlength(grid1a) <= 40)  # sanity check

grid1b <- makeRegularArrayGridOfCappedLengthViewports(maxdim, 40,
                                            "first-dim-grows-first")
grid1b
#> 2 x 12  RegularArrayGrid object on a 50 x 12 array:
#>      [,1]      [,2]      [,3]      [,4]      [,5]      [,6]      [,7]     
#> [1,]  [1-40,1]  [1-40,2]  [1-40,3]  [1-40,4]  [1-40,5]  [1-40,6]  [1-40,7]
#> [2,] [41-50,1] [41-50,2] [41-50,3] [41-50,4] [41-50,5] [41-50,6] [41-50,7]
#>      [,8]      [,9]      [,10]      [,11]      [,12]     
#> [1,]  [1-40,8]  [1-40,9]  [1-40,10]  [1-40,11]  [1-40,12]
#> [2,] [41-50,8] [41-50,9] [41-50,10] [41-50,11] [41-50,12]
as.list(grid1b)  # turn the grid into a list of ArrayViewport objects
#> [[1]]
#> 40 x 1 ArrayViewport object on a 50 x 12 array: [1-40,1]
#> 
#> [[2]]
#> 10 x 1 ArrayViewport object on a 50 x 12 array: [41-50,1]
#> 
#> [[3]]
#> 40 x 1 ArrayViewport object on a 50 x 12 array: [1-40,2]
#> 
#> [[4]]
#> 10 x 1 ArrayViewport object on a 50 x 12 array: [41-50,2]
#> 
#> [[5]]
#> 40 x 1 ArrayViewport object on a 50 x 12 array: [1-40,3]
#> 
#> [[6]]
#> 10 x 1 ArrayViewport object on a 50 x 12 array: [41-50,3]
#> 
#> [[7]]
#> 40 x 1 ArrayViewport object on a 50 x 12 array: [1-40,4]
#> 
#> [[8]]
#> 10 x 1 ArrayViewport object on a 50 x 12 array: [41-50,4]
#> 
#> [[9]]
#> 40 x 1 ArrayViewport object on a 50 x 12 array: [1-40,5]
#> 
#> [[10]]
#> 10 x 1 ArrayViewport object on a 50 x 12 array: [41-50,5]
#> 
#> [[11]]
#> 40 x 1 ArrayViewport object on a 50 x 12 array: [1-40,6]
#> 
#> [[12]]
#> 10 x 1 ArrayViewport object on a 50 x 12 array: [41-50,6]
#> 
#> [[13]]
#> 40 x 1 ArrayViewport object on a 50 x 12 array: [1-40,7]
#> 
#> [[14]]
#> 10 x 1 ArrayViewport object on a 50 x 12 array: [41-50,7]
#> 
#> [[15]]
#> 40 x 1 ArrayViewport object on a 50 x 12 array: [1-40,8]
#> 
#> [[16]]
#> 10 x 1 ArrayViewport object on a 50 x 12 array: [41-50,8]
#> 
#> [[17]]
#> 40 x 1 ArrayViewport object on a 50 x 12 array: [1-40,9]
#> 
#> [[18]]
#> 10 x 1 ArrayViewport object on a 50 x 12 array: [41-50,9]
#> 
#> [[19]]
#> 40 x 1 ArrayViewport object on a 50 x 12 array: [1-40,10]
#> 
#> [[20]]
#> 10 x 1 ArrayViewport object on a 50 x 12 array: [41-50,10]
#> 
#> [[21]]
#> 40 x 1 ArrayViewport object on a 50 x 12 array: [1-40,11]
#> 
#> [[22]]
#> 10 x 1 ArrayViewport object on a 50 x 12 array: [41-50,11]
#> 
#> [[23]]
#> 40 x 1 ArrayViewport object on a 50 x 12 array: [1-40,12]
#> 
#> [[24]]
#> 10 x 1 ArrayViewport object on a 50 x 12 array: [41-50,12]
#> 
table(lengths(grid1b))
#> 
#> 10 40 
#> 12 12 
stopifnot(maxlength(grid1b) <= 40)  # sanity check

grid2a <- makeRegularArrayGridOfCappedLengthViewports(maxdim, 120)
grid2a
#> 5 x 2  RegularArrayGrid object on a 50 x 12 array:
#>      [,1]         [,2]         
#> [1,]  [1-11,1-10]  [1-11,11-12]
#> [2,] [12-22,1-10] [12-22,11-12]
#> [3,] [23-33,1-10] [23-33,11-12]
#> [4,] [34-44,1-10] [34-44,11-12]
#> [5,] [45-50,1-10] [45-50,11-12]
as.list(grid2a)  # turn the grid into a list of ArrayViewport objects
#> [[1]]
#> 11 x 10 ArrayViewport object on a 50 x 12 array: [1-11,1-10]
#> 
#> [[2]]
#> 11 x 10 ArrayViewport object on a 50 x 12 array: [12-22,1-10]
#> 
#> [[3]]
#> 11 x 10 ArrayViewport object on a 50 x 12 array: [23-33,1-10]
#> 
#> [[4]]
#> 11 x 10 ArrayViewport object on a 50 x 12 array: [34-44,1-10]
#> 
#> [[5]]
#> 6 x 10 ArrayViewport object on a 50 x 12 array: [45-50,1-10]
#> 
#> [[6]]
#> 11 x 2 ArrayViewport object on a 50 x 12 array: [1-11,11-12]
#> 
#> [[7]]
#> 11 x 2 ArrayViewport object on a 50 x 12 array: [12-22,11-12]
#> 
#> [[8]]
#> 11 x 2 ArrayViewport object on a 50 x 12 array: [23-33,11-12]
#> 
#> [[9]]
#> 11 x 2 ArrayViewport object on a 50 x 12 array: [34-44,11-12]
#> 
#> [[10]]
#> 6 x 2 ArrayViewport object on a 50 x 12 array: [45-50,11-12]
#> 
table(lengths(grid2a))
#> 
#>  12  22  60 110 
#>   1   4   1   4 
stopifnot(maxlength(grid2a) <= 120)  # sanity check

grid2b <- makeRegularArrayGridOfCappedLengthViewports(maxdim, 120,
                                            "first-dim-grows-first")
grid2b
#> 1 x 6  RegularArrayGrid object on a 50 x 12 array:
#>      [,1]    [,2]    [,3]    [,4]    [,5]     [,6]     
#> [1,] [ ,1-2] [ ,3-4] [ ,5-6] [ ,7-8] [ ,9-10] [ ,11-12]
as.list(grid2b)  # turn the grid into a list of ArrayViewport objects
#> [[1]]
#> 50 x 2 ArrayViewport object on a 50 x 12 array: [ ,1-2]
#> 
#> [[2]]
#> 50 x 2 ArrayViewport object on a 50 x 12 array: [ ,3-4]
#> 
#> [[3]]
#> 50 x 2 ArrayViewport object on a 50 x 12 array: [ ,5-6]
#> 
#> [[4]]
#> 50 x 2 ArrayViewport object on a 50 x 12 array: [ ,7-8]
#> 
#> [[5]]
#> 50 x 2 ArrayViewport object on a 50 x 12 array: [ ,9-10]
#> 
#> [[6]]
#> 50 x 2 ArrayViewport object on a 50 x 12 array: [ ,11-12]
#> 
table(lengths(grid2b))
#> 
#> 100 
#>   6 
stopifnot(maxlength(grid2b) <= 120)  # sanity check

grid3a <- makeRegularArrayGridOfCappedLengthViewports(maxdim, 200)
grid3a
#> 4 x 1  RegularArrayGrid object on a 50 x 12 array:
#>      [,1]     
#> [1,]  [1-16, ]
#> [2,] [17-32, ]
#> [3,] [33-48, ]
#> [4,] [49-50, ]
as.list(grid3a)  # turn the grid into a list of ArrayViewport objects
#> [[1]]
#> 16 x 12 ArrayViewport object on a 50 x 12 array: [1-16, ]
#> 
#> [[2]]
#> 16 x 12 ArrayViewport object on a 50 x 12 array: [17-32, ]
#> 
#> [[3]]
#> 16 x 12 ArrayViewport object on a 50 x 12 array: [33-48, ]
#> 
#> [[4]]
#> 2 x 12 ArrayViewport object on a 50 x 12 array: [49-50, ]
#> 
table(lengths(grid3a))
#> 
#>  24 192 
#>   1   3 
stopifnot(maxlength(grid3a) <= 200)  # sanity check

grid3b <- makeRegularArrayGridOfCappedLengthViewports(maxdim, 200,
                                            "first-dim-grows-first")
grid3b
#> 1 x 3  RegularArrayGrid object on a 50 x 12 array:
#>      [,1]    [,2]    [,3]    
#> [1,] [ ,1-4] [ ,5-8] [ ,9-12]
as.list(grid3b)  # turn the grid into a list of ArrayViewport objects
#> [[1]]
#> 50 x 4 ArrayViewport object on a 50 x 12 array: [ ,1-4]
#> 
#> [[2]]
#> 50 x 4 ArrayViewport object on a 50 x 12 array: [ ,5-8]
#> 
#> [[3]]
#> 50 x 4 ArrayViewport object on a 50 x 12 array: [ ,9-12]
#> 
table(lengths(grid3b))
#> 
#> 200 
#>   3 
stopifnot(maxlength(grid3b) <= 200)  # sanity check