circos.genomicTrackPlotRegion: Create a track for genomic graphics
In circlize: Circular Visualization

circos.genomicTrackPlotRegion

R Documentation

Create a track for genomic graphics

Description

Create a track for genomic graphics

Usage

circos.genomicTrackPlotRegion(
    data = NULL,
    ylim = NULL,
    stack = FALSE,
    numeric.column = NULL,
    jitter = 0,
    panel.fun = function(region, value, ...) {NULL},
    ...)

Arguments

`data`	A bed-file-like data frame or a list of data frames
`ylim`	If it is `NULL`, the value will be calculated from data. If `stack` is set to `TRUE`, this value is ignored.
`stack`	whether to plot in a "stack" mode.
`numeric.column`	Columns of numeric values in `data` that will be used for plotting. If `data` is a data frame list, `numeric.column` should be either length of one or length of `data`. If value of `numeric.column` is not set, its value will depend on the structure of `data`. If `data` is a data frame, the default value for `numeric.column` is all the numeric column starting from the fourth column. If `data` is a list of data frame, the default value for `numeric.column` is a vector which have the same length as `data` and the value in default `numeric.column` is the index of the first numeric column in corresponding data frame.
`jitter`	Numeric. Only works for adding points in `circos.genomicTrackPlotRegion` under `stack` mode
`panel.fun`	Self-defined function which will be applied on each sector. Please not it is different from that in `circos.trackPlotRegion`. In this function, there are two arguments (`region` and `value`) plus `...`. In them, `region` is a two-column data frame with start positions and end positions in current genomic category (e.g. chromosome). `value` is a data frame which is derived from `data` but excluding the first three columns. Rows in `value` correspond to rows in `region`. `...` is mandatory and is used to pass internal parameters to other functions. The definition of `value` will be different according to different input data (data frame or list of data frame) and different settings (stacked or not), please refer to 'details' section and vignettes to detailed explanation.
`...`	Pass to `circos.trackPlotRegion`.

Details

Similar as circos.trackPlotRegion, users can add customized graphics by panel.fun, but the behaviour of panel.fun will change depending on users' input data and stack setting.

When data is a single data frame, region in panel.fun is a data frame containing the second and third column in data in 'current' genomic category (e.g. current chromosome). value is also a data frame containing columns in data excluding the first three columns.

When data is a list containing data frames, panel.fun will be applied iteratively on each data frame, thus, region is extracted from the data frame which is in the current iteration. For example, if data contains two data frames, panel.fun will be applied with the first data frame in current chromosome and then applied with the second data frame in the same chromosome.

If stack is set to TRUE, ylim will be re-defined. in stack mode, the y-axis will be splitted into several part with equal height and graphics will be drawn on each 'horizontal' lines (y = 1, 2, ...). In this case:

When data is a single data frame containing one or more numeric columns, each numeric column defined in numeric.column will be treated as a single unit. ylim is re-defined to c(0.5, n+0.5) in which n is number of numeric columns. panel.fun will be applied iteratively on each numeric column. In each iteration, in panel.fun, region is still the genomic regions in current genomic category, but value contains current numeric column plus all non-numeric columns. Under stack mode, in panel.fun, all low-level genomic graphical functions will draw on the 'horizontal line' y = i in which i is the index of current numeric column and the value of i can be obtained by getI.

When data is a list containing data frames, each data frame will be treated as a single unit. The situation is quite similar as described in previous paragraph. ylim is re-defined to c(0.5, n+0.5) in which n is number of data frames. panel.fun will be applied iteratively on each data frame. In each iteration, in panel.fun, region is still the genomic regions in current genomic category, and value contains columns in current data frame excluding the first three columns. Under stack mode, in panel.fun, all low-level genomic graphical functions will draw on the 'horizontal line' y = i in which i is the index of current data frame.

Being different from panel.fun in circos.trackPlotRegion, there should be an additional argument ... in panel.fun. This additional argument is used to pass hidden values to low-level graphical functions. So if you are using functions like circos.genomicPoints, you should also add ... as an additional argument into circos.genomicPoints.