plot_admix: Make a structure/admixture plot
In popkin: Estimate Kinship and FST under Arbitrary Population Structure

plot_admix

R Documentation

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()`.

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!

popkin documentation built on Jan. 7, 2023, 1:26 a.m.