add_track: Add self-defined graphics track by track
In eilslabs/gtrellis: Genome Level Trellis Layout

Description Usage Arguments Details Value Author(s) See Also Examples

Add self-defined graphics track by track

add_track(gr = NULL, category = NULL, track = current_track() + 1,
    clip = TRUE, panel_fun = function(gr) NULL, panel.fun = NULL,
    use_raster = FALSE,
    raster_device = c("png", "jpeg", "tiff", "CairoPNG", "CairoJPEG", "CairoTIFF"),
    raster_quality = 1,
    raster_device_param = list())

`gr`	genomic regions. It should be a data frame in BED format or a `GRanges` object.
`category`	subset of categories (e.g. chromosomes) that users want to add graphics. The value can be a vector which contains more than one category. By default it is all available categories.
`track`	which track the graphics will be added to. By default it is the next track. The value should only be a scalar.
`clip`	whether graphics are restricted inside the cell.
`panel_fun`	self-defined panel function to add graphics in each 'cell'. THe argument `gr` in `panel_fun` only contains data for the current category which is a subset of the main `gr`. The function can also contains no argument if nothing needs to be passed in.
`panel.fun`	deprecated
`use_raster`	whether render the each panel as a raster image. It helps to reduce file size when the file size is huge.
`raster_device`	graphic device which is used to generate the raster image
`raster_quality`	a value set to larger than 1 will improve the quality of the raster image. A temporary image with `raster_quality`*`raster_quality` times the original size of panel is generated first and then fit into the panel by `grid.raster`.
`raster_device_param`	a list of further parameters for the selected graphic device

Initialization of the Trellis layout and adding graphics are two independent steps. Once the layout initialization finished, each cell will be an independent plotting region. As same as panel_fun in circlize-package, the self-defined function panel_fun will be applied on every cell in the specified track (by default it is the 'current' track).

When adding graphics in each cell, get_cell_meta_data can return several meta data for the current cell.

Since this package is implemented by the grid graphic system, grid-family functions (such as grid.points, grid.rect, ...) should be used to add graphics. The usage of grid functions is quite similar as the traditional graphic functions. Followings are several examples:

1
2
3

    grid.points(x, y)
    grid.lines(x, y)
    grid.rect(x, y, width, height)

Graphical parameters are usually passed by gpar:

1 2	grid.points(x, y, gp = gpar(col = "red") grid.rect(x, y, width, height, gp = gpar(fill = "black", col = "red"))

grid system also support a large number of coordinate measurement systems by defining proper unit object which provides high flexibility to place graphics on the plotting regions.

1 2	grid.points(x, y, default.units = "npc") grid.rect(x, y, width = unit(1, "cm"))

You can refer to the documentations and vignettes of grid-package to get a overview.

No value is returned.

Zuguang Gu <z.gu@dkfz.de>

There are several functions which draw specific graphics and are implemented by add_track:

add_points_track
add_segments_track
add_lines_track
add_rect_track
add_heatmap_track

require(circlize)
bed = circlize::generateRandomBed()
gtrellis_layout(track_ylim = range(bed[[4]]))
add_track(bed, panel.fun = function(bed) {
    x = (bed[[2]] + bed[[3]]) / 2
    y = bed[[4]]
    grid.points(x, y, pch = 16, size = unit(0.5, "mm"))
})

# you can add graphics in any cell by specifying `category` and `track`
all_chr = paste0("chr", 1:22)
letter = strsplit("MERRY CHRISTMAS!", "")[[1]]
gtrellis_layout(nrow = 5)
for(i in seq_along(letter)) {
    add_track(category = all_chr[i], track = 1, panel.fun = function(gr) {
        grid.text(letter[i], gp = gpar(fontsize = 30))
    })
}