add_track: Add self-defined graphics track by track

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

View source: R/track.R

Description

Add self-defined graphics track by track

Usage

1
2
3
4
5
6
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())

Arguments

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

Details

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

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.

Value

No value is returned.

Author(s)

Zuguang Gu <[email protected]>

See Also

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

Examples

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
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))
    })
}

gtrellis documentation built on Nov. 17, 2017, 1:09 p.m.

Related to add_track in gtrellis...