pophelper (version 2.1.0)

plotQMultiline: Plot a qlist as individual-level multiline barplot

Description

Plot a qlist as individual-level barplot with multiple lines.

Usage

plotQMultiline(qlist = NULL, spl = NA, lpp = NA, clustercol = NA,
  grplab = NA, sortind = NA, subsetgrp = NA, grpmean = FALSE,
  indlab = TRUE, useindlab = FALSE, labsep = " ", labsize = 5,
  labangle = 90, labvjust = 0.5, labhjust = 1, barwidth = NA,
  barsize = 0.9, ticks = FALSE, yaxislabs = FALSE, imgtype = "png",
  height = NA, width = NA, dpi = 300, units = "cm", mar = c(0.1, 0.1,
  0.1, 0), theme = "theme_grey", font = "", na.rm = FALSE)

Arguments

qlist

A qlist (list of dataframes). An output from readQ.

spl

An integer indicating samples per line. Defaults to 60.

lpp

An integer indicating lines per page. Defaults to 11.

clustercol

A character vector of colours for clusters.

grplab

A named list of group labels equal to the length of individuals. See details.

sortind

A character indicating how individuals are sorted. Default is NA (Same order of individuals as in input file). Other options are 'all' (sorting by values of all clusters), by any one cluster (eg. 'Cluster1') or 'labels' (sorting by individual labels). See details.

subsetgrp

A character or character vector with group names to subset or reorder groups. Only applicable when grplab is in use. Default is NA (no group labels). See details.

grpmean

A logical indicating if q-matrix must be converted from individual values to group mean values. Applicable only when grplab is in use and only one set of group labels are used.

indlab

A logical indicating if individual labels must be shown below the bars. To hide labels, set indlab=FALSE. See details.

useindlab

A logical indicating if individual labels must be read from the rownames of qlist dataframes and used as labels.

labsep

A character used as separator when concatenating individual labels and group labels. Defaults to space labsep=" ".

labsize

A numeric denoting size of the labels. Defaults to 5.

labangle

A numeric denoting the angle of the labels. Defaults to 90.

labvjust

A numeric denoting vertical justification of the labels. Defaults to 0.5.

labhjust

A numeric denoting the horizontal justification of the labels. Defaults to 1.

barwidth

Deprecated. Use argument 'barsize' instead.

barsize

A numeric indicating the width of the bars. Defaults to 0.9.

ticks

A logical indicating if ticks on axis should be displayed or not.

yaxislabs

A logical indicating if y-axis labels should be displayed or not.

imgtype

A character denoting figure output format. Options are 'png', 'jpeg', 'tiff' or 'pdf'.

height

A numeric denoting height of the full figure. If NA, height is set to 29.7cm (A4 height).

width

A numeric denoting width of the full figure. If NA, width is set to 21cm (A4 width).

dpi

A numeric denoting resolution of the figure. Default is 300. If imgtype="pdf", dpi is fixed at 300 and does not have any effect..

units

A character denoting the units of dimension of the figure. Default is "cm". Other options are 'px', 'in' or 'mm'.

mar

A four number vector denoting distance of top, right, bottom and left margins in units.

theme

A character indicating ggplot theme to be used. Use like "theme_grey", "theme_bw" etc.

font

A character indicating font family to be used in the plots. Uses default system fonts by default for jpeg, png and tiff. Uses 'Helvetica' as default for pdf. Use package extrafonts to import custom fonts. See vignette for examples.

na.rm

Default set to FALSE. NAs are not removed from data, therefore ggplot prints warning messages for NAs. If set to TRUE, NAs are removed before plotting and ggplot NA warning is suppressed.

Details

Figures are always created to A4 size. Any plotted row will span the width of the figure. Note that this function is slow and may take several minutes when plotting mutiple runs.

Labels plotQMultiline() labels each individual separately. When indlab=T, individual labels are shown/displayed. When indlab=F, individual labels are not shown/displayed on the graph, although they are present in the underlying data. Therefore, indlab only control display of labels on the plot and nothing to do with label control in the data. The default useindlab=F, creates labels numerically in the original order of data but with zero padding. For example, if there are 10 individuals, labels are 01, 02 up to 10. if there are 100 individuals, then labels are 001, 002 up to 100. Zero padding to ensure optimal sorting. When useindlab=T, labels are used from rownames of qlist dataframes. They are usually labelled 1,2,3.. if read in using readQ(). This can be an issue with sorting by labels sortind="label". For STRUCTURE files with individual labels, they can be read in automatically using readQ(indlabfromfile=T). When group labels are in use, grplab, they are added to the individual labels in both cases useindlab=T and useindlab=F separated by labsep. Default labsep=" " adds a space between individual label and grplab. For example, group labels 'popA', 'popA'... will be '01 popA', '02 popA'... when useindlab=F and usually '1 popA', '2 popA'... when useindlab=T. When multiple group labels are in use, the are similarly concatenated one after the other to individual names in the order in which the group labels were provided.

sortind This argument takes one character as input. Default NA means individuals are plotted in the same order as input. Individuals can be ordered by any one cluster. For ex. sortind="Cluster1" or sortind="Cluster2". To order by all clusters as the 'Sort by Q' option in STRUCTURE software, use sortind="all". To order by individual labels, use sortind="label". When using sortind with grplab, individuals are sorted within the groups.

grplab grplab must be a list. One or more label sets can be provided. Each label set must be a character vector equal to the number of individuals present in the qlist. For example, we can provide one set of grp labels as such: labs1 <- c("Pop A","Pop A","Pop B","Pop B") grplab=list("grp"=labs1)

A second set of grp labels can be provided as such: labs2 <- c("Loc 1","Loc 1","Loc 2","Loc 3") grplab=list("population"=labs1,"location"=labs2)

subsetgrp This argument takes one or more characters as input. Use only group labels exactly as used in the grplab vector. For ex. In case of two grps in order 'Pop A' and 'Pop B', use subsetgrp=c("Pop B","Pop A") to change order of groups. Use subsetgrp="Pop B" to subset only Pop B.

See the vignette for more details.

Examples

# NOT RUN {
sfiles <- list.files(path=system.file("files/structure",package="pophelper"),full.names=TRUE)
slist <- readQ(sfiles)

# basic
plotQMultiline(slist[1])

# multiple files
plotQMultiline(slist[1:3])

# adjust samples per line and lines per page
plotQMultiline(slist[1],spl=75,lpp=10)

# sort individuals
plotQMultiline(slist[1],sortind="all")
plotQMultiline(slist[1],sortind="Cluster1")

# include labels from file
inds <- read.delim(system.file("files/structureindlabels.txt",package="pophelper"),header=FALSE,stringsAsFactors=FALSE)
rownames(slist[[1]]) <- inds$V1
plotQMultiline(slist[1],useindlab=T)

# change cluster colours
plotQMultiline(slist[1],clustercol=c("steelblue","coral"))

# change bar width and height
plotQMultiline(slist[1],barsize=1,spl=149,labsize=3,height=5)

# read group labels
grps1 <- read.delim(system.file("files/structuregrplabels.txt", package="pophelper"), header=F,stringsAsFactors=F)

# plot with group labels
plotQMultiline(qlist=slist[1],grplab=list("grps"=grps1$V1))
plotQMultiline(qlist=slist[1],grplab=list("grps"=grps1$V1),useindlab=T)

#sort ind within groups
plotQMultiline(qlist=slist[1],grplab=list("grps"=grps1$V1),sortind="Cluster1")

#subset or reorder groups
plotQMultiline(qlist=slist[1],grplab=list("grps"=grps1$V1),subsetgrp=c("Pop B"))
plotQMultiline(qlist=slist[1],grplab=list("grps"=grps1$V1),subsetgrp=c("Pop B","Pop A"))

# }