Perform the Evanno method for STRUCTURE runs. — evannoMethodStructure • pophelper

The Evanno method for detecting the appropriate number of population clusters from STRUCTURE results. Creates table and figure with Evanno method derivatives. Refer to return for detailed list of columns. See details for Evanno method reference.

evannoMethodStructure(
  data = NULL,
  writetable = FALSE,
  exportplot = FALSE,
  returnplot = FALSE,
  returndata = TRUE,
  pointsize = NA,
  pointtype = 20,
  pointcol = "steelblue",
  linesize = NA,
  linecol = "steelblue",
  ebwidth = 0.2,
  ebcol = "grey30",
  textcol = "grey30",
  xaxisbreaks = waiver(),
  xaxislabels = waiver(),
  basesize = 6,
  gridsize = NA,
  imgtype = "png",
  height = NA,
  width = NA,
  dpi = 300,
  units = "cm",
  theme = "theme_bw",
  font = "",
  na.rm = TRUE,
  outputfilename = "evannoMethodStructure",
  exportpath = NULL
)

Arguments

data	A dataframe with summarised runs. An output from `summariseQ()` derived from STRUCTURE runs. Must have minimum 7 columns named elpdmean, elpdsd, k, runs, loci, elpdmax and elpdmin.
writetable	A logical indicating if the output table is to be exported as a text file.
exportplot	A logical indicating if the Evanno plots are to be exported as an image. If Evanno method cannot be computed, a kPlot (elpd over k) is exported instead.
returnplot	A logical indicating if the plot must be returned. A gtable object is returned alone when `returndata=FALSE`. When `returndata=TRUE`, the gtable object is returned in a list. See 'Value'.
returndata	A logical indicating if the data must be returned. A data.frame object is returned alone when `returnplot=FALSE`. When `returnplot=TRUE`, the data.frame object is returned in a list. See 'Value'.
pointsize	A numeric indicating size of points. Default for `basesize=6` is 1.8.
pointtype	A character or number for the type of points. Defaults to 20. Same as pch in standard R.
pointcol	A colour character for the colour of points. Defaults to "steelblue".
linesize	A numeric indicating the thickness of the line. Default for `basesize=6` is 0.24.
linecol	A colour character for the colour of line. Defaults to "steelblue".
ebwidth	A numeric indicating size od width of error abrs. Defaults to 0.2.
ebcol	A colour character for colour for errorbar. Defaults to "grey30".
textcol	A colour character for all text elements on the plot. Defaults to "grey30".
xaxisbreaks	A numeric vector indicating x-axis breaks. Automatically calculated by default.
xaxislabels	A character vector indicating x-axis labels. Automatically calculated by default.
basesize	A numeric indicating the base size of various plot elements such as pointsize, linesize etc. Increase basesize with larger figure dimensions. Defaults to 6. Manually specified arguments (eg: pointsize) override basesize.
gridsize	A numeric indicating thickness of background grid. Default for `basesize=6` is 0.18.
imgtype	A character indicating the type of exported image. Default set to 'png'. Other possible options are 'jpeg', 'tiff' or 'pdf'.
height	A numeric denoting the height of exported image. Default units in 'cm'.
width	A numeric denoting the width of exported image. Default units in 'cm'.
dpi	A numeric denoting the resolution of exported image. Default set to 300. If `imgtype="pdf"`, dpi is fixed at 300.
units	A character denoting the unit of measure of the export image. Default is 'cm'. Other options are 'px', 'in' or 'mm'.
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. Does not remove NAs for plot and this generates warnings from `ggplot`. If set to TRUE, NAs are removed before plotting and warning messages from `ggplot` are avoided.
outputfilename	A character indicating output file name. Defaults to 'evannoMethodStructure'.
exportpath	A path to where content must be exported. For example, `exportpath="./dir/anotherdir"`. To use the current working directory, set `exportpath=getwd()`.

Value

When returndata=TRUE and returnplot=FALSE, a data.frame is returned. When returndata=FALSE and returnplot=TRUE, a gtable plot object is returned. When returndata=TRUE and returnplot=TRUE, a list with data.frame and gtable object is returned.

The data.frame contains Evanno results sorted by K. The table has 16 columns namely Mean estimated ln probability of data, Standard deviation, Value of K, Number of runs for each K, Number of runs for each K, Number of individuals for each K, Number of loci for each K, Estimated ln probability of data plus standard deviation, Estimated ln probability of data minus standard deviation, First derivative, Max error of first derivative, Min error of first derivative, Second derivative, Max error of second derivative, Min error of second derivative and the Third derivative.

The gtable object is a result of gridExtra::arrangeGrob(). This is suitable for plotting in a report.

Details

The Evanno method is based on the paper: Evanno, G., Regnaut, S., and Goudet, J. (2005). Detecting the number of clusters of individuals using the software STRUCTURE: a simulation study. Molecular ecology, 14(8), 2611-2620. The Evanno plot generated from this function can be recreated from the returned dataframe if further customisation is required.

See the vignette for more details.

Examples


if (FALSE) {
sfiles <- list.files(path=system.file("files/structure",package="pophelper"),
full.names=TRUE)
tr1 <- tabulateQ(readQ(sfiles))
sr1 <- summariseQ(tr1)
evannoMethodStructure(sr1)
evannoMethodStructure(data=sr1,exportplot=TRUE,exportpath=getwd())
}