add_track {gtrellis} | R Documentation

## Add self-defined graphics track by track

### Description

Add self-defined graphics track by track

### Usage

    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:

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

Graphical parameters are usually passed by `gpar`:

        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.

        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 <z.gu@dkfz.de>

### See Also

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`

### Examples

    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))
        })
    }

[Package gtrellis version 1.12.1 Index]