This function plots one or more kinship matrices and a shared legend for the color key. Many options allow for fine control of individual or subpopulation labeling. This code assumes input matrices are symmetric.
plot_popkin(kinship, titles = NULL, col = NULL, col_n = 100,
mar = NULL, mar_pad = 0.2, diag_line = FALSE,
panel_letters = toupper(letters), panel_letters_cex = 1.5,
ylab = "Individuals", ylab_adj = NA, ylab_line = 0,
layout_add = TRUE, layout_rows = 1, leg_title = "Kinship",
leg_cex = 1, leg_mar = NULL, leg_n = 5, names = FALSE,
names_cex = 1, names_line = NA, 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, ...)A numeric kinship matrix or a list of matrices.
Note kinship may contain NULL elements (makes blank plots with titles; good for placeholders or non-existent data)
Titles to add to each matrix panel (default is no titles)
Colors for heatmap (default is a red-white-blue palette symmetric about zero constructed using RColorBrewer).
The number of colors to use in the heatmap (applies if col = NULL).
Margins for each panel (if a list) or for all panels (if a vector).
Margins are in c(bottom,left,top,right) format that par('mar') expects.
Note the padding mar_pad below is also added to every margin if set.
If NULL, the original margin values are used without change, and are reset for every panel that has a NULL value.
The original margins are also reset after plotting is complete.
Margin padding added to all panels (mar above and leg_mar below).
Default 0.2.
Must be a scalar or a vector of length 4 to match par('mar').
If TRUE adds a line along the diagonal (default no line).
May also be a vector of booleans to set per panel (lengths must agree).
Vector of strings for labeling panels (default A-Z).
No labels are added if panel_letters = NULL, or when there is only one panel except if panel_letters is set to a single letter in that case (this behavior is useful if goal is to have multiple external panels but popkin only creates one of these panels).
Scaling factor of panel letters (default 1.5).
AXIS LABEL OPTIONS
The y-axis label (default "Individuals").
If length(ylab) == 1, the label is placed in the outer margin (shared across panels);
otherwise length(ylab) must equal the number of panels and each label is placed in the inner margin of the respective panel.
The value of "adj" passed to mtext.
If length(ylab) == 1, only the first value is used, otherwise length(ylab_adj) must equal the number of panels.
The value of "line" passed to mtext.
If length(ylab) == 1, only the first value is used, otherwise length(ylab_line) must equal the number of panels.
LAYOUT OPTIONS
If TRUE (default) then layout is called internally with appropriate values for the required number of panels for each matrix, the desired number of rows (see layout_rows below) plus 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 plot_popkin) are desired, set to FALSE and call layout yourself beforehand.
Number of rows in layout, used only if layout_add = TRUE.
LEGEND (COLOR KEY) OPTIONS
The name of the variable that the heatmap colors measure (default "Kinship").
Scaling factor for leg_title (default 1).
Margin vector (in c(bottom,left,top,right) format that par('mar') expects) for the legend panel only.
If not provided, the margins used in the last panel are preserved with the exception that the left margin is set to zero (plus the value of mar_pad, see above).
The desired number of ticks in the legend y-axis (input to pretty, see that for more details).
INDIVIDUAL LABEL OPTIONS
If TRUE, the column and row names are plotted in the heatmap.
Scaling factor for the column and row names.
Line where column and row names are placed.
SUBPOPULATION LABEL OPTIONS
Subpopulation labels for individuals. Use a matrix of labels to show groupings at more than one level (for a hierarchy or otherwise). If input is a vector or a matrix, the same subpopulation labels are shown for every heatmap panel; the input must be a list of such vectors or matrices if the labels vary per panel.
A vector of label scaling factors for each level of labs, or a list of such vectors if labels vary per panel.
A vector of label orientations (in format that mtext expects) for each level of labs, or a list of such vectors if labels vary per panel.
A vector of lines where labels are placed (in format that mtext expects) for each level of labs, or a list of such vectors if labels vary per panel.
A vector of booleans that specify whether lines separating the subpopulations are drawn for each level of labs, or a list of such vectors if labels vary per panel.
A vector of line widths for the lines that divide subpopulations (if labs_sep = TRUE) for each level of labs, or a list of such vectors if labels vary per panel.
A vector of colors for the lines that divide subpopulations (if labs_sep = TRUE) for each level of labs, or a list of such vectors if labels vary per panel.
A vector of booleans that specify whether ticks separating the subpopulations are drawn for each level of labs, or a list of such vectors if labels vary per panel.
A vector of booleans that specify whether the subpopulation labels are shown for each level of labs, or a list of such vectors if labels vary per panel. Useful for including separating lines or ticks without text.
A vector of booleans that specify whether the subpopulations labels are drawn with equal spacing for each level of labs, or a list of such vectors if labels vary per panel.
When TRUE, lines mapping the equally-spaced labels to the unequally-spaced subsections of the heatmap are also drawn.
Additional options passed to image.
These are shared across panels
plot_popkin plots the input kinship matrices as-is.
For best results, a standard kinship matrix (such as the output of popkin) should have its diagonal rescaled to contain inbreeding coefficients (inbr_diag does this) before plot_popkin is used.
This function permits the labeling of individuals (from row and column names when names = TRUE) and of subpopulations (passed through labs).
The difference is that the labels passed through labs are assumed to be shared by many individuals, and lines (or other optional visual aids) are added to demarcate these subgroups.
# NOT RUN {
# Construct toy data
X <- matrix(c(0,1,2,1,0,1,1,0,2), nrow = 3, byrow = TRUE) # genotype matrix
subpops <- c(1,1,2) # subpopulation assignments for individuals
# NOTE: for BED-formatted input, use BEDMatrix!
# "file" is path to BED file (excluding .bed extension)
## library(BEDMatrix)
## X <- BEDMatrix(file) # load genotype matrix object
# estimate the kinship matrix from the genotypes "X"!
kinship <- popkin(X, subpops) # calculate kinship from X and optional subpop labels
# simple plot of the kinship matrix, marking the subpopulations only
# note inbr_diag replaces the diagonal of kinship with inbreeding coefficients
# (see vignette for more elaborate examples)
plot_popkin( inbr_diag(kinship), labs = subpops )
# }
Run the code above in your browser using DataLab