Movatterモバイル変換

gtable: Arrange 'Grobs' in Tables

Description

Tools to make it easier to work with "tables" of 'grobs'. The 'gtable' package defines a 'gtable' grob class that specifies a grid along with a list of grobs and their placement in the grid. Further the package makes it easy to manipulate and combine 'gtable' objects so that complex compositions can be built up sequentially.

Author(s)

Maintainer: Thomas Lin Pedersenthomas.pedersen@posit.co

Authors:

• Hadley Wickhamhadley@posit.co

Other contributors:

• Posit Software, PBC [copyright holder, funder]

See Also

Useful links:

• https://gtable.r-lib.org

• https://github.com/r-lib/gtable

• Report bugs athttps://github.com/r-lib/gtable/issues

Convert to a gtable

Description

Convert to a gtable

Usage

as.gtable(x, ...)## S3 method for class 'grob'as.gtable(x, widths = NULL, heights = NULL, ...)

Arguments

Value

A gtable object

Methods (by class)

• as.gtable(grob): Creates a 1-cell gtable containing the grob.

Row and column binding for gtables.

Description

These functions are the parallels of thematrix/data.frame row andcolumn bindings. As such they work in the same way, except they have to takecare of additional attributes within the gtables. Most importantly it needsto take care of the sizing of the final gtable, as the different gtablesgoing in may have different widths or heights. By default it tries tocalculate the maximum width/height among the supplied gtables, but otheroptions exists. Further, the relative layering of the grobs in each gtablecan be modified or left as-is.

Usage

## S3 method for class 'gtable'rbind(..., size = "max", z = NULL)## S3 method for class 'gtable'cbind(..., size = "max", z = NULL)

Arguments

Value

A gtable object

Examples

library(grid)a <- rectGrob(gp = gpar(fill = "red"))b <- circleGrob()c <- linesGrob()row <- matrix(list(a, b), nrow = 1)col <- matrix(list(a, b), ncol = 1)mat <- matrix(list(a, b, c, nullGrob()), nrow = 2)row_gt <- gtable_matrix("demo", row, unit(c(1, 1), "null"), unit(1, "null"))col_gt <- gtable_matrix("demo", col, unit(1, "null"), unit(c(1, 1), "null"))mat_gt <- gtable_matrix("demo", mat, unit(c(1, 1), "null"), unit(c(1, 1), "null"))# cbindc_binded <- cbind(mat_gt, col_gt, size = "first")plot(c_binded)# rbindr_binded <- rbind(mat_gt, row_gt, size = "last")plot(r_binded)# Dimensions must match along bind directiontry(cbind(mat_gt, row_gt))

Create a new grob table.

Description

A grob table captures all the information needed to layout grobs in a tablestructure. It supports row and column spanning, offers some tools toautomatically figure out the correct dimensions, and makes it easy toalign and combine multiple tables.

Usage

gtable(  widths = list(),  heights = list(),  respect = FALSE,  name = "layout",  rownames = NULL,  colnames = NULL,  vp = NULL)

Arguments

Details

Each grob is put in its own viewport - grobs in the same location arenot combined into one cell. Each grob takes up the entire cell viewportso justification control is not available.

It constructs both the viewports and the gTree needed to display the table.

Value

A gtable object

Components

There are three basics components to a grob table: the specification oftable (cell heights and widths), the layout (for each grob, its position,name and other settings), and global parameters.

It's easier to understand howgtable works if in your head you keepthe table separate from it's contents. Each cell can have 0, 1, or manygrobs inside. Each grob must belong to at least one cell, but can spanacross many cells.

Layout

The layout details are stored in a data frame with one row for each grob,and columns:

• t top extent of grob

• r right extent of grob

• b bottom extent of

• l left extent of grob

• z the z-order of the grob - used to reorder the grobsbefore they are rendered

• clip a string, specifying how the grob should be clipped:either"on","off" or"inherit"

• name, a character vector used to name each grob and itsviewport

You should not need to modify this data frame directly - instead usefunctions likegtable_add_grob.

See Also

Other gtable construction:gtable_col(),gtable_matrix(),gtable_row(),gtable_spacer

Examples

library(grid)a <- gtable(unit(1:3, c("cm")), unit(5, "cm"))agtable_show_layout(a)# Add a grob:rect <- rectGrob(gp = gpar(fill = "black"))a <- gtable_add_grob(a, rect, 1, 1)aplot(a)# gtables behave like matrices:dim(a)t(a)plot(t(a))# when subsetting, grobs are retained if their extents lie in the# rows/columns that retained.b <- gtable(unit(c(2, 2, 2), "cm"), unit(c(2, 2, 2), "cm"))b <- gtable_add_grob(b, rect, 2, 2)b[1, ]b[, 1]b[2, 2]# gtable have row and column namesrownames(b) <- 1:3rownames(b)[2] <- 200colnames(b) <- letters[1:3]dimnames(b)

Add new columns in specified position.

Description

Insert new columns in a gtable and adjust the grob placement accordingly. Ifcolumns are added in the middle of a grob spanning multiple columns, the grobwill continue to span them all. If a column is added to the left or right ofa grob, the grob will not span the new column(s).

Usage

gtable_add_cols(x, widths, pos = -1)

Arguments

Value

A gtable with the new columns added.

See Also

Other gtable manipulation:gtable_add_grob(),gtable_add_padding(),gtable_add_rows(),gtable_add_space,gtable_filter()

Examples

library(grid)rect <- rectGrob(gp = gpar(fill = "#00000080"))tab <- gtable(unit(rep(1, 3), "null"), unit(rep(1, 3), "null"))tab <- gtable_add_grob(tab, rect, t = 1, l = 1, r = 3)tab <- gtable_add_grob(tab, rect, t = 1, b = 3, l = 1)tab <- gtable_add_grob(tab, rect, t = 1, b = 3, l = 3)dim(tab)plot(tab)# Grobs will continue to span over new rows if added in the middletab2 <- gtable_add_cols(tab, unit(1, "null"), 1)dim(tab2)plot(tab2)# But not when added to left (0) or right (-1, the default)tab3 <- gtable_add_cols(tab, unit(1, "null"))tab3 <- gtable_add_cols(tab3, unit(1, "null"), 0)dim(tab3)plot(tab3)

Add a single grob, possibly spanning multiple rows or columns.

Description

This only adds grobs into the table - it doesn't affect the table layout inany way. In the gtable model, grobs always fill up the complete tablecell. If you want custom justification you might need to define the grobdimension in absolute units, or put it into another gtable that can then beadded to the gtable instead of the grob.

Usage

gtable_add_grob(  x,  grobs,  t,  l,  b = t,  r = l,  z = Inf,  clip = "on",  name = x$name)

Arguments

Value

A gtable object with the new grob(s) added

See Also

Other gtable manipulation:gtable_add_cols(),gtable_add_padding(),gtable_add_rows(),gtable_add_space,gtable_filter()

Examples

library(grid)gt <- gtable(widths = unit(c(1, 1), 'null'), heights = unit(c(1, 1), 'null'))pts <- pointsGrob(x = runif(5), y = runif(5))# Add a grob to a single cell (top-right cell)gt <- gtable_add_grob(gt, pts, t = 1, l = 2)# Add a grob spanning multiple cellsgt <- gtable_add_grob(gt, pts, t = 1, l = 1, b = 2)plot(gt)

Add padding around edges of table.

Description

This is a convenience function for adding an extra row and an extra column ateach edge of the table.

Usage

gtable_add_padding(x, padding)

Arguments

Value

A gtable object

See Also

Other gtable manipulation:gtable_add_cols(),gtable_add_grob(),gtable_add_rows(),gtable_add_space,gtable_filter()

Examples

library(grid)gt <- gtable(unit(1, "null"), unit(1, "null"))gt <- gtable_add_grob(gt, rectGrob(gp = gpar(fill = "black")), 1, 1)plot(gt)plot(cbind(gt, gt))plot(rbind(gt, gt))pad <- gtable_add_padding(gt, unit(1, "cm"))plot(pad)plot(cbind(pad, pad))plot(rbind(pad, pad))

Add new rows in specified position.

Description

Insert new rows in a gtable and adjust the grob placement accordingly. Ifrows are added in the middle of a grob spanning multiple rows, the grob willcontinue to span them all. If a row is added above or below a grob, the grobwill not span the new row(s).

Usage

gtable_add_rows(x, heights, pos = -1)

Arguments

Value

A gtable with the new rows added.

See Also

Other gtable manipulation:gtable_add_cols(),gtable_add_grob(),gtable_add_padding(),gtable_add_space,gtable_filter()

Examples

library(grid)rect <- rectGrob(gp = gpar(fill = "#00000080"))tab <- gtable(unit(rep(1, 3), "null"), unit(rep(1, 3), "null"))tab <- gtable_add_grob(tab, rect, t = 1, l = 1, r = 3)tab <- gtable_add_grob(tab, rect, t = 1, b = 3, l = 1)tab <- gtable_add_grob(tab, rect, t = 1, b = 3, l = 3)dim(tab)plot(tab)# Grobs will continue to span over new rows if added in the middletab2 <- gtable_add_rows(tab, unit(1, "null"), 1)dim(tab2)plot(tab2)# But not when added to top (0) or bottom (-1, the default)tab3 <- gtable_add_rows(tab, unit(1, "null"))tab3 <- gtable_add_rows(tab3, unit(1, "null"), 0)dim(tab3)plot(tab3)

Add row/column spacing.

Description

Addswidth space between the columns orheight space betweenthe rows, effictvely pushing the existing cells apart.

Usage

gtable_add_col_space(x, width)gtable_add_row_space(x, height)

Arguments

Value

A gtable with the additional rows or columns added

See Also

Other gtable manipulation:gtable_add_cols(),gtable_add_grob(),gtable_add_padding(),gtable_add_rows(),gtable_filter()

Examples

library(grid)rect <- rectGrob()rect_mat <- matrix(rep(list(rect), 9), nrow = 3)gt <- gtable_matrix("rects", rect_mat, widths = unit(rep(1, 3), "null"),                    heights = unit(rep(1, 3), "null"))plot(gt)# Add spacing between the grobs# same height between all rowsgt <- gtable_add_row_space(gt, unit(0.5, "cm"))# Different width between the columnsgt <- gtable_add_col_space(gt, unit(c(0.5, 1), "cm"))plot(gt)

Create a single column gtable

Description

This function stacks a list of grobs into a single column gtable of the givenwidth and heights.

Usage

gtable_col(  name,  grobs,  width = NULL,  heights = NULL,  z = NULL,  vp = NULL,  clip = "inherit")

Arguments

Value

A gtable with one column and as many rows as elements in the grobslist.

See Also

Other gtable construction:gtable(),gtable_matrix(),gtable_row(),gtable_spacer

Examples

library(grid)a <- rectGrob(gp = gpar(fill = "red"))b <- circleGrob()c <- linesGrob()gt <- gtable_col("demo", list(a, b, c))gtplot(gt)gtable_show_layout(gt)

Filter cells by name

Description

Normally a gtable is considered a matrix when indexing so that indexing isworking on the cell layout and not on the grobs it contains.gtable_filterallows you to subset the grobs by name and optionally remove rows or columnsif left empty after the subsetting

Usage

gtable_filter(x, pattern, fixed = FALSE, trim = TRUE, invert = FALSE)

Arguments

Value

A gtable only containing the matching grobs, potentially stripped ofempty columns and rows

See Also

Other gtable manipulation:gtable_add_cols(),gtable_add_grob(),gtable_add_padding(),gtable_add_rows(),gtable_add_space

Examples

library(grid)gt <- gtable(unit(rep(5, 3), c("cm")), unit(5, "cm"))rect <- rectGrob(gp = gpar(fill = "black"))circ <- circleGrob(gp = gpar(fill = "red"))gt <- gtable_add_grob(gt, rect, 1, 1, name = "rect")gt <- gtable_add_grob(gt, circ, 1, 3, name = "circ")plot(gtable_filter(gt, "rect"))plot(gtable_filter(gt, "rect", trim = FALSE))plot(gtable_filter(gt, "circ"))plot(gtable_filter(gt, "circ", trim = FALSE))

Returns the height of a gtable, in the gtable's units

Description

Note that unlike heightDetails.gtable, this can return relative units.

Usage

gtable_height(x)

Arguments

Create a gtable from a matrix of grobs.

Description

This function takes a matrix of grobs and create a gtable matching with thegrobs in the same position as they were in the matrix, with the given heightsand widths.

Usage

gtable_matrix(  name,  grobs,  widths = NULL,  heights = NULL,  z = NULL,  respect = FALSE,  clip = "on",  vp = NULL)

Arguments

Value

A gtable of the same dimensions as the grobs matrix.

See Also

Other gtable construction:gtable(),gtable_col(),gtable_row(),gtable_spacer

Examples

library(grid)a <- rectGrob(gp = gpar(fill = "red"))b <- circleGrob()c <- linesGrob()row <- matrix(list(a, b, c), nrow = 1)col <- matrix(list(a, b, c), ncol = 1)mat <- matrix(list(a, b, c, nullGrob()), nrow = 2)gtable_matrix("demo", row, unit(c(1, 1, 1), "null"), unit(1, "null"))gtable_matrix("demo", col, unit(1, "null"), unit(c(1, 1, 1), "null"))gtable_matrix("demo", mat, unit(c(1, 1), "null"), unit(c(1, 1), "null"))# Can specify z orderingz <- matrix(c(3, 1, 2, 4), nrow = 2)gtable_matrix("demo", mat, unit(c(1, 1), "null"), unit(c(1, 1), "null"), z = z)

Create a single row gtable.

Description

This function puts grobs in a list side-by-side in a single-row gtable fromleft to right witrh the given widths and height.

Usage

gtable_row(  name,  grobs,  height = NULL,  widths = NULL,  z = NULL,  vp = NULL,  clip = "inherit")

Arguments

Value

A gtable with a single row and the same number of columns aselements in the grobs list

See Also

Other gtable construction:gtable(),gtable_col(),gtable_matrix(),gtable_spacer

Examples

library(grid)a <- rectGrob(gp = gpar(fill = "red"))b <- circleGrob()c <- linesGrob()gt <- gtable_row("demo", list(a, b, c))gtplot(gt)gtable_show_layout(gt)

Visualise the layout of a gtable.

Description

This function is a simple wrapper aroundgrid::grid.show.layout() thatallows you to inspect the layout of the gtable.

Usage

gtable_show_layout(x, ...)

Arguments

Examples

gt <- gtable(widths = grid::unit(c(1, 0.5, 2), c("null", "cm", "null")),             heights = grid::unit(c(0.2, 1, 3), c("inch", "null", "cm")))gtable_show_layout(gt)

Create a row/col spacer gtable.

Description

Create a zero-column or zero-row gtable with the given heights or widthsrespectively.

Usage

gtable_row_spacer(widths)gtable_col_spacer(heights)

Arguments

Value

A gtable object

See Also

Other gtable construction:gtable(),gtable_col(),gtable_matrix(),gtable_row()

Trim off empty cells.

Description

This function detects rows and columns that does not contain any grobs andremoves thewm from the gtable. If the rows and/or columns removed had anon-zero height/width the relative layout of the gtable may change.

Usage

gtable_trim(x)

Arguments

Value

A gtable object

Examples

library(grid)rect <- rectGrob(gp = gpar(fill = "black"))base <- gtable(unit(c(2, 2, 2), "cm"), unit(c(2, 2, 2), "cm"))center <- gtable_add_grob(base, rect, 2, 2)plot(center)plot(gtable_trim(center))col <- gtable_add_grob(base, rect, 1, 2, 3, 2)plot(col)plot(gtable_trim(col))row <- gtable_add_grob(base, rect, 2, 1, 2, 3)plot(row)plot(gtable_trim(row))

Returns the width of a gtable, in the gtable's units

Description

Note that unlike widthDetails.gtable, this can return relative units.

Usage

gtable_width(x)

Arguments

Is this a gtable?

Description

Is this a gtable?

Usage

is.gtable(x)

Arguments

Print a gtable object

Description

Print a gtable object

Usage

## S3 method for class 'gtable'print(x, zsort = FALSE, ...)

Arguments