plot_events {linbin}

Plot Events as Bar Plots

Description

Plots an event table as a grid of bar plots.

Usage

plot_events(
  e,
  group.col = NULL,
  groups = NULL,
  data.cols = NULL,
  dim = NULL,
  byrow = TRUE,
  main = NULL,
  xlabs = character(),
  ylabs = character(),
  xlim = NULL,
  ylim = NULL,
  xticks = NULL,
  yticks = NULL,
  xtick.labels = NULL,
  ytick.labels = NULL,
  plot.grid = FALSE,
  sigfigs = c(3, 3),
  col = NULL,
  border = par("fg"),
  lty = par("lty"),
  lwd = par("lwd"),
  xpd = FALSE,
  mar = c(2.1, 2.75, 1.5, 0.5),
  oma = c(2, 2, 2, 2),
  ...
)

Arguments

e

An event table.

group.col

Name or index of column defining the event grouping for plotting. If NULL, the events are treated as one group. Group NA is not plotted.

groups

Vector of values from group.col specifying which groups to plot. If NULL, all groups are plotted by order of first appearance in group.col.

data.cols

Names or indices of columns to plot, given as a list of character or numeric vectors. If multiple columns are specified, their bars are stacked together in one plot. Names are interpreted as regular expressions (regex) matching full column names. If NULL, all columns not named from, to, or group.col are each plotted individually in order of appearance.

dim

The row and column dimensions of the grid. If NULL, the grid is column groups (rows) by event groups (columns) if byrow = TRUE, and event groups (rows) by column groups (columns) if byrow = FALSE.

byrow

Plots are added by column group, then bin group. If TRUE, plots are added by rows, rather than columns, to the grid.

main

Titles for each plot. If NULL, plots are titled by the column names, pasted together with separator " + ". Set main = NA to not title the plots.

xlabs, ylabs

Labels arranged at equal intervals along the bottom and left side of the plot grid. These are drawn in the outer margins of the figure, so oma[1] and oma[2] must be non-zero.

xlim, ylim

Limits for the x and y axes of all plots. If NULL, limits are set to the range of the data and the y limits extended as needed to include 0.

xticks, yticks

The positions of x and y tick marks for all plots. If NULL, only the min and max x and y are ticked (and 0 as needed for y). If axTicks, that function will be used to calculate R default tick mark positions. If NA, no ticks are drawn.

xtick.labels, ytick.labels

The labels for the x and y tick marks, coerced to character vectors and recycled as necessary. If NULL, the positions of the ticks are used as the labels, formatted with sigfigs. If NA, the tick marks are not labeled.

plot.grid

If TRUE, a lined horizontal grid is plotted at the yticks.

sigfigs

The maximum significant figures of the x and y axis labels.

col

Color(s) for the bars in each plot. If NA, bars are transparent. If NULL, a grey palette is used.

border

Color(s) for bar borders in each plot. If NA, borders are omitted.

lty

Line type(s) for bar borders in each plot.

lwd

Line width(s) for bar borders in each plot.

xpd

Logical value or NA. If FALSE, all plotting is clipped to the plot region, if TRUE, all plotting is clipped to the figure region, and if NA, all plotting is clipped to the device region.

mar

Numerical vector of the form c(bottom, left, top, right) giving the size of the inner margins of each plot in lines of text.

oma

Numeric vector of the form c(bottom, left, top, right) giving the size of the outer figure margins in lines of text.

...

Additional arguments passed to plot.

Details

Given a grouping variable for the rows of the event table (e.g., groups of bins of different sizes used in sample_events), and groups of columns to plot, bar plots are drawn in a grid for each combination of event and column groups. In each plot, the specified event table columns are plotted together as stacked bars. Negative and positive values are stacked separately from the y = 0 baseline. Events with NA are not shown, differentiating them from zero-valued events which are drawn as thin black lines. Point events are drawn as thin vertical lines. Overlapping events are drawn as overlapping bars, so it is best to use sample_events with non-overlapping bins to flatten the data before plotting.

See Also

seq_events for generating groups of sequential bins, sample_events to populate groups of bins with event data.

Examples

e <- events(from = c(0, 10, 15, 25), to = c(10, 20, 25, 40), length = c(10, 10, 10, 15),
            x = c(1, 2, 1, 1), f = c('a', 'b', 'a', 'a'))
bins <- seq_events(event_coverage(e), c(8, 4, 2, 1))
e.bins <- sample_events(e, bins, list(sum, c('x', 'length')), scaled.cols = 'length')
plot_events(e.bins, group.col = 'group')