plot_admix {popkin}

Make a structure/admixture plot

Description

This function facilitates structure plots with options that resemble those of plot_popkin() in name and results. The biggest difference is this function plots single panels (technically 2 panels including the legend, unless it is omitted), whereas plot_popkin() can plot multiple kinship matrices with a shared legend.

Usage

plot_admix(
  Q,
  col = RColorBrewer::brewer.pal(max(ncol(Q), 3), "Paired"),
  mar_pad = 0.2,
  panel_letters = NA,
  panel_letters_cex = 1.5,
  panel_letters_adj = -0.1,
  axis_lab_cex = 1,
  xlab = "Individuals",
  xlab_line = 1,
  xlab_cex = axis_lab_cex,
  ylab = "Ancestry",
  ylab_line = 2,
  ylab_side = 2,
  ylab_cex = axis_lab_cex,
  leg_title = "Ancestries",
  leg_title_cex = axis_lab_cex,
  leg_title_line = 2,
  leg_cex = 1,
  leg_mar = leg_title_line + 1,
  leg_width = 0.2,
  leg_las = 0,
  leg_omit = FALSE,
  layout_add = !leg_omit,
  names = FALSE,
  names_cex = 1,
  names_line = NA,
  names_las = 2,
  labs = NULL,
  labs_cex = 1,
  labs_las = 0,
  labs_line = 0,
  labs_sep = TRUE,
  labs_lwd = 1,
  labs_col = "black",
  labs_ticks = FALSE,
  labs_text = TRUE,
  labs_even = FALSE,
  ...
)

Arguments

Q

The admixture proportions matrix, with n individuals along rows and K ancestries along columns. Rows should sum to 1, but this is not enforced. There must be at least 2 ancestries. The ancestry labels used by the legend must be the column names, which are unlabeled if the column names are missing.

col

A vector of at least K colors for the ancestries (extra colors are ignored). By default uses the "Paired" palette of RColorBrewer, which has at most 12 colors, so please provide colors if K > 12. Since the minimum number of colors for "Paired" is 3, when K = 2 we ask for 3 colors, then remove the middle color internally.

mar_pad

Margin padding used for legend panel only (margins for first/main panel are not altered by this function).

panel_letters

Panel letter to include in first/main panel (default NA is no letter). Despite name (matches plot_popkin()), must be scalar.

panel_letters_cex

Scaling factor of panel letter (default 1.5).

panel_letters_adj

X-axis adjustment for panel letter (default -0.1). Negative values place the letter into the left margin area. Might need adjustment depending on the size of the left margin.

AXIS LABEL OPTIONS

axis_lab_cex

Scaling factor for x-axis, y-axis, and legend title labels (which can also be set individually, see below).

xlab

X-axis label (default "Individuals"). Set to NA to omit.

xlab_line

The value of line for xlab passed to graphics::mtext().

xlab_cex

Scaling factor for x-axis label.

ylab

Y-axis label (default "Ancestry"). Set to NA to omit.

ylab_line

The value of line for ylab passed to graphics::mtext().

ylab_side

The value of side for ylab passed to graphics::mtext() (2 is y-axis, 1 is x-axis, can also place on top (3) or right (4)).

ylab_cex

Scaling factor for y-axis label.

LEGEND (COLOR KEY) OPTIONS

leg_title

The name of the categorical ancestry variable (default "Ancestries").

leg_title_cex

Scaling factor for legend title label.

leg_title_line

The value of line for leg_title passed to graphics::mtext().

leg_cex

Scaling factor for ancestry labels.

leg_mar

Margin values for the kinship legend panel only. A length-4 vector (in c( bottom, left, top, right ) format that graphics::par() 'mar' expects) specifies the full margins, to which mar_pad is added. Otherwise, the margins used in the last panel are preserved with the exception that the left margin is set to mar_pad, and if leg_mar is length-1 (default), it is added to mar_pad to specify the right margin. By default the right margin is large enough to accommodate leg_title for the given value of leg_title_line.

leg_width

The width of the legend panel, relative to the width of the main panel. This value is passed to graphics::layout() (ignored if layout_add = FALSE).

leg_las

The ancestry label orientations (in format that graphics::mtext() expects).

leg_omit

If TRUE, no legend (second panel) is produced (default FALSE is to include legend).

layout_add

If TRUE (default) then graphics::layout() is called internally to create two panels: the main panel and the color key legend. The original layout is reset when plotting is complete and if layout_add = TRUE. If a non-standard layout or additional panels (beyond those provided by this function) are desired, set to FALSE and call graphics::layout() yourself beforehand.

INDIVIDUAL LABEL OPTIONS

names

If TRUE, the row (individual) names are plotted in the structure barplot.

names_cex

Scaling factor for the individual names.

names_line

Line where individual names are placed.

names_las

Orientation of labels relative to axis. Default (2) makes labels perpendicular to axis.

SUBPOPULATION LABEL OPTIONS

labs

Subpopulation labels for individuals in the admixture matrix. Use a matrix of labels to show groupings at more than one level (for a hierarchy or otherwise).

labs_cex

A vector of label scaling factors for each level of labs.

labs_las

A vector of label orientations (in format that graphics::mtext() expects) for each level of labs.

labs_line

A vector of lines where labels are placed (in format that graphics::mtext() expects) for each level of labs.

labs_sep

A vector of logicals that specify whether lines separating the subpopulations are drawn for each level of labs.

labs_lwd

A vector of line widths for the lines that divide subpopulations (if labs_sep = TRUE) for each level of labs.

labs_col

A vector of colors for the lines that divide subpopulations (if labs_sep = TRUE) for each level of labs.

labs_ticks

A vector of logicals that specify whether ticks separating the subpopulations are drawn for each level of labs.

labs_text

A vector of logicals that specify whether the subpopulation labels are shown for each level of labs. Useful for including separating lines or ticks without text.

labs_even

A vector of logicals that specify whether the subpopulations labels are drawn with equal spacing for each level of labs. When TRUE, lines mapping the equally-spaced labels to the unequally-spaced subsections of the heatmap are also drawn.

...

Additional options passed to graphics::barplot().

See Also

admix_order_cols() to automatically order ancestries given ordered individuals.

admix_label_cols() to automatically assign labels to ancestries given labels to individuals.

Examples

# create random proportions for two ancestries
Q <- runif( 10 )
Q <- cbind( Q, 1 - Q )
# add ancestry names
colnames( Q ) <- c('A1', 'A2')

# plot this data!
plot_admix( Q )

# See vignette for more elaborate examples!