Polysat

polysat is an R package for polyploid microsatellite analysis in ecological genetics. Version 1.1-0 is available on CRAN as of December 2010.

Screenshot of polysat from RGui

What polysat does

• Assumes allele copy number ambiguity in partial heterozygotes.
• Handles data of any ploidy, including mixed ploidy samples.
• Stores genotype data in a simple format that can be easily manipulated to exclude or add samples and loci.
• Imports and exports data in ABI GeneMapper Genotypes Table, GenoDive, Structure, SPAGeDi, ATetra, Tetrasat/Tetra, POPDIST, and binary presence/absence formats.
• Calculates pairwise distances between individuals using a stepwise mutation model or infinite alleles model.
• Counts alleles to assist user in estimating ploidy.
• Estimates allele frequencies in autopolyploids using either an iterative or non-iterative algorithm. Calculates pairwise F_ST based on these estimates. Mixed ploidy population size is measured in genomes rather than individuals.
• Exports allele frequencies in SPAGeDi and adegenet formats.
• Easily extensible; ordinary users can write new functions to interface with the package.

Author and Maintainer

User:Lindsay V. Clark

Obtaining polysat

If you don't already have R, download it from CRAN and install it.

At the prompt in the R console, type:

install.packages("combinat")

install.packages("polysat")

library(polysat)

Documentation

Tutorial manual: Most users will want to read this first to get a general idea of how to use the package. It starts with a broad tutorial to familiarize users with the package, then goes into more detail about how data are stored in polysat and which analyses are appropriate for autopolyploid and allopolyploid data.

R code from tutorial manual: You can copy and paste this code into the R console in order to follow along with the tutorial, or edit it to work with your own data. Emacs Speaks Statistics is a really handy program for editing this type of file and sending lines directly to R, but you can also use a simpler text editor such as Notepad to view and edit this file.

Reference manual: This is an alphabetized collection of all of the help files provided with the package. It contains more details about each function, as well as additional examples.

Graphical Front End for Import/Export

I have made a limited graphical front end (GUI) for interacting with polysat. It may be expanded in the future. Currently, it can assist the user with importing and exporting data to and from text files, as well as editing the dataset. The GUI does not yet perform any analyses (distance matrices, allele frequencies) but creates a "genambig" object, named genobject, that can be used for analysis from the R command prompt.

Notes on use of the GUI: Media: polysat_front_end_notes101017.txt

To obtain the GUI:

1. If you haven't already, follow the instructions above for installing polysat.
2. Install the package tcltk2. (Type install.packages("tcltk2") at the R prompt.)
3. Save a copy of the following file to your computer: Media: polysat_front_end101017.R.txt
4. Every time you want to launch the GUI, load the text file using the source function. For example: source("C:/Users/lvclark/Desktop/polysat_front_end101017.R.txt")

Note that the GUI has not gone through the same quality control (i.e. extensive checks on CRAN) that polysat itself has. I am offering it here "as is".

How to cite polysat

Clark, LV and Jasieniuk, M, 2011. POLYSAT: an R package for polyploid microsatellite analysis. Molecular Ecology Resources (in press). DOI: 10.1111/j.1755-0998.2011.02985.x

Upcoming in Version 1.2

Below are some functions that I am adding because I will be using them in my dissertation work. They are in various stages of development. If you have an immediate need for something on this list, email me and I may be able to send you the source code and documentation.

• A scoring system to determine whether an offspring was sexually or asexually produced, as seen in my poster at PAG XIX.
• Estimate selfing rate under polysomic inheritance, based on observed and expected frequencies of fully heterozygous genotypes.
• Given an ambiguous genotype and allele frequencies, find all possible unambiguous genotypes and their probabilities under random mating or partial selfing.
• meandistance.matrix2: When calculating the genetic distance between two individuals, use the above function to find all possible unambiguous genotypes and their probabilities, then the genetic distance between all possible combinations of unambiguous genotypes, weighted by probability. This is a better way to calculate Bruvo.distance as long as the individuals are the same ploidy.
• Some relatedness coefficients for unambiguous genotypes, to be used with meandistance.matrix2.

Wish List

This section lists additional functionality that I'm thinking of adding to polysat. If you have any additional requests (please be specific), or would like to "vote" for one of the items below to be a top priority, just send me an email! If you have created your own functions to interface with the package and would like to be added as a contributor, I am open to that as well.

• For allopolyploids, assign alleles to one genome or the other based on what genotypes are found in the population. (This is a complex problem and not on the to-do list for my dissertation, but could be very useful. Want to hire me to do this as a post-doc?) Use these allele assignments to re-code allopolyploid data into autopolyploid data by splitting each locus into two or more loci.
• On a related note, test whether genotype distributions in a population are consistent with autopolyploid or allopolyploid inheritance.
• Given probabilities of unambiguous genotypes (see above section), randomly generate an unambiguous dataset. This could then be passed to software such as adegenet that allows for polyploidy but not allele copy number ambiguity.
• More population statistics (Weir and Cockerham 1984, etc.).
• Parentage analysis

Frequently asked questions

If you have never used R before, particularly if you find command-line software to be intimidating, you may need to spend a day or two just learning R before you even touch polysat. (Look for the An Introduction to R manual on the CRAN website.) I have tried to make polysat as user-friendly as possible, but that cannot substitute for a basic understanding of how R works. Trust me, learning R is worth it! R is very powerful and efficient software for data analysis, and if you take the time to learn it for the sake of using polysat, you may find yourself using R in other areas of your research. If you are not sure how something works, try experimenting to see if it does what you think it does.

• Is missing data allowed in polysat? Yes it is! For the Structure, GenoDive, SPAGeDi, and Tetrasat/Tetra formats, you can code the missing data as you normally would for that format. For the GeneMapper format, you can either delete rows with missing data, or fill in a -9 in the first allele column for that row.
• I have made my PCA plot. Can I add a label for each sample? Yes. See ?text.
• In read.GeneMapper I got the error "line 2 did not have X elements". Each line of the file needs to have the same number of tab stops. You can add these manually in a text editor, or if you open and save the file in a spreadsheet program it should automatically insert the right number of tab stops.
• I tried to do PCoA (cmdscale) but got the error "NA values not allowed in d." If you only have one or two loci, you will need to exclude all individuals with missing data from your analysis. If you have three or more loci and still see this error, you may need to exclude individuals that are missing genotypes at multiple loci.

Known issues

Current version (1.1-0)

• None. (Email me to report any problems.)

Older versions

• editGenotypes in version 1.0 rearranges the genotypes if the samples and loci are not in alphabetical order.
• In version 0.1, read.SPAGeDi will not work with missing=0, missing=00, etc. This should not be an issue in version 1.0 because of the change in data structure. (In either version, even if the missing data symbol is at the default, -9, the software still knows that zero indicates missing data in a SPAGeDi file.)

Source code

For advanced R users, here is the source code for the functions in the package, so that you may tweak them or create new functions for your own use:

Current version (1.1-0)

• Media: classes_generics_methods_polysat_1-0-1.R.txt
• Media: class_conversion_polysat_1-0.R.txt
• Media: dataimport_polysat_1-1.R.txt
• Media: dataexport_polysat_1-1.R.txt
• Media: individual_distance_polysat_1-0.R.txt
• Media: population_stats_polysat_1-1.R.txt

Older versions

• Media: polysat_0.1_functions.R.txt
• Media: dataimport_polysat_1-0.R.txt
• Media: dataexport_polysat_1-0.R.txt
• Media: population_stats_polysat_1-0a.R.txt

External links

• You can rate and review polysat on Crantastic. (I am of course also open to questions and comments via email.)
• CRAN page with source and binary downloads.