pophelper is an R package and web app to analyse and visualise population structure. pophelper can be curently used to analyse output files generated from population analysis programs such as STRUCTURE, TESS and ADMIXTURE. The pophelper package can be used to tabulate runs, summarise runs, estimate K using the Evanno method, export files for CLUMPP, generate barplot figures, spatial plots and interpolation using geographical coordinates.

For a detailed demonstration, refer the vignette. Click here to watch video tutorials. New versions and updates are shown only on this GitHub page.

You need to have R (> 3.1.2) statistical package installed on your system. R is open-source and freely available to download for Windows, Mac and other OS. Then, install the 'devtools' package. Then, you can install pophelper from github using the devtools package.

#install devtools package from CRAN
install.packages('devtools',dep=T)
library(devtools)

#install pophelper package from GitHub
install_github('royfrancis/pophelper')

#load library for use
library(pophelper)

An online interactive version of pophelper is now available at pophelper.com.

For help on any function, use
?tabulateRunsStructure
?evannoMethodStructure

For functions where one or more files need to be selected, the selection can be performed interactively. Windows users can use choose.files(multi=T). Mac users can use file.choose() for single selection and tk_choose.files() from tcltk package for multiple selection.

tabulateRunsStructure()   # Get a tabulation of several STRUCTURE files
summariseRunsStructure()  # Summarise runs by repeats for each K
evannoMethodStructure()   # Perform the Evanno method on summarised data
runsToDfStructure()       # Convert STRUCTURE run files to R dataframe
clumppExportStructure()   # Export data file and parameter file for use with CLUMPP

collectRunsTess()         # Collect TESS output from multiple folders into one
tabulateRunsTess()        # Get a tabulation of several TESS files
summariseRunsTess()       # Summarise runs by repeats for each K
runsToDfTess()            # Convert TESS run files to R dataframe
clumppExportTess()        # Export data file and parameter file for use with CLUMPP

collectClumppOutput()     # Collect CLUMPP output into a common folder
plotRuns()                # Plot a barplot from STRUCTURE/TESS/table files
PlotMultiline()           # Plot a multi-line barplot from STRUCTURE/TESS/table file
plotRunsInterpolate()     # Spatially interpolate clusters from a STRUCTURE/TESS run file
plotRunsSpatial()         # Cluster by max assignment and plot points spatially

analyseRuns()             # A wrapper function to quickly tabulate, summarise, perform evanno method, 
                            clumpp output and generate barplots from STRUCTURE or TESS run files.

A long demo script with usage of all functions, see here

Fig 1. Workflow for STRUCTURE files. Files/objects are indicated in black text and functions are indicated in blue. The analyseRuns() function is a wrapper function which can be used to run several functions together. This is indicated by the asterisk and the orange path. For clumpp results, the clumpp executable must be run to continue with the workflow.

Fig 2. Workflow for TESS files. Files/objects are indicated in black text and functions are indicated in blue. The analyseRuns() function is a wrapper function which can be used to run several functions together. This is indicated by the asterisk and the orange path. For clumpp results, the clumpp executable must be run to continue with the workflow.

Fig 3. Plots from Evanno Method.

Fig 4. Folders created from CLUMPP export and the contents of each folder.

Fig 5. Folder showing CLUMPP results: aligned file, merged file and misc file.

Fig 6. An overview of the components of a plot from the function plotRuns() and the arguments used to modify them.

Fig 7. Left: Single run plotted separately. Right: Two runs joined together in one image.

Fig 8. Left: Single run plotted separately with pop labels. Right: Two runs joined together in one image with pop labels.

Fig 9. Left: Combined files (Three STRUCTURE runs for K=4). Middle: Aligned files (Three STRUCTURE runs for K=4 aligned using CLUMPP). Right: Merged file (Three runs for K=4 merged into one table/figure using CLUMPP).

Fig 10. Left: plotMultiline default output. Right: Modified output where samples per line and lines per page were defined manually.

Fig 11. Multiline plots with (left) standard colours, (middle) rich.colors() from gplots package and (right) brewer.pal(8,"Spectral") from RColorBrewer package.

Fig 12. Interpolated plot of one TESS run file containing 6 clusters (K=6). The default interpolation algorithm (method) used was kriging. In this particular case, it is known that K=2, therefore only cluster 2 has useful information.

Fig 13. Interpolated plot of one cluster (Cluster 2) of one TESS run file containing 6 clusters (K=6) showing different interpolation methods. Row 1 from left: bilinear, bicubic and Inverse distance weighting. Row 2 from left: Nearest neighbour and Kriging.

Fig 14. Interpolation plots showing some of the available colour palettes.

Fig 15. Some of the plots created using the function plotRunsSpatial().

For detailed demonstration and description, refer the vignette.

The pophelper R package is offered free and without warranty of any kind, either expressed or implied. I will not be held liable to you for any damage arising out of the use, modification or inability to use this program. pophelper R package can be used, redistributed and/or modified freely for non-commercial purposes subject to the original source being properly cited. Licensed under GPL-3. Please make sure you verify all your results by eye atleast once per batch.

If you have an issues, suggestions, corrections, ideas on ways to improve or extend this package, feel free to contact me, or add a comment to the issues section here on Github. Preferred email is roy.m.francis@outlook.com. My spam filter sometimes goes hyper and swallows emails. If you don't receive a reply from me in 48 hours, consider sending an email to roy.francis@ebc.uu.se as well.

2015 Roy M Francis | roy.m.francis@outlook.com