ursa (version 3.9.4)

compose_design: Organize multi-panel layout with images and color bars.

Description

compose_design prepares scheme for layout of images and color bars.

Usage

compose_design(…)

Arguments

…

Set of arguments, which are recognized via their names and classes:

obj

Object of class ursaRaster or list of objects of class ursaRaster or NULL. Default is NULL. Used to detect panel layout and coordinate reference system.

layout

Integer of length 2 or NA. Layout matrix has dimensionsc(nr, nc), where nr is number of rows, and nc is number of columns. If layout=NA then layout matrix is recognized internally using number of bands of obj and argument ratio. If layout=NA and obj=NULL then matrix c(1,1) is used.

byrow

Logical. The order of filling of layout matrix. Default is TRUE. If byrow=TRUE then matrix is filled by rows (from top row, consequently from left element to right element, then next row). If byrow=FALSE then matrix is filled by columns.

skip

Positive integer of variable length. Default in NULL (length is zero). Indices of panels in the layout matrix, which are not used.

legend

The descripition of rules how color bars (legends) or panel captions are located in the layout. It is the list of embedded lists of two elements, which describe the color bars position in the layout. of Default is NA, it means using of internal rules. If legend=NULL then no plotting of color bars. If legend is positive integer in the range 1L:4L, then sinlge color bar is used and legend's side is corresponded to margins of R graphic system.

side

Positive integer 1L, 2L, 3L, or 4L. Default is NA. Simplification of color bar position in the case that single color bar is used. The value is corresponded to margins of R graphic system. The synonym of integer value of legend.

ratio

Positive numeric. The desired ratio of layout sides (width per height). If layout=NA then the dimensions of layout matrix are defined internally to get the given ratio of layout's width per height. The default is (16+1)/(9+1) in the assumtion of optimal filling on the usual 16:9 screens.

Value

It is a list of class ursaLayout.

layout

Integer matrix with dimension c(2*nr+3, 2*nc+3), where nr and nc are number of rows and colunms of the layout matrix. The layout matrix of image panels is surrounded by colorbar panels. The original layout matrix is expanded by adding zero columns and rows. In the new matrix each even column has zero values, and each even row has zero values.

image

Nonnegative integer. Number of panels with images.

legend

Nonnegative integer. Number of panels with color bars (legends).

The returned value is passed to function compose_open and further is kept in the options until calling of compose_close.

Details

Function compose_design extracts and validates required arguments from a list of parameters (three-dots construct) and passes them to internal function .compose_design.

Argument legend is a list or coerced to a list. The length of this list is equal to number of color bars; each item describes certain color bar. This desctiption is a list again with two elements, which desribes the position of color bar in relation to main panels of images.

If argument legend is in interval 1L:4L then it is interpreted as argument side in functions axis, mtext. Argument side in function compose_design plays the same role. It is introduced for consistency with R graphic system.

In the one of example below (See Examples section) the layout with dimension of two rows by three columns is considered (layout=c(2,3)). The dimension of resulting layout matrix is c(7,9), where 7=2*2+3, and 9=3*2+3.

     [,1] [,2] [,3] [,4] [,5] [,6] [,7] [,8] [,9]
[1,]    0    0    0    0    0    0    0    0    0
[2,]    0    0    0    0    0    0    0    0    0
[3,]    0    0    1    0    2    0    3    0    0
[4,]    0    0    0    0    0    0    0    0    0
[5,]    0    0    4    0    5    0    6    0    0
[6,]    0    0    0    0    0    0    0    0    0
[7,]    0    0    0    0    0    0    0    0    0

The complicated color bar structure is specified via R's list function:

>   leg <- list("7"=list(row=1,col=0),"8"=list(2,"left")
+              ,"9"=list("full","right"),"10"=list("top","full")
+              ,"11"=list(99,1:2),"12"=list("bottom",3))
> str(leg)
 $ 7 :List of 2
  ..$ row: num 1
  ..$ col: num 0
 $ 8 :List of 2
  ..$ : num 2
  ..$ : chr "left"
 $ 9 :List of 2
  ..$ : chr "full"
  ..$ : chr "right"
 $ 10:List of 2
  ..$ : chr "top"
  ..$ : chr "full"
 $ 11:List of 2
  ..$ : num 99
  ..$ : int [1:2] 1 2
 $ 12:List of 2
  ..$ : chr "bottom"
  ..$ : num 3

Here, six color bars are specified. It is a list of six lists (sub-lists). First item of sub-list is row number, and the second one is column number. Integers can be replaces by character keywords.

For row-position, "top" means 0L (less than first row), "bottom" means large integer value (greater than last row, currently, 99L), "first" means 1L, "last" means number of last row (2L in this example), "full" means whole range from first to last rows (1L:2L in this example). Values "top" and "bottom" are used for horizontal color bars (last three sub-lists), and the rest for vertical color bars (first three sub-lists).

For column-position, "left" means 0L (less then first column), "bottom" means large integer value (greater than last column, currently, 99L), "first" means first column (1L), "last" means last column (3L in this example), "full" means whole range from first to last columns ((1L:3L in this example)). Values "left" and "right" are used for vertical color bars, and the rest are for horizontal ones.

The resulting layout is a sparse matrix with zero values for each even row and each column. These zeros plays role of white space between panels in the plotted layout. In our example, values 1L:6L are corresponded to six map panels, and values 7L:12L are corresponded to six narrow panels of color bars (legends).

     [,1] [,2] [,3] [,4] [,5] [,6] [,7] [,8] [,9]
[1,]    0    0   10    0   10    0   10    0    0
[2,]    0    0    0    0    0    0    0    0    0
[3,]    7    0    1    0    2    0    3    0    9
[4,]    0    0    0    0    0    0    0    0    0
[5,]    8    0    4    0    5    0    6    0    9
[6,]    0    0    0    0    0    0    0    0    0
[7,]    0    0   11    0   11    0   12    0    0

Examples

# NOT RUN {
session_grid(NULL)
a <- ursa_dummy(nband=5,min=1,max=200,mul=1/8)
b <- list(colorize(a[1:3],pal.rich=240,pal.rotate=0)
         ,colorize(sqrt(a[4:5]),pal.rich=-15,pal.rotate=0,stretch="equal"))

cl1 <- compose_design(layout=c(2,3),byrow=TRUE,legend=NULL)
print(cl1)
compose_open(cl1)
compose_close()

cl2 <- compose_design(layout=c(2,3),byrow=FALSE,legend="left")
print(cl2$layout)
compose_open(cl2)
compose_close()

cl3 <- compose_design(a,side=2)
print(cl3)
compose_open(cl3)
compose_close()

cl4 <- compose_design(b)
print(cl4)
# }
# NOT RUN {
 ## to avoid over-time during example check -- begin
   compose_open(cl4)
   compose_plot(b,decor=FALSE,las=2)
   compose_close("nocrop")
# }
# NOT RUN {
 ## to avoid over-time during example check -- end

cl5 <- compose_design(b,byrow=FALSE,skip=3
                     ,legend=list(list("full","left"),list(1:2,"right")))
compose_open(cl5)
compose_plot(b,decor=FALSE)
compose_close("nocrop")

leg <- list(list(1,0),list(2,"left")
           ,list("full","right"),list("top","full")
           ,list(99,1:2),list("bottom",3))
str(leg)
cl6 <- compose_design(layout=c(2,3),skip=NA,legend=leg)
print(cl6)
compose_open(cl6,scale=3,pointsize=16)
compose_close("nocrop")
# }