Plot a qlist as individual-level barplot with multiple lines.
plotQMultiline( qlist = NULL, spl = NA, lpp = NA, clustercol = NA, sortind = NA, grplab = NA, selgrp = NA, ordergrp = FALSE, subsetgrp = NA, grpmean = FALSE, showindlab = TRUE, useindlab = FALSE, indlabwithgrplab = FALSE, indlabsep = " ", indlabsize = 5, indlabangle = 90, indlabvjust = 0.5, indlabhjust = 1, indlabcol = "grey30", indlabspacer = 1.5, showgrplab = TRUE, grplabsize = 7, grplabcol = "grey30", grplabbgcol = "#DCDCDC", showtitle = FALSE, titlelab = NA, titlehjust = 0, titlevjust = 0.5, titlesize = 9, titlecol = "grey30", titleface = "plain", titlespacer = 3, titleangle = 0, showsubtitle = FALSE, subtitlelab = NA, subtitlehjust = 0, subtitlevjust = 0.5, subtitlesize = 7, subtitlecol = "grey30", subtitleface = "plain", subtitlespacer = 4, subtitleangle = 0, showlegend = FALSE, legendlab = NA, legendpos = "right", legendkeysize = 6, legendtextsize = 8, legendmargin = c(1, 1, 1, 0), barsize = 0.9, barbordersize = 0, barbordercolour = NA, showticks = FALSE, showyaxis = FALSE, ticksize = 0.1, ticklength = 0.03, outputfilename = NA, imgtype = "png", height = NA, width = NA, dpi = 300, units = "cm", mar = c(0.1, 0.5, 0.1, 0.5), theme = "theme_grey", basesize = 5, font = "", na.rm = FALSE, exportplot = TRUE, returnplot = FALSE, returndata = FALSE, exportpath = NULL )
| qlist | A qlist (list of dataframes). An output from |
|---|---|
| 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. |
| 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. |
| grplab | A dataframe with one or more columns (group label sets), and rows equal to the number of individuals. See details. |
| selgrp | A single character denoting a selected group label set. The
selected label must be a group label title used in |
| ordergrp | A logical indicating if individuals must be grouped into
contiguous blocks based on |
| subsetgrp | A character or character vector with group names to subset
or reorder groups. Only applicable when |
| grpmean | A logical indicating if q-matrix must be converted from
individual values to group mean values. Applicable only when |
| showindlab | A logical indicating if individual labels must be shown
below the bars. To hide labels, set |
| useindlab | A logical indicating if individual labels must be read from the rownames of qlist dataframes and used as labels. See details. |
| indlabwithgrplab | A logical indicating if individual labels must be concatenated with grplab. Applies only when grplab is in use. Relevant for sorting by label. |
| indlabsep | A character used as separator when concatenating individual
labels and group labels. Defaults to space |
| indlabsize | A numeric denoting size of the individual labels. Defaults to 5. |
| indlabangle | A numeric denoting the angle of the individual labels. Defaults to 90. |
| indlabvjust | A numeric denoting vertical justification of the individual labels. Defaults to 0.5. |
| indlabhjust | A numeric denoting the horizontal justification of the individual labels. Defaults to 1. |
| indlabcol | A colour for individual labels. Defaults to 'grey30'. |
| indlabspacer | A numeric denoting space between the individual label and the plot area. Default set to 0. |
| showgrplab | A logical indicating if group labels |
| grplabsize | A numeric denoting size of the group labels. Defaults to 7. |
| grplabcol | A colour for group labels. Defaults to 'grey30'. |
| grplabbgcol | A colour for group label background. Defaults to 'white'. |
| showtitle | A logical indicating if plot title must be shown on the top.
Defaults to FALSE. If TRUE and |
| titlelab | A character or character vector for title text. Defaults to
NA, and when |
| titlehjust | A numeric denoting the horizontal justification of the title. Defaults to 0 (left). |
| titlevjust | A numeric denoting the vertical justification of the title. Defaults to 0.5 (center). |
| titlesize | A numeric indicating the size of the title text. Defaults to 5 points. |
| titlecol | A colour character for title. Defaults to "grey30". |
| titleface | A character indicating the font face of title label. One of
'plain', 'italic', 'bold' or 'bold.italic'. Defaults to 'plain'. Applicable
only when |
| titlespacer | A numeric indicating the space below the title. Defaults to 1.2. |
| titleangle | A numeric indicating the angle/rotation of the title. Defaults to 0. |
| showsubtitle | A logical indicating if plot subtitle must be shown on
the top. Defaults to FALSE. If TRUE and |
| subtitlelab | A character or character vector for subtitle text.
Defaults to NA, and when |
| subtitlehjust | A numeric denoting the horizontal justification of the subtitle. Defaults to 0 (left). |
| subtitlevjust | A numeric denoting the vertical justification of the subtitle. Defaults to 0.5 (center). |
| subtitlesize | A numeric indicating the size of the subtitle text. Defaults to 5 points. |
| subtitlecol | A colour character for subtitle. Defaults to "grey30". |
| subtitleface | A character indicating the font face of subtitle label.
One of 'plain', 'italic', 'bold' or 'bold.italic'. Defaults to 'plain'.
Applicable only when |
| subtitlespacer | A numeric indicating the space below the subtitle. Defaults to 1.2. |
| subtitleangle | A numeric indicating the angle/rotation of the subtitle. Defaults to 0. |
| showlegend | A logical indicating if legend denoting cluster colours must be plotted. Defaults to FALSE. |
| legendlab | A character or character vector to for legend cluster labels. Must be equal to max number of clusters. |
| legendpos | A character 'right' or 'left' denoting position of the legend. Defaults to 'left'. |
| legendkeysize | A numeric indicating size of the legend key. Defaults to 4. |
| legendtextsize | A numeric indicating size of the legend text. Defaults to 3. |
| legendmargin | A numeric vector of length 4 indicating top, right, bottom and left margins of the legend. |
| barsize | A numeric indicating the width of the bars. Defaults to 0.9. |
| barbordersize | A numeric indicating border size of bars. Defaults to 0.
Visible only when |
| barbordercolour | A single colour for bar border. Defaults to NA.
Visible only when |
| showticks | A logical indicating if ticks on axis should be displayed or not. Defaults to FALSE. |
| showyaxis | A logical indicating if y-axis labels should be displayed or not. Defaults to FALSE. |
| ticksize | A numeric indicating size of ticks. Defaults to 0.2. Applies to both x and y axis. |
| ticklength | A numeric indicating length of tick marks in cm. Defaults to 0.03. Applies to both x and y axis. |
| outputfilename | A character or character vector denoting output file name without file extension. See details. |
| 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
|
| 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 |
| theme | A character indicating ggplot theme to be used. Use like "theme_grey", "theme_bw" etc. |
| basesize | A numeric indicating overall text size. Defaults to 5 suitable for export. Set to 11 for returned plot. |
| 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 |
| na.rm | Default set to FALSE. NAs are not removed from data, therefore
|
| exportplot | A logical indicating if a plot image must be exported into the working directory. |
| returnplot | A logical indicating if ggplot plot objects must be returned. See 'Value'. |
| returndata | A logical indicating if processed data must be returned. See 'Value'. |
| exportpath | A path to where content must be exported. For example,
|
When returnplot=TRUE, plot object(s) are returned. When
grplab=NA, a ggplot2 object is returned. When returndata=TRUE,
the input qlist is modified (sorted, subsetted etc) and returned. If
grplab is in use, a list of modified qlist and grplab is returned.
If returnplot=TRUE and returndata=TRUE are both set, then a
named list (plot,data) is returned. The plot item contains the ggplot2 object
and the data contains qlist (and grplab).
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.
indlab
plotQMultiline() labels each individual separately. When
showindlab=TRUE,
individual labels are shown/displayed. When showindlab=FALSE, individual
labels are not shown/displayed on the graph, although they are present in the
underlying data. Therefore, showindlab only control display of labels
on the plot and nothing to do with label control in the data.
The default useindlab=FALSE, 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 upto 100. Zero padding to ensure optimal sorting. When
useindlab=TRUE, 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=TRUE).
When group labels are in use, grplab, they are added to the individual
labels in both cases useindlab=TRUE and useindlab=FALSE separated by
indlabsep. Default indlabsep=" " adds a space between
individual label and grplab. For example, group labels 'popA', 'popA'... will
be '01 popA', '02 popA'... when useindlab=FALSE and usually '1 popA',
'2 popA'... when useindlab=TRUE. 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("Grp A","Grp A","Grp B","Grp 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.
outputfilename
Output file names are created automatically by default using the input qlist
names. When number of individuals exceed one page and extra pages are
created, incremental numbers are added to the run name like so: -1, -2 etc.
Custom file name can be provided to outputfilename. The number of
labels must be equal to the number of input runs. Incremental numbers are
still added if extra pages are created.
See the vignette for more details and examples.
if (FALSE) { sfiles <- list.files(path=system.file("files/structure",package="pophelper"), full.names=TRUE) slist <- readQ(sfiles) # basic plotQMultiline(slist[1],exportpath=getwd()) # multiple files plotQMultiline(slist[1:3],exportpath=getwd()) # adjust samples per line (spl) and lines per page (lpp) plotQMultiline(slist[1],spl=30,exportpath=getwd()) plotQMultiline(slist[1],lpp=8,exportpath=getwd()) plotQMultiline(slist[1],spl=75,lpp=10,exportpath=getwd()) # sort individuals plotQMultiline(slist[1],sortind="all",exportpath=getwd()) plotQMultiline(slist[1],sortind="Cluster1",exportpath=getwd()) plotQMultiline(slist[1],sortind="label",exportpath=getwd()) # use custom individual labels inds <- read.delim(system.file("files/structureindlabels.txt", package="pophelper"),header=FALSE,stringsAsFactors=FALSE) rownames(slist[[1]]) <- inds$V1 plotQMultiline(slist[1],useindlab=TRUE,exportpath=getwd()) # change cluster colours plotQMultiline(slist[1],clustercol=c("steelblue","coral"),exportpath=getwd()) # change bar width and height plotQMultiline(slist[1],barsize=1,spl=149,indlabsize=3,height=5,exportpath=getwd()) # read group labels md <- read.delim(system.file("files/metadata.txt", package="pophelper"), header=TRUE,stringsAsFactors=FALSE) # plot with one group label set plotQMultiline(qlist=slist[1],grplab=md[,2,drop=FALSE],exportpath=getwd()) plotQMultiline(qlist=slist[1],grplab=md[,2,drop=FALSE],useindlab=TRUE,exportpath=getwd()) # sort ind within groups plotQMultiline(qlist=slist[1],grplab=md[,2,drop=FALSE],sortind="Cluster1",exportpath=getwd()) plotQMultiline(qlist=slist[1],grplab=md[,2,drop=FALSE],sortind="all",exportpath=getwd()) plotQMultiline(qlist=slist[1],grplab=md[,2,drop=FALSE],sortind="label",exportpath=getwd()) # subset or reorder groups plotQMultiline(qlist=slist[1],grplab=md[,2,drop=FALSE],subsetgrp=c("CatB"),exportpath=getwd()) plotQMultiline(qlist=slist[1],grplab=md[,2,drop=FALSE], subsetgrp=c("Cat B","CatA"),exportpath=getwd()) # using multiple group label sets plotQMultiline(qlist=slist[1],grplab=md,ordergrp=TRUE,exportpath=getwd()) # subset on a group from second group label set plotQMultiline(qlist=slist[1],grplab=md,selgrp="cat",subsetgrp="CatB",exportpath=getwd()) }