Skip to contents

Plots the data

Source: R/plot_data.R
plot_data.Rd

Plots the alleles (colours), which are observed in different episodes (columns), on different markers (rows), where episodes are grouped by patient. The per-patient episodes are plotted from left to right in chronological order. If more than one allele is detected per episode per marker, the corresponding row is subdivided into rows of different colours. The order of markers follow the allele frequencies, if provided. Otherwise, markers are ordered lexicographically.

Usage

plot_data(
  ys,
  fs = NULL,
  patient.vert = FALSE,
  mar = c(1.5, 3.5, 1.5, 1),
  gridlines = TRUE,
  palette = RColorBrewer::brewer.pal(12, "Paired"),
  marker.annotate = TRUE,
  legend.lab = "Allele frequencies",
  legend.line = 0.2,
  legend.ylim = c(0.05, 0.2),
  cex.maj = 0.7,
  cex.min = 0.5,
  cex.text = 0.5,
  x.line = 0.2,
  y.line = 2.5
)

Arguments

ys

A nested list of per-patient, per-episode, per-marker allelic data. Specifically, a per-patient list of a per-episode list of a per-marker list of character vectors of observed alleles.

fs

A per-marker list of numeric vectors of allele frequencies. If NULL (default), for a given marker, only the alleles present in the data are represented in the legend, and each allele is represented equally. Because the colour scheme is adaptive (see introduction), the same allele will have a different colour in a plot of an alternative data list if more or fewer alleles are observed at the given marker across the alternative data list. If fs is specified, all possible alleles are represented and legend areas are proportional to allele frequencies; i.e., common alleles have relatively large legend areas, and rare alleles have relatively small legend areas. Specify fs to fix the colour of a given allele across plots of different data lists, thereby facilitating cross-comparison.

patient.vert

Logical. If true, patient IDs are printed vertically; otherwise they are printed horizontally (default).

mar

A vector which gives the number of lines of margin for the main plot; see the entry for mar in par.

gridlines

Logical. If true (default), white gridlines separating patients and markers will be drawn.

palette

Colour palette for alleles, see return value of brewer.pal. Generally, the colours are interpolated. If a marker has d possible alleles, then the colours used are the 1/(d+1), ..., d/(d+1) quantiles of the colours in palette. This is done such that markers with different number of possible alleles would generally use different colours.

marker.annotate

Logical. If true (default), the names of the alleles are printed on top of their colours in the legend.

legend.lab

Label for the axis of the color legend, defaults to "Allele frequencies". Set to NA if not desired. If this is the case, consider adjusting legend.ylim to use more plotting space.

legend.line

Distance in units of character height of the legend label from the colour bar, defaults to 1.5.

legend.ylim

Vector of two floats representing the y-coordinate limits of the legend in device coordinates (between 0 and 1). Defaults to c(0.05, 0.2).

cex.maj

Float representing the font scaling of major axis labels.

cex.min

Float representing the font scaling of minor axis labels.

cex.text

Float representing the font scaling for the allele labels.

x.line

Distance between top x-axis and x-axis label, defaults to 0.2.

y.line

Distance between left y-axis and y-axis label, defaults to 2.5.

Details

The legend depicts the alleles of the markers in the same vertical order as the main plot. The default colour scheme is adaptive. It is designed to visually differentiate the alleles as much as possible: the maximum range of qualitative scheme, with contrast of hue between adjacent colours. Interpolation is used to make different colour palettes for markers with different numbers of possible alleles. The names of the alleles are printed on top of their colours if marker.annotate is set to TRUE.

Examples


# Plot example Plasmodium vivax data set
mar <- c(2, 3.5, 1.5, 1) # extra vertical margin for vertical patient labels
plot_data(ys = ys_VHX_BPD, patient.vert = TRUE, mar = mar, legend.lab = NA)

plot_data(ys = ys_VHX_BPD, fs = fs_VHX_BPD, patient.vert = TRUE, mar = mar,
          legend.lab = NA)

plot_data(ys = ys_VHX_BPD, fs = fs_VHX_BPD, marker.annotate = FALSE,
          patient.vert = TRUE, mar = mar, legend.lab = NA)


# Demonstrating the adaptive nature of the colour scheme:
ys <- ys_VHX_BPD["VHX_52"] # A single patient
plot_data(ys, fs = fs_VHX_BPD) # Colours and the legend match plots above

plot_data(ys) # Colours and the legend adapt to alleles detected in VHX_52