PopGenReport - a simple way to analyse population genetic data using R

**** Version 2.2.2 on CRAN, be aware that in landgenreport there is still a bug in the landgenreport function. Make sure your locus names are still unique if they are truncated to the first six letters otherwise you will get an error in the landgenreport stating your genind object is invalid. If you get this error change the names of your loci via locNames. this bug will be treated in the next upgrade.

**** bugfix upgrade of PopGenReport (Version 2.2.2) to repair broken functions counts, gdkosman, gdsmouse and null alleles due to adegenet 2.0.2 changes.

**** Upgrade to work with Adegenet 2.0 ****. Please check below how to upgrade to the latest developer version from Github if you experience errors with popgenreport!!

**** Latest versions now on Github. See notes below how to install the developer version ****

**** A description of the landgenreport functions has been recently published (February 2015) ****

Gruber & Adamack (2015) Landgenreport: a new R function to simplify landscape genetic analysis using resistance surface layers, Molecular Ecology Resources, DOI: 10.1111/1755-0998.12381

This document serves as a quick guide for the installation of R and Latex(optional but recommended) to run PopGenReport successfully. For a more detailed description of the installation process and a tutorial how to do an analysis download the tutorial PopGenReportTutorial (pdf).

In a nutshell

The main strength of PopGenReport is to simplify a population genetic analysis. The aim is to make the power of R and its functions to analyse population genetic data available to many more researchers by providing a low-level entry. Hence we aimed for simplicity. A general workflow includes only two steps.

1. load your data into R using various file formats (genepop, structure or a simple text or Excel csv file)
2. use the function popgenreport to analyse your data [and create a nicely layouted pdf of your analysis (optional)]
3. (optional) use the output which are in the form of maps, figures and tables for your final publication
4. (optional) use the provided R code to sophisticate and customize your analysis

Installation

To install PopGenReport you can either install it

• locally at your machine. Be ware that you need to have admin rights to install R and LaTeX. LatTeX is optional, but required if you want to have a pdf as output.
• via a usb stick or in a folder (no admin rights required)

1. Local install
• download and install the latest R version for your system (Windows, Mac, Linux) from CRAN (http://cran.r-project.org/)
• (optional)download and install a LateX distribution (be aware there are 32 and 64 bit versions for some OSs). We suggest MikTeX for Windows, MacTeX for Mac (not tested yet), TexLive for Linux (not tested yet).
• (optional) download and install a more comfortable editor for R such as Rstudio, JGR or Tinn-R.




2. USB stick /local folder (currently Windows only)

• download the file PopGenPack.zip (~334 MB). It includes a running version of R (3.1.0), PopGenReport (currently 2.1) and MikTex (portable 2.9.4757).
• unzip (e.g. using 7-zip) the file to your usb drive or a local folder (~600 MB).
• link R and MikTex. Finally you need to tell R where it can find MikTex and this depends on the location where you unzipped your folder to); If you unzipped it to your local usb drive (e.g. E:\ on windows) then there should be a PopGenPack folder and the full command need to be as specified below:
  • Sys.setenv(PATH = paste(Sys.getenv("PATH"),"E:/PopGenPack/Miktex/miktex/bin/", sep=.Platform$path.sep))
• update to the latest PopGenReport version via
  • install.packages("PopGenReport")

Test the installation by typing the following lines into your R console:

require(PopGenReport)
data(bilby) #this loads some sample data
popgenreport(bilby) #if you installed LaTeX
popgenreport(bilby, mk.pdf=FALSE) #if you did not install LaTeX

You should get the following output (if you installed LaTeX):

There is no figures folder. I am trying to create it otherwise create it manually.
Compiling report...
- Generall summary...

Analysing data ...
Creating pdf from: PopGenReport.rnw ...
Finished.
Check PopGenReport.pdf for results.
Files are saved under: C:\DOCUME~1\user\LOCALS~1\Temp\RtmpcTcsaf
Figures are available in the figures subfolder
Results are stored under PopGenReport.results as an R object

and the following output if you did not install LaTeX:

Compiling report...
- Generall summary...

Analysing data ...
Files are saved under: C:\DOCUME~1\user\LOCALS~1\Temp\RtmpcTcsaf
Figures are available in the figures subfolder
Results are stored under PopGenReport.results as an R object

You can check your output files by accessing the specified folder.
For further information on how to load your data into R type ?read.genetable and on how to do an analysis type ?popgenreport

Tutorial for beginners

Tutorial on how to install the package and do a first analysis using popgenreport .

Tutorial on how to use the least-cost path modelling functions (landgenreport).

Or simply type browseVignettes("PopGenReport") to access the tutorial from within the package (be aware the landscape tutorial is currently only available from here).

Have fun analysing your data using PopGenReport.

Please be aware that PopGenReport is a work in progress and it is likely to contain bugs. Therefore please do not hesitate to contact us via bernd.gruber@canberra.edu.au or aaron.adamack@canberra.edu.au, if you encounter problems, have a comment and/or have a feature request.

Version history and known bugs

PopGenReport 2.2.2 (Github version) How to update?

• Due to recent upgrades in Adegenet and other packages it was necessary to upgrade very frequently with some hot bug fixes for popgenreport
• If you experience problems with popgenreport this is mainly due to these upgrades of other packages (but of course there maybe also bugs in popgenreport). For example adegenet is currently very actively developed and needs to be upgraded as well.
• To get the latest version of PopGenreport type the following in the console:

• install.packages("devtools") # in case not already installed
  library(devtools)
  install_github("green-striped-gecko/PopGenReport")
  install_github("thibautjombart/adegenet") # adegenet 2.0 had quite some bugs
  install_github("jgx65/hierfstat") #pairwise.fst no longer in adegenet
  library("PopGenReport")
  

• Please be aware the the github versions might not be properly tested but it is the best workaround in case you experience strange errors.

PopGenReport 2.2.2

• be aware that in landgenreport there is still a bug in the landgenreport function. Make sure your locus names are still unique if they are truncated to the first six letters otherwise you will get an error in the landgenreport stating your genind object is invalid. If you get this error change the names of your loci via locNames. this bug will be treated in the next upgrade.
• fixes errors in the mk.counts, mk.nullalleles, mk.gd.smouse and mk.gd.kosman functions of popgenreport
• references added to report
• Note: in some instances the bibtex causes a warning when running popgenreport which is not problematic

PopGenReport 2.2

• Developing versions now on Github. Install via devtools. Please note that some functions may not be fully tested.
  • library devtools()
  • install_github("green-striped-gecko/PopGenReport")
• Version 2.2 works with Adegenet 2.0 (not yet uploaded to Cran as Adegenet is also not uploaded yet (06/07/2015)
• Some minor bugfixes to make sure indNames and popNames are unique
• new function costdistances to calculate costdistances seperately from landgenreport. You can now do an analysis without generating a full report. Workflow: a) generate genetic, euclidean and cost distances and then use Wassermann/lgrMMRR to test these.

PopGenReport 2.1

• added new plot of pairwise distance matrices to landgenreport
• Vignette do now compile and can be found via vignetteBrowse("PopGenReport")
• NN=4 is no longer default, must be specified (otherwise warning is issued)
• Also includes additional cost paths such as circuitscape equivalent and randomized shortest-path distance

PopGenReport 2.0

• New version that has now the additional function to do a least cost path analysis (landgenreport, genleastcost, lgr.MMRR and wassermann)
• Vignette did not compile, Tutorial on landgenreport is in the doc folder of the popgenreport library (or download it from here).

PopGenReport 1.6.5

• took care of "cx" warning when mk.counts=TRUE
• a warning is issued if identical individual names are used within a genind object

PopGenReport 1.6.1

• vignetteBrowse("PopGenReport") works now
• read.genetable(): works now also with more than 26 loci, be aware loci headers needs to be unique!!!!

PopGenReport 1.6

• vignetteBrowse("PopGenReport") does not work. To find the tutorial check the file "PopGenReportIntroduction.pdf" in the doc subfolder in the PopGenReport library folder: system.file("doc", package="PopGenReport")
• read.genetable(): make sure you have unique loci name for each loci using the first 4 characters if you have more than 26 loci, otherwise popgenreport does not run properly.