Package 'polysat'

Accessor and Replacement Functions for "gendata" Objects

Description

The accessor functions return information that is contained, either directly or indirectly, in the slots of a gendata object. The replacement functions alter information in one or more slots as appropriate.

Usage

Samples(object, populations, ploidies)
Samples(object) <- value
Loci(object, usatnts, ploidies)
Loci(object) <- value
PopInfo(object)
PopInfo(object) <- value
PopNames(object)
PopNames(object) <- value
PopNum(object, popname)
PopNum(object, popname) <- value
Ploidies(object, samples, loci)
Ploidies(object) <- value
Usatnts(object)
Usatnts(object) <- value
Description(object)
Description(object) <- value
Missing(object)
Missing(object) <- value
Present(object)
Present(object) <- value
Absent(object)
Absent(object) <- value
Genotype(object, sample, locus)
Genotype(object, sample, locus) <- value
Genotypes(object, samples = Samples(object), loci = Loci(object))
Genotypes(object, samples = Samples(object), loci = Loci(object)) <- value

Arguments

object	An object of the class gendata or one of its subclasses.
populations	A character or numeric vector indicating from which populations to return samples. (optional)
ploidies	A numeric vector indicating ploidies, if only samples or loci with a certain ploidy should be returned. (optional)
sample	A character string or number indicating the name or number of the sample whose genotype should be returned.
locus	A character string or number indicating the name or number of the locus whose genotype should be returned.
samples	A character or numeric vector indicating samples for which to return genotypes or ploidies. (optional)
loci	A character or numeric vector indicating loci for which to return genotypes or ploidies. (optional)
usatnts	A numeric vector indicating microsatellite repeat lengths, where only loci of those repeat lengths should be returned. (optional)
popname	Chacter string or vector. The name(s) of the population(s) for which to retrieve or replace the corresponding PopInfo number(s). The replacement function should only be used for one population at a time.
value	For Samples: a character vector of sample names. For Loci: a character vector of locus names. For PopInfo: A numeric vector (integer or can be coerced to integer) indicating the population identities of samples. For PopNames: A character vector indicating the names of populations. For PopNum: A number (integer or can be coerced to integer) that should be the new population number associated with popname. For Ploidies: A numeric vector or matrix (integer or can be coerced to integer) indicating the ploidy of each sample, locus, and/or the dataset. See reformatPloidies and "ploidysuper". For Usatnts: A numeric vector (integer or can be coerced to integer) indicating the repeat type of each microsatellite locus. Dinucleotide repeats should be represented with 2, trinucleotide repeat with 3, and so on. If the alleles for a given locus are already stored in terms of repeat number rather than fragment length in nucleotides, the Usatnts value for that locus should be 1. For Description: A character string or character vector describing the dataset. For Missing: A symbol (usually an integer) to be used to indicate missing data. For Present: A symbol (usually an integer) to be used to indicate the presence of an allele. For Absent: A symbol (usually an integer) to be used to indicate the absence of an allele. For Genotype: a vector of alleles, if the object is of class genambig. For Genotypes: A list of vectors (genotypes), of the same dimensionality as c(length(samples), length(loci)), if the object is of class genambig. If the object is of class genbinary, value should be a matrix, with column names of the form "locus.allele". See Genotypes<-,genbinary-method for more information.

Details

Samples<- and Loci<- can only be used to change sample and locus names, not to add or remove samples and loci from the dataset.

For slots that require integer values, numerical values used in replacement functions will be coerced to integers. The replacement functions also ensure that all slots remain properly indexed.

The Missing<- function finds any genotypes with the old missing data symbol and changes them to the new missing data symbol, then assigns the new symbol to the slot that indicates what the missing data symbol is. Present<- and Absent<- work similarly for the genbinary class.

The Genotype access and replacement functions deal with individual genotypes, which are vectors in the genambig class. The Genotypes access and replacement functions deal with lists of genotypes.

The PopInfo<- replacement function also adds elements to PopNames(object) if necessary in order to have names for all of the populations. These will be of the form "Pop" followed by the population number, and can be later edited using PopNames<-.

The PopNum<- replacement function first finds all samples in the population popname, and replaces the number in PopInfo(object) for those samples with value. It then inserts NA into the original PopNames slot that contained popname, and inserts popname into PopNames(object)[value]. If this results in two populations being merged into one, a message is printed to the console.

Value

PopInfo, PopNames, Missing, Description, Usatnts, Ploidies and Genotypes simply return the contents of the slots of the same names (or in the case of Ploidies, object@Ploidies@pld is returned). Samples and Loci return character vectors taken from the names of other slots (PopInfo and Usatnts, respectively; the initialization and replacement methods ensure that these slots are always named according to samples and loci). PopNum returns an integer vector indicating the population number(s) of the population(s) named in popname. Genotype returns a single genotype for a given sample and locus, which is a vector whose exact form will depend on the class of object.

Author(s)

Lindsay V. Clark

See Also

deleteSamples, deleteLoci, viewGenotypes, editGenotypes, isMissing, estimatePloidy, merge,gendata,gendata-method, gendata

Examples

# create a new genambig (subclass of gendata) object to manipulate
mygen <- new("genambig", samples=c("a", "b", "c"), loci=c("locG",
"locH"))

# retrieve the sample and locus names
Samples(mygen)
Loci(mygen)

# change some of the sample and locus names
Loci(mygen) <- c("lG", "lH")
Samples(mygen)[2] <- "b1"

# describe the dataset
Description(mygen) <- "Example dataset for documentation."

# name some populations and assign samples to them
PopNames(mygen) <- c("PopL", "PopK")
PopInfo(mygen) <- c(1,1,2)
# now we can retrieve samples by population
Samples(mygen, populations="PopL")
# we can also adjust the numbers if we want to make them
# match another dataset
PopNum(mygen, "PopK") <- 3
PopNames(mygen)
PopInfo(mygen)
# change the population identity of just one sample
PopInfo(mygen)["b1"] <- 3

# indicate that both loci are dinucleotide repeats
Usatnts(mygen) <- c(2,2)

# indicate that all samples are tetraploid
Ploidies(mygen) <- 4
# or
Ploidies(mygen) <- rep(4, times = length(Samples(mygen)) * length(Loci(mygen)))
# actually, one sample is triploid
Ploidies(mygen)["c",] <- 3
# view ploidies
Ploidies(mygen)

# view the genotype array as it currently is: filled with missing
# values
Genotypes(mygen)
# fill in the genotypes
Genotypes(mygen, loci="lG") <- list(c(120, 124, 130, 136), c(122, 120),
                                    c(128, 130, 134))
Genotypes(mygen, loci="lH") <- list(c(200, 202, 210), c(206, 208, 210,
                                                        214),
                                    c(208))
# genotypes can also be edited or retrieved by sample
Genotypes(mygen, samples="a")
# fix a single genotype
Genotype(mygen, "a", "lH") <- c(200, 204, 210)
# retrieve a single genotype
Genotype(mygen, "c", "lG")

# change a genotype to being missing
Genotype(mygen, "c", "lH") <- Missing(mygen)
# show the current missing data symbol
Missing(mygen)
# an example of genotypes where one contains the missing data symbol
Genotypes(mygen, samples="c")
# change the missing data symbol
Missing(mygen) <- as.integer(-1)
# now look at the genotypes
Genotypes(mygen, samples="c")

---

Assign Alleles to Isoloci Based on Distribution of Genotypes

Description

Where a single locus represents two or more independent isoloci (as in an allopolyploid, or a diploidized autopolyploid), these two functions can be used in sequence to assign alleles to isoloci. alleleCorrelations uses K-means and UPGMA clustering of pairwise p-values from Fisher's exact test to make initial groupings of alleles into putative isoloci. testAlGroups is then used to check those groupings against individual genotypes, and adjust the assignments if necessary.

Usage

alleleCorrelations(object, samples = Samples(object), locus = 1,
                   alpha = 0.05, n.subgen = 2, n.start = 50)

testAlGroups(object, fisherResults, SGploidy=2, samples=Samples(object),
             null.weight=0.5, tolerance=0.05, swap = TRUE,
             R = 100, rho = 0.95, T0 = 1, maxreps = 100)

Arguments

object	A "genambig" or "genbinary" object containing the data to analyze.
samples	An optional character or numeric vector indicating which samples to analyze.
locus	A single character string or integer indicating which locus to analyze.
alpha	The significance threshold, before multiple correction, for determining whether two alleles are significantly correlated.
n.subgen	The number of subgenomes (number of isoloci) for this locus. This would be 2 for an allotetraploid or 3] for an allohexaploid. For an allo-octoploid, the value would be 2 if there were two tetraploid subgenomes, or 4 if there were four diploid subgenomes.
n.start	Integer, passed directly to the nstart argument of the R base function kmeans. Lowering this number will speed up computation time, whereas increasing it will improve the probability of finding the correct allele assignments. The default value of 50 should work well in most cases.
fisherResults	A list output from alleleCorrelations.
SGploidy	The ploidy of each subgenome (each isolocus). This is 2 for an allotetraploid, an allohexaploid, or an allo-octoploid with four tetraploid subgenomes, or 4 for an allo-octoploid with two tetraploid genomes.
null.weight	Numeric, indicating how genotypes with potential null alleles should be counted when looking for signs of homoplasy. null.weight should be 0 if null alleles are expected to be common, and 1 if there are no null alleles in the dataset. The default of 0.5 was chosen to reflect the fact that the presence of null alleles is generally unknown.
tolerance	The proportion of genotypes that are allowed to be in disagreement with the allele assignments. This is the proportion of genotypes that are expected to have meiotic error or scoring error.
swap	Boolean indicating whether or not to use the allele swapping algorithm before checking for homoplasy. TRUE will yield more accurate results in most cases, but FALSE may be preferable for loci with null or homoplasious alleles at high frequency.
R	Simulated annealing parameter for the allele swapping algorithm. Indicates how many swaps to attempt in each rep (i.e. how many swaps to attempt before changing the temperature).
rho	Simulated annealing parameter for the allele swapping algorithm. Factor by which to reduce the temperature at the end of each rep.
T0	Simulated annealing parameter for the allele swapping algorithm. Starting temperature.
maxreps	Simulated annealing parameter for the allele swapping algorithm. Maximum number of reps if convergence is not achieved.

Details

These functions implement a novel methodology, introduced in polysat version 1.4 and updated in version 1.6, for cases where one pair of microsatellite primers amplifies alleles at two or more independently-segregating loci (referred to here as isoloci). This is not typically the case with new autopolyploids, in which all copies of a locus have equal chances of pairing with each other at meiosis. It is, however, frequently the case with allopolyploids, in which there are two homeologous subgenomes that do not pair (or infrequently pair) at meiosis, or ancient autopolyploids, in which duplicated chromosomes have diverged to the point of no longer pairing at meiosis.

Within the two functions there are four major steps:

1. alleleCorrelations checks to see if there are any alleles that are present in every genotype in the dataset. Such invariable alleles are assumed to be fixed at one isolocus (which is not necessarily true, but may be corrected by testAlGroups in steps 4 and 5). If present, each invariable allele is assigned to its own isolocus. If there are more invariable alleles than isoloci, the function throws an error. If only one isolocus remains, all remaining (variable) alleles are assigned to that isolocus. If there are as many invariable alleles as isoloci, all remaining (variable) alleles are assigned to all isoloci (i.e. they are considered homoplasious because they cannot be assigned).

2. If, after step 1, two or more isoloci remain without alleles assigned to them, correlations between alleles are tested by alleleCorrelations. The dataset is converted to "genbinary" if not already in that format, and a Fisher's exact test, with negative association (odds ratio being less than one) as the alternative hypothesis, is performed between each pair of columns (alleles) in the genotype matrix. The p-value of this test between each pair of alleles is stored in a square matrix, and zeros are inserted into the diagonal of the matrix. K-means clustering and UPGMA are then performed on the square matrix of p-values, and the clusters that are produced represent initial assignments of alleles to isoloci.

3. The output of alleleCorrelations is then passed to testAlGroups. If the results of K-means clustering and UPGMA were not identical, testAlGroups checks both sets of assignments against all genotypes in the dataset. For a genotype to be consistent with a set of assignments, it should have at least one allele and no more than SGploidy alleles belonging to each isolocus. The set of assignments that is consistent with the greatest number of genotypes is chosen, or in the case of a tie, the set of assignments produced by K-means clustering.

4. If swap = TRUE and the assignments chosen in the previous step are inconsistent with some genotypes, testAlGroups attempts to swap the isoloci of single alleles, using a simulated annealing (Bertsimas and Tsitsiklis 1993) algorithm to search for a new set of assignments that is consistent with as many genotypes as possible. At each step, an allele is chosen at random to be moved to a different isolocus (which is also chosen at random if there are more than two isoloci). If the new set of allele assignments is consistent with an equal or greater number of genotypes than the previous set of assignments, the new set is retained. If the new set is consistent with fewer genotypes than the old set, there is a small probability of retaining the new set, dependent on how much worse the new set of assignments is and what the current “temperature” of the algorithm is. After R allele swapping attempts, the temperature is lowered, reducing the probability of retaining a set of allele assignments that is worse than the previous set. A new rep of R swapping attempts then begins. If a set of allele assignments is found that is consistent with all genotypes, the algorithm stops immediately. Otherwise it stops if no changes are made during an entire rep of R swap attempts, or if maxreps reps are performed.

5. testAlGroups then checks through all genotypes to look for signs of homoplasy, meaning single alleles that should be assigned to more than one isolocus. For each genotype, there should be no more than SGploidy alleles assigned to each isolocus. Additionally, if there are no null alleles, each genotype should have at least one allele belonging to each isolocus. Each time a genotype is encountered that does not meet these criteria, the a score is increased for all alleles that might be homoplasious. (The second criterion is not checked if null.weight = 0.) This score starts at zero and is increased by 1 if there are too many alleles per isolocus or by null.weight if an isolocus has no alleles. Once all genotypes have been checked, the allele with the highest score is considered to be homoplasious and is added to the other isolocus. (In a hexaploid or higher, which isolocus the allele is added to depends on the genotypes that were found to be inconsistent with the allele assignments, and which isolocus or isoloci the allele could have belonged to in order to fix the assignment.) Allele scores are reset to zero and all alleles are then checked again with the new set of allele assignments. The process is repeated until the proportion of genotypes that are inconsistent with the allele assignments is at or below tolerance.

Value

Both functions return lists. For alleleCorrelations:

locus	The name of the locus that was analyzed.
clustering.method	The method that was ultimately used to produce value$Kmeans.groups and value$UPGMA.groups. Either "K-means and UPGMA" or "fixed alleles".
significant.neg	Square matrix of logical values indicating whether there was significant negative correlation between each pair of alleles, after multiple testing correction by Holm-Bonferroni.
significant.pos	Square matrix of logical values indicating whether there was significant positive correlation between each pair of alleles, after multiple testing correction by Holm-Bonferroni.
p.values.neg	Square matrix of p-values from Fisher's exact test for negative correlation between each pair of alleles.
p.values.pos	Square matrix of p-values from Fisher's exact test for positive correlation between each pair of alleles.
odds.ratio	Square matrix of the odds ratio estimate from Fisher's exact test for each pair of alleles.
Kmeans.groups	Matrix with n.subgen rows, and as many columns as there are alleles in the dataset. 1 indicates that a given allele belongs to a given isolocus, and 0 indicates that it does not. These are the groupings determined by K-means clustering.
UPGMA.groups	Matrix in the same format as value$Kmeans.groups, showing groupings determined by UPGMA.
heatmap.dist	Square matrix like value$p.values.neg but with zeros inserted on the diagonal. This is the matrix that was used for K-means clustering and UPGMA. This matrix can be passed to the heatmap function in R to visualize the clusters.
totss	Total sums of squares output from K-means clustering.
betweenss	Sums of squares between clusters output from K-means clustering. value$betweenss/value$totss can be used as an indication of clustering quality.
gentable	The table indicating presence/absence of each allele in each genotype.

For testAlGroups:

locus	Name of the locus that was tested.
SGploidy	The ploidy of each subgenome, taken from the SGploidy argument that was passed to testAlGroups.
assignments	Matrix with as many rows as there are isoloci, and as many columns as there are alleles in the dataset. 1 indicates that a given allele belongs to a given isolocus, and 0 indicates that it does not.
proportion.inconsistent.genotypes	A number ranging from zero to one indicating the proportion of genotypes from the dataset that are inconsistent with assignments.

Note

alleleCorrelations will print a warning to the console or to the standard output stream if a significant positive correlation is found between any pair of alleles. (This is not a “warning” in the technical sense usually used in R, because it can occur by random chance and I did not want it to cause polysat to fail package checks.) You can see which allele pair(s) caused this warning by looking at value$significant.pos. If you receive this warning for many loci, consider that there may be population structure in your dataset, and that you might split the dataset into multiple populations to test seperately. If it happens at just a few loci, check to make sure there are not scoring problems such as stutter peaks being miscalled as alleles. If it only happens at one locus and you can't find any evidence of scoring problems, two alleles may have been positively correlated simply from random chance, and the warning can be ignored.

alleleCorrelations can also produce an actual warning stating “Quick-TRANSfer stage steps exceeded maximum”. This warning is produced internally by kmeans and may occur if many genotypes are similar, as in mapping populations. It can be safely ignored.

Author(s)

Lindsay V. Clark

References

Clark, L. V. and Drauch Schreier, A. (2017) Resolving microsatellite genotype ambiguity in populations of allopolyploid and diploidized autopolyploid organisms using negative correlations between allelic variables. Molecular Ecology Resources, 17, 1090–1103. DOI: 10.1111/1755-0998.12639.

Bertsimas, D. and Tsitsiklis, J.(1993) Simulated annealing. Statistical Science 8, 10–15.

See Also

recodeAllopoly, mergeAlleleAssignments, catalanAlleles, processDatasetAllo

Examples

# randomly generate example data for an allotetraploid
mydata <- simAllopoly(n.alleles=c(5,5), n.homoplasy=1)
viewGenotypes(mydata)

# test allele correlations
# n.start is lowered in this example to speed up computation time
myCorr <- alleleCorrelations(mydata, n.subgen=2, n.start=10)
myCorr$Kmeans.groups
myCorr$clustering.method
if(!is.null(myCorr$heatmap.dist)) heatmap(myCorr$heatmap.dist)

# check individual genotypes 
# (low maxreps used in order to speed processing time for this example)
myRes <- testAlGroups(mydata, myCorr, SGploidy=2, maxreps = 5)
myRes$assignments
myRes2 <- testAlGroups(mydata, myCorr, SGploidy=2, swap = FALSE)
myRes2$assignments

---

Retrieve and Count Unique Alleles

Description

alleleDiversity returns the number of unique alleles and/or a list of vectors of all unique alleles, indexed by locus and population.

Usage

alleleDiversity(genobject, samples = Samples(genobject),
                loci = Loci(genobject), alleles = TRUE, counts = TRUE)

Arguments

genobject	An object of the class "genambig".
samples	Optional. A character or numeric vector indicating samples to include in the analysis.
loci	Optional. A character or numeric vector indicating loci to include in the analysis.
alleles	Boolean, indicating whether or not to return the alleles themselves.
counts	Boolean, indicating whether or not to return the number of unique alleles.

Value

Under default settings, a list is returned:

alleles	A two dimensional list. The first dimension is indexed by population, with the additional element “overall” representing the entire dataset. The second dimension is indexed by locus. Each element of the list is a vector, containing all unique alleles found for that population and locus. Missing(genobject) is not counted as an allele.
counts	A matrix, indexed in the same way as alleles. Each element of the matrix is an integer indicating how many alleles were found at that population and locus.

If the argument alleles or counts is set to FALSE, then only one of the above list elements is returned.

Author(s)

Lindsay V. Clark

See Also

genotypeDiversity

Examples

# generate a dataset for this example
mygen <- new("genambig", samples=c("a","b","c","d"), loci=c("E","F"))
PopInfo(mygen) <- c(1,1,2,2)
Genotypes(mygen, loci="E") <- list(c(122,132),c(122,124,140),
                                   c(124,130,132),c(132,136))
Genotypes(mygen, loci="F") <- list(c(97,99,111),c(113,115),
                                   c(99,113),c(111,115))

# look at unique alleles
myal <- alleleDiversity(mygen)
myal$counts
myal$alleles
myal$alleles[["Pop1","E"]]
myal$alleles[["overall","F"]]

---

Simulated Allotetraploid Data

Description

This is a simulated microsatellite dataset for seven loci and 303 individuals. It is intended to be used with the tutorial “Assigning alleles to isoloci in polysat”.

Usage

data("AllopolyTutorialData")

Format

A "genambig" object.

Examples

data(AllopolyTutorialData)
summary(AllopolyTutorialData)
viewGenotypes(AllopolyTutorialData, samples=1:10, loci=1)

---

Group Individuals Based on a Distance Threshold

Description

assignClones uses a distance matrix such as that produced by meandistance.matrix or meandistance.matrix2 to place individuals into groups representing asexually-related ramets, or any other grouping based on a distance threshold.

Usage

assignClones(d, samples = dimnames(d)[[1]], threshold = 0)

Arguments

d	A symmetrical, square matrix containing genetic distances between individuals. Both dimensions should be named according to the names of the individuals (samples). A matrix produced by meandistance.matrix or meandistance.matrix2 when all.distances = FALSE, or the matrix that is the second item in the list produced if all.distances = TRUE, will be in the right format. meandist.from.array will also produce a matrix in the correct format.
samples	A character vector containing the names of samples to analyze. This should be all or a subset of the names of d.
threshold	A number indicating the maximum distance between two individuals that will be placed into the same group.

Details

This function groups individuals very similarly to the software GenoType (Meirmans and van Tienderen, 2004). If a distance matrix from polysat is exported to GenoType, the results will be the same as those from assignClones assuming the same threshold is used. Note that GenoType requires that distances be integers rather than decimals, so you will have to multiply the distances produced by polysat by a large number and round them to the nearest integer if you wish to export them to GenoType. When comparing the results of assignClones and GenoType using my own data, the only differences I have seen have been the result of rounding; a decimal that was slightly above the threshold in when analyzed in R was rounded down to the threshold when analyzed in GenoType.

Note that when using a distance threshold of zero (the default), it is advisable to exclude all samples with missing data, in order to prevent the merging of non-identical clones. At higher thresholds, some missing data are allowable, but samples that have missing data at many loci should be excluded.

The write.table function can be used for exporting the results to GenoDive. See the R documentation for information on how to make a tab-delimited file with no header.

Value

A numeric vector, named by samples. Each clone or group is given a number, and the number for each sample indicates the clone or group to which it belongs.

Author(s)

Lindsay V. Clark

References

Meirmans, P. G. and Van Tienderen, P. H. (2004) GENOTYPE and GENODIVE: two programs for the analysis of genetic diversity of asexual organisms. Molecular Ecology Notes 4, 792–794.

See Also

genotypeDiversity

Examples

# set up a simple matrix with three samples
test <- matrix(c(0,0,.5,0,0,.5,.5,.5,0), ncol=3, nrow=3)
abc <- c("a", "b", "c")
dimnames(test) <- list(abc,abc)

# assign clones with a threshold of zero or 0.5
assignClones(test)
assignClones(test, threshold=0.5)

---

Genetic Distance Metric of Bruvo et al.

Description

This function calculates the distance between two individuals at one microsatellite locus using a method based on that of Bruvo et al. (2004).

Usage

Bruvo.distance(genotype1, genotype2, maxl=10, usatnt=2, missing=-9)

Arguments

genotype1	A vector of alleles for one individual at one locus. Allele length is in nucleotides or repeat count. Each unique allele corresponds to one element in the vector, and the vector is no longer than it needs to be to contain all unique alleles for this individual at this locus.
genotype2	A vector of alleles for another individual at the same locus.
maxl	If both individuals have more than this number of alleles at this locus, NA is returned instead of a numerical distance.
usatnt	Length of the repeat at this locus. For example usatnt=2 for dinucleotide repeats, and usatnt=3 for trinucleotide repeats. If the alleles in genotype1 and genotype2 are expressed in repeat count instead of nucleotides, set usatnt=1.
missing	A numerical value that, when in the first allele position, indicates missing data. NA is returned if this value is found in either genotype.

Details

Since allele copy number is frequently unknown in polyploid microsatellite data, Bruvo et al. developed a measure of genetic distance similar to band-sharing indices used with dominant data, but taking into account mutational distances between alleles. A matrix is created containing all differences in repeat count between the alleles of two individuals at one locus. These differences are then geometrically transformed to reflect the probabilities of mutation from one allele to another. The matrix is then searched to find the minimum sum if each allele from one individual is paired to one allele from the other individual. This sum is divided by the number of alleles per individual.

If one genotype has more alleles than the other, ‘virtual alleles’ must be created so that both genotypes are the same length. There are three options for the value of these virtual alleles, but Bruvo.distance only implements the simplest one, assuming that it is not known whether differences in ploidy arose from genome addition or genome loss. Virtual alleles are set to infinity, such that the geometric distance between any allele and a virtual allele is 1.

In the original publication by Bruvo et al. (2004), ambiguous genotypes were dealt with by calculating the distance for all possible unambiguous genotype combinations and averaging across all of them equally. When Bruvo.distance is called from meandistance.matrix, ploidy is unknown and all genotypes are simply treated as if they had one copy of each allele. When Bruvo.distance is called from meandistance.matrix2, the analysis is truer to the original, in that ploidy is known and all possible unambiguous genotype combinations are considered. However, instead of all possible unambiguous genotypes being weighted equally, in meandistance.matrix2 they are weighted based on allele frequencies and selfing rate, since some unambiguous genotypes are more likely than others.

Value

A number ranging from 0 to 1, with 0 indicating identical genotypes, and 1 being a theoretical maximum distance if all alleles from genotype1 differed by an infinite number of repeats from all alleles in genotype2. NA is returned if both genotypes have more than maxl alleles or if either genotype has the symbol for missing data as its first allele.

Note

The processing time is a function of the factorial of the number of alleles, since each possible combination of allele pairs must be evaluated. For genotypes with a sufficiently large number of alleles, it may be more efficient to estimate distances manually by creating the matrix in Excel and visually picking out the shortest distances between alleles. This is the purpose of the maxl argument. On my personal computer, if both genotypes had more than nine alleles, the calculation could take an hour or more, and so this is the default limit. In this case, Bruvo.distance returns NA.

Author(s)

Lindsay V. Clark

References

Bruvo, R., Michiels, N. K., D'Sousa, T. G., and Schulenberg, H. (2004) A simple method for calculation of microsatellite genotypes irrespective of ploidy level. Molecular Ecology 13, 2101-2106.

See Also

meandistance.matrix, Lynch.distance, Bruvo2.distance

Examples

Bruvo.distance(c(202,206,210,220),c(204,206,216,222))
  Bruvo.distance(c(202,206,210,220),c(204,206,216,222),usatnt=4)
  Bruvo.distance(c(202,206,210,220),c(204,206,222))
  Bruvo.distance(c(202,206,210,220),c(204,206,216,222),maxl=3)
  Bruvo.distance(c(202,206,210,220),c(-9))

---

Distance Measure of Bruvo et al. under Genome Loss and Addition

Description

This is an inter-individual distance measure similar to Bruvo.distance, except that where genotypes have different numbers of alleles, virtual alleles are equal to those from the longer and/or shorter genotype, rather than being equal to infinity.

Usage

Bruvo2.distance(genotype1, genotype2, maxl = 7, usatnt = 2,
                missing = -9, add = TRUE, loss = TRUE)

Arguments

genotype1	A numeric vector representing the genotype of one individual at one locus. This type of vector is produced by the Genotype method for "genambig" objects.
genotype2	The second genotype for the distance calculation, in the same format as genotype1.
maxl	The maximum number of alleles that either genotype can have. If it is exceeded, NA is returned. This argument exists to prevent computations that would take in excess of an hour; see Bruvo.distance.
usatnt	The microsatellite repeat type for the locus. 2 for dinucleotide repeats, 3 for dinucleotide repeats, 1 if the alleles are already coded as repeat numbers, etc. See Usatnts.
missing	The symbol that indicates missing data for a given sample and locus. See Missing.
add	TRUE if the model of genome addition is being used, and FALSE if it is not. If this model is used, the shorter genotype will have virtual alleles added from the same genotype.
loss	TRUE if the model of genome loss is being used, and FALSE if it is not. If this model is used, the shorter genotype will have virtual alleles added from the longer genotype.

Details

Bruvo et al. (2004) describe multiple methods for calculating genetic distances between individuals of different ploidy. (See “Special cases” starting on page 2102 of the paper.) The original Bruvo.distance function in polysat uses the method described for systems with complex changes in ploidy, adding virtual alleles equal to infinity to the shorter genotype to make it the same length as the longer genotype. This method, however, can exaggerate distances between individuals of different ploidy, particularly when used with meandistance.matrix2 as opposed to meandistance.matrix.

Bruvo2.distance calculates distances between individuals under the models of genome addition and genome loss. If add = TRUE and loss = TRUE, the distance produced is equal to that of equation 6 in the paper.

If add = TRUE and loss = FALSE, the distance calculated is that under genome addition only. Likewise if add = FALSE and loss = TRUE the distance is calculated under genome loss only. The latter distance should be greater than the former. If both were averaged together, they would give the identical result to that produced when add = TRUE and loss = TRUE. All three distances will be less than that produced by Bruvo.distance.

If both genotypes have the same number of alleles, they are passed to Bruvo.distance for the calculation. This also happens if add = FALSE and loss = FALSE. Otherwise, if the genotypes have different numbers of alleles, all possible genotypes with virtual alleles are enumerated and passed to Bruvo.distance one by one, and the results averaged.

The number of different genotypes simulated under genome loss or genome addition is $l^d$, where $l$ is the length of the genotype from which virtual alleles are being taken, and $d$ is the difference in length between the longer and shorter genotype. For example, under genome addition for a diploid individual with alleles 1 and 2 being compared to a tetraploid individual, the genotypes 1211, 1212, 1221, and 1222 will each be used once to represent the diploid individual.

Value

A decimal between 0 and 1, with 0 indicating complete identity of two genotypes, and 1 indicating maximum dissimilarity. NA is returned if one or both genotypes are missing or if maxl is exceeded.

Note

Figure 1B and 1C of Bruvo et al. (2004) illustrate an example of this distance measure. To perform the identical calculation to that listed directly under equation 6, you would type:

Bruvo2.distance(c(20,23,24), c(20,24,26,43), usatnt=1)

However, you will notice that the result, 0.401, is slightly different from that given in the paper. This is due to an error in the paper. For the distance under genome loss when the virtual allele is 26, the result should be 1 instead of 1.75.

Author(s)

Lindsay V. Clark

References

Bruvo, R., Michiels, N. K., D'Sousa, T. G., and Schulenberg, H. (2004) A simple method for calculation of microsatellite genotypes irrespective of ploidy level. Molecular Ecology 13, 2101–2106.

See Also

Lynch.distance, Bruvo.distance, meandistance.matrix2

Examples

Bruvo2.distance(c(102,104), c(104,104,106,110))
Bruvo2.distance(c(102,104), c(104,104,106,110), add = FALSE)
Bruvo2.distance(c(102,104), c(104,104,106,110), loss = FALSE)

---

Estimate Population Differentiation Statistics

Description

Given a data frame of allele frequencies and population sizes, calcPopDiff calculates a matrix of pairwise $F_{ST}$, $G_{ST}$, Jost's $D$, or $R_{ST}$ values, or a single global value for any of these four statistics. calcFst is a wrapper for calcPopDiff to allow backwards compatibility with previous versions of polysat.

Usage

calcPopDiff(freqs, metric, pops = row.names(freqs), 
            loci = unique(gsub("\\..*$", "", names(freqs))), global = FALSE,
            bootstrap = FALSE, n.bootstraps = 1000, object = NULL)

calcFst(freqs, pops = row.names(freqs),
        loci = unique(gsub("\\..*$", "", names(freqs))), ...)

Arguments

freqs	A data frame of allele frequencies and population sizes such as that produced by simpleFreq or deSilvaFreq. Each population is in one row, and a column called Genomes (or multiple columns containing the locus names and “Genomes” seperated by a period) contains the relative size of each population. All other columns contain allele frequencies. The names of these columns are the locus name and allele name, separated by a period.
metric	The population differentiation statistic to estimate. Can be “Fst”, “Gst”, “Jost's D”, or “Rst”.
pops	A character vector. Populations to analyze, which should be a subset of row.names(freqs).
loci	A character vector indicating which loci to analyze. These should be a subset of the locus names as used in the column names of freqs.
global	Boolean. If TRUE, a single global statistic will be estimated across all populations. If FALSE, pairwise statistics will be estimated between populations.
bootstrap	Boolean. If TRUE, a set of replicates bootstrapped across loci will be returned. If FALSE, a single value will be returned for each pair of populations (if global = FALSE) or for the whole set (if global = TRUE).
n.bootstraps	Integer. The number of bootstrap replicates to perform. Ignored if bootstrap = FALSE.
object	A "genambig" or "genbinary" object with the Usatnts slot filled in. Required for metric = "Rst" only.
...	Additional arguments to be passed to calcPopDiff (i.e. global, bootstrap, and/or n.bootstraps).

Details

For metric = "Fst" or calcFst:

$H_S$ and $H_T$ are estimate directly from allele frequencies for each locus for each pair of populations, then averaged across loci. Wright's $F_{ST}$ is then calculated for each pair of populations as $\frac{H_T - H_S}{H_T}$.

$H$ values (expected heterozygosities for populations and combined populations) are calculated as one minus the sum of all squared allele frequencies at a locus. To calculte $H_T$, allele frequencies between two populations are averaged before the calculation. To calculate $H_S$, $H$ values are averaged after the calculation. In both cases, the averages are weighted by the relative sizes of the two populations (as indicated by freqs$Genomes).

For metric = "Gst":

This metric is similar to $F_{ST}$, but mean allele frequencies and mean expected heterozygosities are not weighted by population size. Additionally, unbiased estimators of $H_S$ and $H_T$ are used according to Nei and Chesser (1983; equations 15 and 16, reproduced also in Jost (2008)). Instead of using twice the harmonic mean of the number of individuals in the two subpopulations as described by Nei and Chesser (1983), the harmonic mean of the number of allele copies in the two subpopulations (taken from freq$Genomes) is used, in order to allow for polyploidy. $G_{ST}$ is estimated for each locus and then averaged across loci.

For metric = "Jost's D":

The unbiased estimators of $H_S$ and $H_T$ and calculated as with $G_{ST}$, without weighting by population size. They are then used to estimate $D$ at each locus according to Jost (2008; equation 12):

$2 * \frac{H_T - H_S}{1 - H_S}$

Values of $D$ are then averaged across loci.

For metric = "Rst":

$R_{ST}$ is estimated on a per-locus basis according to Slatkin (1995), but with populations weighted equally regardless of size. Values are then averaged across loci.

For each locus:

$S_w = \frac{1}{d} * \sum_j^d{\frac{\sum_i{\sum_{i' < i}{p_{ij} * p_{i'j} * n_j^2 * (a_i - a_{i'})^2}}}{n_j * (n_j - 1)}}$

$\bar{S} = \frac{\sum_i{\sum_{i' < i}{\bar{p}_i * \bar{p}_{i'} * n^2 * (a_i - a_{i'})^2}}}{n * (n-1)}$

$R_{ST} = \frac{\bar{S} - S_w}{\bar{S}}$

where $d$ is the number of populations, $j$ is an individual population, $i$ and $i'$ are individual alleles, $p_{ij}$ is the frequency of an allele in a population, $n_j$ is the number of allele copies in a population, $a_i$ is the size of an allele expressed in number of repeat units, $\bar{p}_i$ is an allele frequency averaged across populations (with populations weighted equally), and $n$ is the total number of allele copies across all populations.

Value

If global = FALSE and bootstrap = FALSE, a square matrix containing $F_{ST}$, $G_{ST}$, $D$, or $R_{ST}$ values. The rows and columns of the matrix are both named by population.

If global = TRUE and bootstrap = FALSE, a single value indicating the $F_{ST}$, $G_{ST}$, $D$, or $R_{ST}$ value.

If global = TRUE and bootstrap = TRUE, a vector of bootstrapped replicates of $F_{ST}$, $G_{ST}$, $D$, or $R_{ST}$.

If global = FALSE and bootstrap = TRUE, a square two-dimensional list, with rows and columns named by population. Each item is a vector of bootstrapped values for $F_{ST}$, $G_{ST}$, $D$, or $R_{ST}$ for that pair of populations.

Author(s)

Lindsay V. Clark

References

Nei, M. (1973) Analysis of gene diversity in subdivided populations. Proceedings of the National Academy of Sciences of the United States of America 70, 3321–3323.

Nei, M. and Chesser, R. (1983) Estimation of fixation indices and gene diversities. Annals of Human Genetics 47, 253–259.

Jost, L. (2008) $G_{ST}$ and its relatives to not measure differentiation. Molecular Ecology 17, 4015–4026.

Slatkin, M. (1995) A measure of population subdivision based on microsatellite allele frequencies. Genetics 139, 457–462.

See Also

simpleFreq, deSilvaFreq

Examples

# create a data set (typically done by reading files)
mygenotypes <- new("genambig", samples = paste("ind", 1:6, sep=""),
                   loci = c("loc1", "loc2"))
Genotypes(mygenotypes, loci = "loc1") <- list(c(206), c(208,210),
                                              c(204,206,210),
    c(196,198,202,208), c(196,200), c(198,200,202,204))
Genotypes(mygenotypes, loci = "loc2") <- list(c(130,134), c(138,140),
                                              c(130,136,140),
    c(138), c(136,140), c(130,132,136))
PopInfo(mygenotypes) <- c(1,1,1,2,2,2)
mygenotypes <- reformatPloidies(mygenotypes, output="sample")
Ploidies(mygenotypes) <- c(2,2,4,4,2,4)
Usatnts(mygenotypes) <- c(2,2)

# calculate allele frequencies
myfreq <- simpleFreq(mygenotypes)

# calculate pairwise differentiation statistics
myfst <- calcPopDiff(myfreq, metric = "Fst")
mygst <- calcPopDiff(myfreq, metric = "Gst")
myD <- calcPopDiff(myfreq, metric = "Jost's D")
myrst <- calcPopDiff(myfreq, metric = "Rst", object = mygenotypes)

# examine the results
myfst
mygst
myD
myrst

# get global statistics
calcPopDiff(myfreq, metric = "Fst", global = TRUE)
calcPopDiff(myfreq, metric = "Gst", global = TRUE)
calcPopDiff(myfreq, metric = "Jost's D", global = TRUE)
calcPopDiff(myfreq, metric = "Rst", global = TRUE, object = mygenotypes)

---

Sort Alleles into Isoloci

Description

catalanAlleles uses genotypes present in a "genambig" object to sort alleles from one locus into two or more isoloci in an allopolyploid or diploidized autopolyploid species. Alleles are determined to belong to different isoloci if they are both present in a fully homozygous genotype. If necessary, heterozygous genotypes are also examined to resolve remaining alleles.

Usage

catalanAlleles(object, samples = Samples(object), locus = 1,
               n.subgen = 2, SGploidy = 2, verbose = FALSE)

Arguments

object	A "genambig" object containing the dataset to analyze. All individuals should be the same ploidy, although the function does not access the Ploidies slot. Missing data are allowed. For the locus to be examined, no genotype should have fewer than n.subgen alleles or more than n.subgen*SGploidy alleles.
samples	Optional argument indicating samples to be analyzed. Can be integer or character, as with other polysat functions.
locus	An integer or character string indicating which locus to analyze. Cannot be a vector greater than length 1. (The function will only analyze one locus at a time.)
n.subgen	The number of isoloci (number of subgenomes). For example, 2 for an allotetraploid, and 3 for an allohexaploid (three diploid genomes).
SGploidy	The ploidy of each genome. Only one value is allowed; all genomes must be the same ploidy. 2 indicates that each subgenome is diploid (as in an allotetraploid, or an allohexaploid with three diploid genomes).
verbose	Boolean. Indicates whether results, and if applicable, problematic genotypes, should be printed to the console.

Details

catalanAlleles implements and extends an approach used by Catalan et al. (2006) that sorts alleles from a duplicated microsatellite locus into two or more isoloci (homeologous loci on different subgenomes). First, fully homozygous genotypes are identified and used in analysis. If a genotype has as many alleles as there are subgenomes (for example, a genotype with two alleles in an allotetraploid species), it is assumed to be fully homozygous and the alleles are assumed to belong to different subgenomes. If some alleles remain unassigned after examination of all fully homozygous genotypes, heterozygous genotypes are also examined to attempt to assign those remaining alleles.

For example, in an allotetraploid, if a genotype contains one unassigned allele, and all other alleles in the genotype are known to belong to one isolocus, the unassigned allele can be assigned to the other isolocus. Or, if two alleles in a genotype belong to one isolocus, one allele belongs to the other isolocus, and one allele is unassigned, the unassigned allele can be assigned to the latter isolocus. The function follows such logic (which can be extended to higher ploidies) until all alleles can be assigned, or returns a text string saying that the allele assignments were unresolvable.

It is important to note that this method assumes no null alleles and no homoplasy across isoloci. If the function encounters evidence of either it will not return allele assignments. Null alleles and homoplasy are real possibilities in any dataset, which means that this method simply will not work for some microsatellite loci.

(Null alleles are those that do not produce a PCR amplicon, usually because of a mutation in the primer binding site. Alleles that exhibit homoplasy are those that produce amplicons of the same size, despite not being identical by descent. Specifically, homoplasy between alleles from different isoloci will interfere with the Catalan method of allele assignment.)

Value

A list containing the following items:

locus	A character string giving the name of the locus.
SGploidy	A number giving the ploidy of each subgenome. Identical to the SGploidy argument.
assignments	If assignments cannot be made, a character string describing the problem. Otherwise, a matrix with n.subgen rows and a labeled column for each allele, with a 1 if the allele belongs to that subgenome and a 0 if it does not.

Note

Aside from homoplasy and null alleles, stochastic effects may prevent the minimum combination of genotypes needed to resolve all alleles from being present in the dataset. For a typical allotetraploid dataset, 50 to 100 samples will be needed, whereas an allohexaploid dataset may require over 100 samples. In simulations, allo-octoploid datasets with two tetraploid genomes were unresolvable even with 10,000 samples due to the low probability of finding full homozygotes. Additionally, loci are less likely to be resolvable if they have many alleles or if one isolocus is monomorphic.

Although determination of allele copy number by is not needed (or expected) for catalanAlleles as it was in the originally published Catalan method, it is still very important that the genotypes be high quality. Even a single scoring error can cause the method to fail, including allelic dropout, contamination between samples, stutter peaks miscalled as alleles, and PCR artifacts miscalled as alleles. Poor quality loci (those that require some “artistic” interpretation of gels or electropherograms) are unlikely to work with this method. Individual genotypes that are of questionable quality should be discarded before running the function.

Author(s)

Lindsay V. Clark

References

Catalan, P., Segarra-Moragues, J. G., Palop-Esteban, M., Moreno, C. and Gonzalez-Candelas, F. (2006) A Bayesian approach for discriminating among alternative inheritance hypotheses in plant polyploids: the allotetraploid origin of genus Borderea (Dioscoreaceae). Genetics 172, 1939–1953.

See Also

alleleCorrelations, mergeAlleleAssignments, recodeAllopoly, simAllopoly

Examples

# make the default simulated allotetraploid dataset
mydata <- simAllopoly()

# resolve the alleles
myassign <- catalanAlleles(mydata)

---

Remove Samples or Loci from an Object

Description

These functions remove samples or loci from all relevant slots of an object.

Usage

deleteSamples(object, samples)
deleteLoci(object, loci)

Arguments

object	An object containing the dataset of interest. Generally an object of some subclass of gendata.
samples	A numerical or character vector of samples to be removed.
loci	A numerical or character vector of loci to be removed.

Details

These are generic functions with methods for genambig, genbinary, and gendata objects. The methods for the subclasses remove samples or loci from the @Genotypes slot, then pass the object to the method for gendata, which removes samples or loci from the @PopInfo, @Ploidies, and/or @Usatnts slots, as appropriate. The @PopNames slot is left untouched even if an entire population is deleted, in order to preserve the connection between the numbers in @PopInfo and the names in @PopNames.

If your intent is to experiment with excluding samples or loci, it may be a better idea to create character vectors of samples and loci that you want to use and then use these vectors as the samples and loci arguments for analysis or export functions.

Value

An object identical to object, but with the specified samples or loci removed.

Note

These functions are somewhat redundant with the subscripting function "[", which also works for all gendata objects. However, they may be more convenient depending on whether the user prefers to specify the samples and loci to use or to exclude.

Author(s)

Lindsay V. Clark

See Also

Samples, Loci, merge,gendata,gendata-method

Examples

# set up genambig object
mygen <- new("genambig", samples = c("ind1", "ind2", "ind3", "ind4"),
             loci = c("locA", "locB", "locC", "locD"))

# delete a sample
Samples(mygen)
mygen <- deleteSamples(mygen, "ind1")
Samples(mygen)

# delete some loci
Loci(mygen)
mygen <- deleteLoci(mygen, c("locB", "locC"))
Loci(mygen)

---

Estimate Allele Frequencies with EM Algorithm

Description

This function uses the method of De Silva et al. (2005) to estimate allele frequencies under polysomic inheritance with a known selfing rate.

Usage

deSilvaFreq(object, self, samples = Samples(object),
            loci = Loci(object), initNull = 0.15,
            initFreq = simpleFreq(object[samples, loci]),
            tol = 1e-08, maxiter = 1e4)

Arguments

object	A "genambig" or "genbinary" object containing the dataset of interest. All ploidies for samples and loci should be the same, and this should be an even number. PopInfo must also be filled in for samples.
self	A number between 1 and 0, indicating the rate of selfing.
samples	An optional character vector indicating a subset of samples to use in the calculation.
loci	An optional character vector indicating a subset of loci for which to calculate allele frequencies.
initNull	A single value or numeric vector indicating initial frequencies to use for the null allele at each locus.
initFreq	A data frame containing allele frequencies (for non-null loci) to use for initialization. This needs to be in the same format as the output of simpleFreq with a single “Genomes” column (similarly to the format of the output of deSilvaFreq). By default, the function will do a quick estimation of allele frequencies using simpleFreq and then initialize the EM algorithm at these frequencies.
tol	The tolerance level for determining when the results have converged. Where p2 and p1 are the current and previous vectors of allele frequencies, respectively, the EM algorithm stops if sum(abs(p2-p1)/(p2+p1)) <= tol.
maxiter	The maximum number of iterations that will be performed for each locus and population.

Details

Most of the SAS code from the supplementary material of De Silva et al. (2005) is translated directly into the R code for this function. The SIMSAMPLE (or CreateRandomSample in the SAS code) function is omitted so that the actual allelic phenotypes from the dataset can be used instead of simulated phenotypes. deSilvaFreq loops through each locus and population, and in each loop tallies the number of alleles and sets up matrices using GENLIST, PHENLIST, RANMUL, SELFMAT, and CONVMAT as described in the paper. Frequencies of each allelic phenotype are then tallied across all samples in that population with non-missing data at the locus. Initial allele frequencies for that population and locus are then extraced from initFreq and adjusted according to initNull. The EM iteration then begins for that population and locus, as described in the paper (EXPECTATION, GPROBS, and MAXIMISATION).

Each repetition of the EM algorithm includes an expectation and maximization step. The expectation step uses allele frequencies and the selfing rate to calculate expected genotype frequencies, then uses observed phenotype frequencies and expected genotype frequencies to estimate genotype frequencies for the population. The maximization step uses the estimated genotype frequencies to calculate a new set of allele frequencies. The process is repeated until allele frequencies converge.

In addition to returning a data frame of allele frequencies, deSilvaFreq also prints to the console the number of EM repetitions used for each population and locus. When each locus and each population is begun, a message is printed to the console so that the user can monitor the progress of the computation.

Value

A data frame containing the estimated allele frequencies. The row names are population names from PopNames(object). The first column shows how many genomes each population has. All other columns represent alleles (including one null allele per locus). These column names are the locus name and allele name separated by a period.

Note

It is possible to exceed memory limits for R if a locus has too many alleles in a population (e.g. 15 alleles in a tetraploid if the memory limit is 1535 Mb, see memory.limit).

De Silva et al. mention that their estimation method could be extended to the case of disomic inheritence. A method for disomic inheritence is not implemented here, as it would require knowledge of which alleles belong to which isoloci.

De Silva et al. also suggest a means of estimating the selfing rate with a least-squares method. Using the notation in the source code, this would be:

lsq <- smatt %*% EP - rvec

self <- as.vector((t(EP - rvec) %*% lsq)/(t(lsq) %*% lsq))

However, in my experimentation with this calculation, it sometimes yields selfing rates greater than one. For this reason, it is not implemented here.

Author(s)

Lindsay V. Clark

References

De Silva, H. N., Hall, A. J., Rikkerink, E., and Fraser, L. G. (2005) Estimation of allele frequencies in polyploids under certain patterns of inheritance. Heredity 95, 327–334

See Also

simpleFreq, write.freq.SPAGeDi, GENLIST

Examples

## Not run: 
## An example with a long run time due to the number of alleles

# create a dataset for this example
mygen <- new("genambig", samples=c(paste("A", 1:100, sep=""),
                                   paste("B", 1:100, sep="")),
             loci=c("loc1", "loc2"))
PopNames(mygen) <- c("PopA", "PopB")
PopInfo(mygen) <- c(rep(1, 100), rep(2, 100))
mygen <- reformatPloidies(mygen, output="one")
Ploidies(mygen) <- 4
Usatnts(mygen) <- c(2, 2)
Description(mygen) <- "An example for allele frequency calculation."

# create some genotypes at random for this example
for(s in Samples(mygen)){
    Genotype(mygen, s, "loc1") <- sample(seq(120, 140, by=2),
                                         sample(1:4, 1))
}
for(s in Samples(mygen)){
    Genotype(mygen, s, "loc2") <- sample(seq(130, 156, by=2),
                                         sample(1:4, 1))
}
# make one genotype missing
Genotype(mygen, "B4", "loc2") <- Missing(mygen)

# view the dataset
summary(mygen)
viewGenotypes(mygen)

# calculate the allele frequencies if the rate of selfing is 0.2
myfrequencies <- deSilvaFreq(mygen, self=0.2)

# view the results
myfrequencies

## End(Not run)

## An example with a shorter run time, for checking that the funciton
## is working.  Genotype simulation is also a bit more realistic here.

# Create a dataset for the example.
mygen <- new("genambig", samples=paste("A", 1:100, sep=""), loci="loc1")
PopNames(mygen) <- "PopA"
PopInfo(mygen) <- rep(1, 100)
mygen <- reformatPloidies(mygen, output="one")
Ploidies(mygen) <- 4
Usatnts(mygen) <- 2
for(s in Samples(mygen)){
    alleles <- unique(sample(c(122,124,126,0), 4, replace=TRUE,
                             prob = c(0.3, 0.2, 0.4, 0.1)))
    Genotype(mygen, s, "loc1") <- alleles[alleles != 0]
    if(length(Genotype(mygen, s, "loc1"))==0)
        Genotype(mygen, s, "loc1") <- Missing(mygen)
}

# We have created a random mating populations with four alleles
# including one null.  The allele frequencies are given in the
# 'prob' argument.

# Estimate allele frequencies
myfreq <- deSilvaFreq(mygen, self=0.01)
myfreq

---

Edit Genotypes Using the Data Editor

Description

The genotypes from an object of one of the subclasses of gendata are converted to a data frame (if necessary), then displayed in the data editor. After the user makes the desired edits and closes the data editor window, the new genotypes are written to the gendata object and the object is returned.

Usage

editGenotypes(object, maxalleles = max(Ploidies(object)),
              samples = Samples(object), loci = Loci(object))

Arguments

object	An object of the class genambig or genbinary. Contains the genotypes to be edited.
maxalleles	Numeric. The maximum number of alleles found in any given genotype. The method for genambig requires this information in order to determine how many columns to put in the data frame.
samples	Character or numeric vector indicating which samples to edit.
loci	Character or numeric vector indicating which loci to edit.

Details

The method for genambig lists sample and locus names in each row in order to identify the genotypes. However, only the alleles themselves should be edited. NA values and duplicate alleles in the data editor will be omitted from the genotype vectors that are written back to the genambig object.

Value

An object identical to object but with edited genotypes.

Author(s)

Lindsay V. Clark

See Also

viewGenotypes, Genotype<-, Genotypes<-

Examples

if(interactive()){  #this line included for automated checking on CRAN

# set up "genambig" object to edit
mygen <- new("genambig", samples = c("a", "b", "c"),
             loci = c("loc1", "loc2"))
Genotypes(mygen, loci="loc1") <- list(c(133, 139, 142),
                                      c(130, 136, 139, 145),
                                      c(136, 142))
Genotypes(mygen, loci="loc2") <- list(c(202, 204), Missing(mygen),
                                      c(200, 206, 208))
mygen <- reformatPloidies(mygen, output="one")
Ploidies(mygen) <- 4

# open up the data editor
mygen <- editGenotypes(mygen)

# view the results of your edits
viewGenotypes(mygen)

}

---

Estimate Ploidies Based on Allele Counts

Description

estimatePloidy calculates the maximum and mean number of unique alleles for each sample across a given set of loci. These values are presented in a data editor, along with other pertinent information, so that the user can then edit the ploidy values for the object.

Usage

estimatePloidy(object, extrainfo, samples = Samples(object), 
               loci = Loci(object))

Arguments

object	The object containing genotype data, and to which ploidies will be written.
extrainfo	A named or unnamed vector or data frame containing extra information (such as morphological or flow cytometry data) to display in the data editor, to assist with making decisions about ploidy. If unnamed, the vector (or the rows of the data frame) is assumed to be in the same order as samples. An array can also be given as an argument here, and will be coerced to a data frame.
samples	A numeric or character vector indicating a subset of samples to evaluate.
loci	A numeric or character vector indicating a subset of loci to use in the calculation of mean and maximum allele number.

Details

estimatePloidy is a generic function with methods written for the genambig and genbinary classes.

If the Ploidies slot of object is not already a "ploidysample" object, the function will first convert the Ploidies slot to this format, deleting any data that is currently there. (Ploidies must be indexed by sample and not by locus.) If ploidies were already in the "ploidysample" format, any ploidy data already in the object is retained and put into the table (see below).

Population identities are displayed in the table only if more than one population identity is found in the dataset. Likewise, the current ploidies of the dataset are only displayed if there is more than one ploidy level already found in Ploidies(object).

Missing genotypes are ignored; maximum and mean allele counts are only calculted across genotypes that are not missing. If all genotypes for a given sample are missing, NA is displayed in the corresponding cells in the data editor.

The default values for new.ploidy are the maximum number of alleles per locus for each sample.

Value

object is returned, with Ploidies(object) now equal to the values set in the new.ploidy column of the data editor.

Author(s)

Lindsay V. Clark

See Also

genambig, genbinary, Ploidies

Examples

if(interactive()){ #this line included for automated checking on CRAN

# create a dataset for this example
mygen <- new("genambig", samples=c("a", "b", "c"),
             loci=c("loc1", "loc2"))
Genotypes(mygen, loci="loc1") <- list(c(122, 126, 128), c(124, 130),
                                      c(120, 122, 124))
Genotypes(mygen, loci="loc2") <- list(c(140, 148), c(144, 150), Missing(mygen))

# estimate the ploidies
mygen <- estimatePloidy(mygen)

# view the ploidies
Ploidies(mygen)

}

---

Additional Data on Rubus Samples

Description

For 20 Rubus samples, contains colors and symbols to use for plotting data.

Usage

data(FCRinfo)

Format

Data frame. FCRinfo$Plot.color contains character strings of the colors to be used to represent species groups. FCR.info$Plot.symbol contains integers to be passed to pch to designate the symbol used to represent each individual. These reflect chloroplast haplotypes.

Source

Clark, L. V. and Jasieniuk, M. (2012) Spontaneous hybrids between native and exotic Rubus in the Western United States produce offspring both by apomixis and by sexual recombination. Heredity 109, 320–328. Data available at: doi:10.5061/dryad.m466f

See Also

testgenotypes

---

Find Missing Genotypes

Description

This function returns a data frame listing the locus and sample names of all genotypes with missing data.

Usage

find.missing.gen(object, samples = Samples(object),
                 loci = Loci(object))

Arguments

object	A genambig or genbinary object containing the genotypes of interest.
samples	A character vector of all samples to be searched. Must be a subset of Samples(object).
loci	A character vector of all loci to be searched. Must be a subset of Loci(object).

Value

A data frame with no row names. The first column is named “Locus” and the second column is named “Sample”. Each row represents one missing genotype, and gives the locus and sample of that genotype.

Author(s)

Lindsay V. Clark

See Also

isMissing

Examples

# set up the genotype data
samples <- paste("ind", 1:4, sep="")
samples
loci <- paste("loc", 1:3, sep="")
loci
testgen <- new("genambig", samples = samples, loci = loci)
Genotypes(testgen, loci="loc1") <- list(c(-9), c(102,104),
                                        c(100,106,108,110,114),
                                        c(102,104,106,110,112))
Genotypes(testgen, loci="loc2") <- list(c(77,79,83), c(79,85), c(-9),
                                        c(83,85,87,91))
Genotypes(testgen, loci="loc3") <- list(c(122,128), c(124,126,128,132),
                                        c(120,126), c(124,128,130))

# look up which samples*loci have missing genotypes
find.missing.gen(testgen)

---

Convert Allele Frequencies for Adegenet

Description

Given a data frame of allele frequencies such as that produced by simpleFreq or deSilvaFreq, freq.to.genpop creates a data frame of allele counts that can be read by the as.genpop function in the package adegenet.

Usage

freq.to.genpop(freqs, pops = row.names(freqs),
               loci =
                unique(as.matrix(as.data.frame(strsplit(names(freqs),
                split = ".", fixed = TRUE), stringsAsFactors = FALSE))[1, ]))

Arguments

freqs	A data frame of allele frequencies. Row names are population names. The first column is called "Genomes" and indicates the size of each population in terms of number of haploid genomes. All other column names are the locus and allele separated by a period. These columns contain the frequencies of each allele in each population. For each locus and population, all frequencies should total to 1.
pops	An optional character vector indicating the names of populations to use.
loci	An optional character vector indicating the names of loci to use.

Details

adegenet expects one ploidy for the entire dataset. Therefore, data frames of allele frequencies with multiple “Genomes” columns, such as those produced when ploidy varies by locus, are not allowed as the freqs argument.

Value

A data frame with row and column names identical to those in freqs, minus the "Genomes" column and any columns for loci not included in loci. Allele frequencies are converted to counts by multiplying by the values in the "Genomes" column and rounding to the nearest integer.

Author(s)

Lindsay V. Clark

References

Jombart, T. (2008) adegenet: a R package for the multivariate analysis of genetic markers. Bioinformatics 24, 1403-1405.

See Also

simpleFreq, deSilvaFreq, write.freq.SPAGeDi, gendata.to.genind

Examples

# create a simple allele frequency table
# (usually done with simpleFreq or deSilvaFreq)
myfreq <- data.frame(row.names=c("popA","popB"), Genomes=c(120,100),
                     locG.152=c(0.1,0.4), locG.156=c(0.5, 0.3),
                     locG.160=c(0.4, 0.3), locK.179=c(0.15, 0.25),
                     locK.181=c(0.35, 0.6), locK.183=c(0.5, 0.15))
myfreq

# convert to adegenet format
gpfreq <- freq.to.genpop(myfreq)
gpfreq

## Not run: 
# If you have adegenet installed, you can now make this into a
# genpop object.
require(adegenet)
mygenpop <- genpop(gpfreq, ploidy=as.integer(4), type="codom")

# examine the object that has been created
mygenpop
popNames(mygenpop)
mygenpop@tab
mygenpop@all.names

# Perform a distance calculation with the object
dist.genpop(mygenpop)

## End(Not run)

---

Class "genambig"

Description

Objects of this class store microsatellite datasets in which allele copy number is ambiguous. Genotypes are stored as a two-dimensional list of vectors, each vector containing all unique alleles for a given sample at a given locus. genambig is a subclass of gendata.

Objects from the Class

Objects can be created by calls of the form new("genambig", samples, loci, ...). This automatically sets up a two-dimensional list in the Genotypes slot, with dimnames=list(samples, loci). This array-list is initially populated with the missing data symbol. All other slots are given initial values according to the initialize method for gendata. Data can then be inserted into the slots using the replacement functions (see Accessors).

Slots

Genotypes:

Object of class "array". The first dimension of the array represents and is named by samples, while the second dimension represents and is named by loci. Each element of the array can contain a vector. Each vector should contain each unique allele for the genotype once. If an array element contains a vector of length 1 containing only the symbol that is in the Missing slot, this indicates missing data for that sample and locus.

Description:

Object of class "character". This stores a description of the dataset for the user's convenience.

Missing:

Object of class "ANY". A symbol to be used to indicate missing data in the Genotypes slot. This is the integer -9 by default.

Usatnts:

Object of class "integer". A vector, named by loci. Each element indicates the repeat type of the locus. 2 indicates dinucleotide repeats, 3 indicates trinucleotide repeats, and so on. If the alleles stored in the Genotypes slot for a given locus are already written in terms of repeat number, the Usatnts value for that locus should be 1. In other words, all alleles for a locus can be divided by the number in Usatnts to give alleles expressed in terms of relative repeat number.

Ploidies:

Object of class "integer". A vector, named by samples. This stores the ploidy of each sample. NA indicates unknown ploidy. See Ploidies<- and estimatePloidy for ways to fill this slot.

PopInfo:

Object of class "integer". A vector, named by samples, containing the population identity of each sample.

PopNames:

Object of class "character". A vector containing names for all populations. The position of a population name in the vector indicates the integer used to represent that population in PopInfo.

Extends

Class "gendata", directly.

Methods

For more information on any of these methods, see the help files of their respective generic functions.

deleteLoci

signature(object = "genambig"): Removes columns in the array in the Genotypes slot corresponding to the locus names supplied, then passes the arguments to the method for gendata.

deleteSamples

signature(object = "genambig"): Removes rows in the array in the Genotypes slot corresponding to the sample names supplied, then passes the arguments to the method for gendata.

editGenotypes

signature(object = "genambig"): Each vector in the Genotypes slot is placed into the row of a data frame, along with the sample and locus name for this vector. The data frame is then opened in the Data Editor so that the user can make changes. When the Data Editor window is closed, vectors are extracted back out of the data frame and written to the Genotypes slot.

estimatePloidy

signature(object = "genambig"): Calculates the length of each genotype vector (excluding those with the missing data symbol), and creates a data frame showing the maximum and mean number of alleles per locus for each sample. This data frame is then opened in the Data Editor, where the user may edit ploidy levels. Once the Data Editor is closed, the genambig object is returned with the new values written to the Ploidies slot.

Genotype

signature(object = "genambig"): Retrieves a single genotype vector, as specified by sample and locus arguments.

Genotype<-

signature(object = "genambig"): Replaces a single genotype vector.

Genotypes

signature(object = "genambig"): Retrieves a two-dimensional list of genotype vectors.

Genotypes<-

signature(object = "genambig"): Replaces a one- or two-dimensional list of genotype vectors.

initialize

signature(.Object = "genambig"): When new is called to create a new genambig object, the initialize method sets up a two dimensional list in the Genotypes slot indexed by sample and locus, and fills this list with the missing data symbol. The initialize method for gendata is then called.

isMissing

signature(object = "genambig"): Given a set of samples and loci, each position in the array in the Genotypes slot is checked to see if it matches the missing data value. A single Boolean value or an array of Boolean values is returned.

Loci<-

signature(object = "genambig"): For changing the names of loci. The names are changed in the second dimension of the array in the Genotypes slot, and then the Loci<- method for gendata is called.

Missing<-

signature(object = "genambig"): For changing the missing data symbol. All elements of the Genotypes array that match the current missing data symbol are changed to the new missing data symbol. The Missing<- method for gendata is then called.

Samples<-

signature(object = "genambig"): For changing the names of samples. The names are changed in the first dimension of the array in the Genotypes slot, and then the Samples<- method for gendata is called.

summary

signature(object = "genambig"): Prints the dataset description (Description slot) to the console as well as the number of missing genotypes, then calls the summary method for gendata.

show

signature(object = "genambig"): Prints the data to the console, formatted to make it more legible. The genotype for each locus is shown as the size of each allele, separated by a '/'. The SSR motif length ('Usatnts'), ploidies, population names, and population membership ('PopInfo') are displayed if they exist.

viewGenotypes

signature(object = "genambig"): Prints a tab-delimited table of samples, loci, and genotype vectors to the console.

"["

signature(x = "genambig", i = "ANY", j = "ANY"): For subscipting genambig objects. Should be of the form mygenambig[mysamples, myloci]. Returns a genambig object. The Genotypes slot is replaced by one containing only samples i and loci j. Likewise, the PopInfo and Ploidies slots are truncated to contain only samples i, and the Usatnts slot is truncated to contain only loci j. Other slots are left unaltered.

merge

signature(x = "genambig", y = "genambig"): Merges two genotypes objects together. See merge,genambig,genambig-method.

Author(s)

Lindsay V. Clark, Tyler W. Smith

See Also

gendata, Accessors, merge,genambig,genambig-method

Examples

# display class definition
showClass("genambig")

# create a genambig object
mygen <- new("genambig", samples=c("a", "b", "c", "d"),
             loci=c("L1", "L2", "L3"))
# add some genotypes
Genotypes(mygen)[,"L1"] <- list(c(133, 139, 145), c(142, 154),
                                c(130, 142, 148), Missing(mygen))
Genotypes(mygen, loci="L2") <- list(c(105, 109, 113), c(111, 117),
                                    c(103, 115), c(105, 109, 113))
Genotypes(mygen, loci="L3") <- list(c(254, 258), Missing(mygen),
                                    c(246, 250, 262), c(250, 258))

# see a summary of the object
summary(mygen)
# display some of the genotypes
viewGenotypes(mygen[c("a", "b", "c"),])

---

Convert Between Genotype Object Classes

Description

These functions convert back and forth between the genambig and genbinary classes.

Usage

genambig.to.genbinary(object, samples = Samples(object),
                      loci = Loci(object))

genbinary.to.genambig(object, samples = Samples(object),
                      loci = Loci(object))

Arguments

object	The object containing the genetic dataset. A genambig object for genambig.to.genbinary, or a genbinary object for genbinary.to.genambig.
samples	An optional character vector indicating samples to include in the new object.
loci	An optional character vector indicating loci to include in the new object.

Details

The slots Description, Ploidies, Usatnts, PopNames, and PopInfo are transferred as-is from the old object to the new. The value in the Genotypes slot is converted from one format to the other, with preservation of allele names.

Value

For genambig.to.genbinary: a genbinary object containing all of the data from object. Missing, Present, and Absent are set at their default values.

For genbinary.to.genambig: a genambig object containing all of the data from object. Missing is at the default value.

Author(s)

Lindsay V. Clark

See Also

genambig, genbinary

Examples

# set up a genambig object for this example
mygen <- new("genambig", samples = c("A", "B", "C", "D"),
             loci = c("locJ", "locK"))
PopNames(mygen) <- c("PopQ", "PopR")
PopInfo(mygen) <- c(1,1,2,2)
Usatnts(mygen) <- c(2,2)
Genotypes(mygen, loci="locJ") <- list(c(178, 184, 186), c(174,186),
                                      c(182, 188, 190),
                                      c(182, 184, 188))
Genotypes(mygen, loci="locK") <- list(c(133, 135, 141),
                                      c(131, 135, 137, 143),
                                      Missing(mygen), c(133, 137))

# convert it to a genbinary object
mygenB <- genambig.to.genbinary(mygen)

# check the results
viewGenotypes(mygenB)
viewGenotypes(mygen)
PopInfo(mygenB)

# convert back to a genambig object
mygenA <- genbinary.to.genambig(mygenB)
viewGenotypes(mygenA)

# note: identical(mygen, mygenA) returns FALSE, because the alleles
# origninally input are not stored as integers, while the alleles
# produced by genbinary.to.genambig are integers.

---

Class "genbinary"

Description

This is a subclass of gendata that allows genotypes to be stored as a matrix indicating the presence and absence of alleles.

Objects from the Class

Objects can be created by calls of the form new("genbinary", samples, loci, ...). After objects are initialized with sample and locus names, data can be added to slots using the replacement functions.

Slots

Genotypes:

Object of class "matrix". Row names of the matrix are sample names. Each column name is a locus name and an allele separated by a period (e.g. "loc1.124"); each column represents on allele. The number of alleles per locus is not limited and can be expanded even after entering initial data. Each element of the matrix must be equal to either Present(object), Absent(object), or Missing(object). These symbols indicate, respectively, that a sample has an allele, that a sample does not have an allele, or that data for the sample at that locus are missing.

Present:

Object of class "ANY". The integer 1 by default. This symbol is used in the Genotypes slot to indicate the presence of an allele in a sample.

Absent:

Object of class "ANY". The integer 0 by default. This symbol is used in the Genotypes slot to indicate the absence of an allele in a sample.

Description:

Object of class "character". A character string or vector describing the dataset, for the convenience of the user.

Missing:

Object of class "ANY". The integer -9 by default. This symbol is used in the Genotypes slot to indicate that data are missing for a given sample and locus.

Usatnts:

Object of class "integer". A vector, named by loci. This indicates the repeat length of each locus. 2 indicates dinucleotide repeats, 3 indicates trinucleotide repeats, and so on. If the alleles stored in the column names of the Genotypes slot for a given locus are already written in terms of repeat number, the Usatnts value for that locus should be 1. In other words, all alleles for a locus can be divided by the number in Usatnts to give alleles expressed in terms of relative repeat number.

Ploidies:

Object of class "integer". A vector, named by samples. This indicates the ploidy of each sample.

PopInfo:

Object of class "integer". A vector, named by samples. This indicates the population identity of each sample.

PopNames:

Object of class "character". Names of each population. The position of the population name in the vector corresponds to the number used to represent that population in the PopInfo slot.

Extends

Class "gendata", directly.

Methods

Absent

signature(object = "genbinary"): Returns the symbol used to indicate that a given allele is absent in a given sample.

Absent<-

signature(object = "genbinary"): Changes the symbol used to indicate that a given allele is absent in a given sample. The matrix in the Genotypes slot is searched for the old symbol, which is replaced by the new. The new symbol is then written to the Absent slot.

Genotype

signature(object = "genbinary"): Returns a matrix containing the genotype for a given sample and locus (by a call to Genotypes).

Genotypes

signature(object = "genbinary"): Returns the matrix stored in the Genotypes slot, or a subset as specified by the samples and loci arguments.

Genotypes<-

signature(object = "genbinary"): A method for adding or replacing genotype data in the object. Note that allele columns cannot be removed from the matrix in the Genotypes slot using this method, although an entire column could be filled with zeros in order to effectively remove an allele from the dataset. If the order of rows in value (the matrix containing values to be assigned to the Genotypes slot) is not identical to Samples(object), the samples argument should be used to indicate row order. Row names in value are ignored. The loci argument can be left at the default, even if only a subset of loci are being assigned. Column names of value are important, and should be the locus name and allele name separated by a period, as they are in the Genotypes slot. After checking that the column name is valid, the method checks for whether the column name already exists or not in the Genotypes slot. If it does exist, data from that column are replaced with data from value. If not, a column is added to the matrix in the Genotypes slot for the new allele. If the column is new and data are not being written for samples, the method automatically fills in Missing or Absent symbols for additional samples, depending on whether or not data for the locus appear to be missing for the sample or not.

initialize

signature(.Object = "genbinary"): Sets up a genbinary object when new("genbinary") is called. If samples or loci arguments are missing, these are filled in with dummy values ("ind1", "ind2", "loc1", "loc2"). The matrix is then set up in the Genotypes slot. Sample names are used for row names, and there are zero columns. The initialize method for gendata is then called.

Missing<-

signature(object = "genbinary"): Replaces all elements in matrix in the Genotypes slot containing the old Missing symbol with the new Missing symbol. The method for gendata is then called to replace the value in the Missing slot.

Present

signature(object = "genbinary"): Returns the symbol used to indicate that a given allele is present in a given sample.

Present<-

signature(object = "genbinary"): Changes the symbol used for indicating that a given allele is present in a given sample. The symbol is first replaced in the Genotypes slot, and then in the Present slot.

Samples<-

signature(object = "genbinary"): Changes sample names in the dataset. Changes the row names in the Genotypes slot, then calls the method for gendata to change the names in the PopInfo and Ploidies slots.

Loci<-

signature(object = "genbinary"): Changes locus names in the dataset. Replaces the locus portion of the column names in the Genotypes slot, then calls the method for gendata to change the names in the Usatnts slot.

isMissing

signature(object = "genbinary"): Returns Boolean values, by sample and locus, indicating whether genotypes are missing. If there are any missing data symbols within the genotype, it is considered missing.

summary

signature(object = "genbinary"): Prints description of dataset and number of missing genotypes, then calls the method for gendata to print additional information.

editGenotypes

signature(object = "genbinary"): Opens the genotype matrix in the Data Editor for editing. Useful for making minor changes, although allele columns cannot be added using this method.

viewGenotypes

signature(object = "genbinary"): Prints the genotype matrix to the console, one locus at a time.

deleteSamples

signature(object = "genbinary"): Removes the specified samples from the genotypes matrix, then calls the method for gendata.

deleteLoci

signature(object = "genbinary"): Removes the specified loci from the genotypes matrix, then calls the method for gendata.

"["

signature(x = "genbinary", i = "ANY", j = "ANY"): Subscripting method. Returns a genbinary object with a subset of the samples and/or loci from x. Usage: genobject[samples,loci].

estimatePloidy

signature(object = "genbinary"): Creates a data frame of mean and maximum number of alleles per sample, which is then opened in the Data Editor so that the user can manually specify the ploidy of each sample. Ploidies are then written to the Ploidies slot of the object.

merge

signature(x = "genbinary", y = "genbinary"): Merges two genotype objects together. See merge,genbinary,genbinary-method.

Author(s)

Lindsay V. Clark

See Also

gendata, Accessors, genambig

Examples

# show the class definition
showClass("genbinary")

# create a genbinary object
mygen <- new("genbinary", samples = c("indA", "indB", "indC", "indD"),
             loci = c("loc1", "loc2"))
Description(mygen) <- "Example genbinary object for the documentation."
Usatnts(mygen) <- c(2,3)
PopNames(mygen) <- c("Maine", "Indiana")
PopInfo(mygen) <- c(1,1,2,2)
Genotypes(mygen) <- matrix(c(1,1,0,0, 1,0,0,1, 0,0,1,1,
                             1,-9,1,0, 0,-9,0,1, 1,-9,0,1, 0,-9,1,1),
   nrow=4, ncol=7, dimnames = list(NULL,
   c("loc1.140", "loc1.144", "loc1.150",
     "loc2.97", "loc2.100", "loc2.106", "loc2.109")))

# view all of the data in the object
mygen

---

Class "gendata"

Description

This is a superclass for other classes that contain population genetic datasets. It has slots for population information, ploidy, microsatellite repeat lengths, and a missing data symbol, but does not have a slot to store genotypes. Sample and locus names are stored as the names of vectors in the slots.

Objects from the Class

Objects can be created by calls of the form new("gendata", samples, loci, ...). The missing data symbol will be set to -9 by default. The default initial value for PopNames is a character vector of length 0, and for Description is the string "Insert dataset description here". The default initial value for the Ploidies slot is a "ploidymatrix" object, containing a matrix filled with NA and named by samples in the first dimension and loci in the second dimension. For other slots, vectors filled with NA will be generated and will be named by samples (for PopInfo) or loci (for Usatnts). The slots can then be edited using the methods described below.

Note that in most cases you will want to instead create an object from one of gendata's subclasses, such as genambig.

Slots

Description:

Object of class "character". One or more character strings to name or describe the dataset.

Missing:

Object of class "ANY". A value to indicate missing data in the genotypes of the dataset. -9 by default.

Usatnts:

Object of class "integer". This vector must be named by locus names. Each element should be the length of the microsatellite repeat for that locus, given in nucleotides. For example, 2 would indicate a locus with dinucleotide repeats, and 3 would indicate a locus with trinucleotide repeats. 1 should be used for mononucleotide repeats OR if alleles for that locus are already expressed in terms of repeat number rather than nucleotides. To put it another way, if you divided the number used to represent an allele by the corresponding number in Usatnts (and rounded if necessary), the result would be the number of repeats (plus some additional length for flanking regions).

Ploidies:

Object of class "ploidysuper". This object will contain a pld slot that is a matrix named by samples and loci, a vector named by samples or loci, or a single value, depending on the subclass. Each element is an integer that represents ploidy. NA indicates unknown ploidy.

PopInfo:

Object of class "integer". This vector also must be named by sample names. Each element represents the number of the population to which each sample belongs.

PopNames:

Object of class "character". An unnamed vector containing the name of each population. If a number from PopInfo is used to index PopNames, it should find the correct population name. For example, if the first element of PopNames is "ABC", then any samples with 1 as their PopInfo value belong to population "ABC".

Methods

deleteLoci

signature(object = "gendata"): Permanently remove loci from the dataset. This removes elements from Usatnts.

deleteSamples

signature(object = "gendata"): Permanently remove samples from the dataset. This removes elements from PopInfo and Ploidies.

Description

signature(object = "gendata"): Returns the character vector in the Description slot.

Description<-

signature(object = "gendata"): Assigns a new value to the character vector in the Description slot.

initialize

signature(.Object = "gendata"): This is called when the new("gendata") function is used. A new gendata object is created with sample and locus names used to index the appropriate slots.

Loci

signature(object = "gendata", usatnts = "missing", ploidies="missing"): Returns a character vector containing all locus names for the object. The method accomplishes this by returning names(object@Usatnts).

Loci

signature(object = "gendata", usatnts = "numeric", ploidies = "missing"): Returns a character vector of all loci for a given set of repeat lengths. For example, if usatnts = 2 all loci with dinucleotide repeats will be returned.

Loci

signature(object= "gendata", usatnts = "missing", ploidies = "numeric"): Returns a character vector of all loci for a given set of ploidies. Only works if object@Ploidies is a "ploidylocus" object.

Loci

signature(object = "gendata", usatnts = "numeric", ploidies = "numeric"): Returns a character vector of all loci that have one of the indicated repeat types and one of the indicated ploidies. Only works if object@Ploidies is a "ploidylocus" object.

Loci<-

signature(object = "gendata"): Assigns new names to loci in the dataset (changes names(object@Usants). Should not be used for adding or removing loci.

Missing

signature(object = "gendata"): Returns the missing data symbol from object@Missing.

Missing<-

signature(object = "gendata"): Assigns a new value to object@Missing (changes the missing data symbol).

Ploidies

signature(object = "gendata", samples = "ANY", loci = "ANY"): Returns the ploidies in the dataset (object@Ploidies), indexed by sample and locus if applicable..

Ploidies<-

signature(object = "gendata"): Assigns new values to ploidies of samples in the dataset. The assigned values are coerced to integers by the method. Names in the assigned vector or matrix are ignored; sample and/or locus names already present in the gendata object are used instead.

PopInfo

signature(object = "gendata"): Returns the population numbers of samples in the dataset (object@PopInfo).

PopInfo<-

signature(object = "gendata"): Assigns new population numbers to samples in the dataset. The assigned values are coerced to integers by the method. Names in the assigned vector are ignored; sample names already present in the gendata object are used instead.

PopNames

signature(object = "gendata"): Returns a character vector of population names (object@PopNames).

PopNames<-

signature(object = "gendata"): Assigns new names to populations.

PopNum

signature(object = "gendata", popname="character"): Returns the number corresponding to a population name.

PopNum<-

signature(object = "gendata", popname = "character"): Changes the population number for a given population name, merging it with an existing population of that number if applicable.

Samples

signature(object = "gendata", populations = "character", ploidies = "missing"): Returns all sample names for a given set of population names.

Samples

signature(object = "gendata", populations = "character", ploidies = "numeric"): Returns all sample names for a given set of population names and ploidies. Only samples that fit both criteria will be returned.

Samples

signature(object = "gendata", populations = "missing", ploidies = "missing"): Returns all sample names.

Samples

signature(object = "gendata", populations = "missing", ploidies = "numeric"): Returns all sample names for a given set of ploidies. Only works if object@Ploidies is a "ploidysample" object.

Samples

signature(object = "gendata", populations = "numeric", ploidies = "missing"): Returns all sample names for a given set of population numbers.

Samples

signature(object = "gendata", populations = "numeric", ploidies = "numeric"): Returns all sample names for a given set of population numbers and ploidies. Only samples that fit both criteria will be returned. Only works if object@Ploidies is a "ploidysample" object.

Samples<-

signature(object = "gendata"): Assigns new names to samples. This edits both names(object@PopInfo) and names(object@Ploidies). It should not be used for adding or removing samples from the dataset.

summary

signature(object = "gendata"): Prints some informaton to the console, including the numbers of samples, loci, and populations, the ploidies present, and the types of microsatellite repeats present.

Usatnts

signature(object = "gendata"): Returns microsatellite repeat lengths for loci in the dataset (object@Usatnts).

Usatnts<-

signature(object = "gendata"): Assigns new values to microsatellite repeat lengths of loci (object@Usatnts). The assigned values are coerced to integers by the method. Names in the assigned vector are ignored; locus names already present in the gendata object are used instead.

"["

signature(x = "gendata", i = "ANY", j = "ANY"): Subscripts the data by a subset of samples and/or loci. Should be used in the format mygendata[mysamples, myloci]. Returns a gendata object with PopInfo, Ploidies, and Usatnts truncated to only contain the samples and loci listed in i and j, respectively. Description, Missing, and PopNames are left unaltered.

merge

signature(x = "gendata", y = "gendata"): Merges two genotype objects. See merge,gendata,gendata-method.

Author(s)

Lindsay V. Clark

See Also

genambig, genbinary, Accessors

Examples

# show class definition
showClass("gendata")

# create an object of the class gendata
# (in reality you would want to create an object belonging to one of the
# subclasses, but the procedure is the same)
mygen <- new("gendata", samples = c("a", "b", "c"),
             loci = c("loc1", "loc2"))
Description(mygen) <- "An example for the documentation"
Usatnts(mygen) <- c(2,3)
PopNames(mygen) <- c("PopV", "PopX")
PopInfo(mygen) <- c(2,1,2)
Ploidies(mygen) <- c(2,2,4,2,2,2)

# view a summary of the object
summary(mygen)

---

Convert Data to genind Format

Description

This is a function for exporting data to the package adegenet.

Usage

gendata.to.genind(object, samples = Samples(object), loci = Loci(object))

Arguments

object	A "genambig" or (preferably) a "genbinary" object.
samples	A character vector indicating the samples to include in the output.
loci	A character vector indicating the loci to include in the output.

Details

gendata.to.genind converts a "genambig" or "genbinary" object to a "genind" object using the package adegenet. Each individual must have a single ploidy. Ploidy and population information are carried over to the new object. Data will be coded as presence/absence in the new object. The locus names in the new object are locus and allele names seperated by a hyphen.

adegenet must be installed in order to use this function.

Value

A genetic dataset in the "genind" class, ready for use in adegenet.

Author(s)

Lindsay V. Clark

References

http://adegenet.r-forge.r-project.org/

Jombart, T. (2008) adegenet: a R package for the multivariate analysis of genetic markers. Bioinformatics 24, 1403–1405.

See Also

freq.to.genpop

Examples

# create a "genambig" object
mydata <- new("genambig", samples=c("a","b","c","d"), loci=c("e","f"))
PopNames(mydata) <- c("G","H")
PopInfo(mydata) <- c(1,1,2,2)
mydata <- reformatPloidies(mydata, output="one")
Ploidies(mydata) <- 3
Genotypes(mydata, loci="e") <- list(c(100),c(100,102),
                                    c(98,102,104),c(102,106))
Genotypes(mydata, loci="f") <- list(c(200,202,204),Missing(mydata),
                                    c(210,212),c(204,210,214))

# convert to "genind"; not tested as it takes several seconds to load adegenet

if(require("adegenet")){
  mydata2 <- gendata.to.genind(mydata)
  mydata2@tab
  locNames(mydata2)
  indNames(mydata2)
  popNames(mydata2)
  pop(mydata2)
}

---

Find All Unique Genotypes for a Locus

Description

This function will return all unique genotypes for a given locus (ignoring allele order, but taking copy number into account) and return those genotypes as well as an index indicating which genotype(s) each individual has. This is a generic function with methods for "genambig" objects and for arrays. The array method is primarily intended for internal use with meandistance.matrix2, processing the output of genotypeProbs.

Usage

genIndex(object, locus)

Arguments

object	Typically, a "genambig" object. A two-dimentional list (array) can also be used here, where samples are in the first dimension and loci in the second dimension and each element of the list is output from genotypeProbs.
locus	A character string or integer indicating which locus to process.

Value

A list with two elements:

uniquegen	A list, where each element in the list is a vector indicating a unique genotype that was found.
genindex	For "genambig" objects, an integer vector, with one value per sample. This is the index of that sample's genotype in uniquegen. For arrays, a list with one element per sample. Each element is a vector of indices of that sample's possible genotypes in uniquegen, in the same order as in the genotypeProbs output.

Author(s)

Lindsay V. Clark

See Also

meandistance.matrix uses the "genambig" method internally.

.unal1loc, assignClones

Examples

data(simgen)
genIndex(simgen, 1)

---

Genotype Diversity Statistics

Description

genotypeDiversity calculates diversity statistics based on genotype frequencies, using a distance matrix to assign individuals to genotypes. The Shannon and Simpson functions are also available to calculate these statistics directly from a vector of frequencies.

Usage

genotypeDiversity(genobject, samples = Samples(genobject),
                  loci = Loci(genobject),
                  d = meandistance.matrix(genobject, samples, loci,
                                          all.distances = TRUE,
                                          distmetric = Lynch.distance),
                  threshold = 0, index = Shannon, ...)

Shannon(p, base = exp(1))

Simpson(p)

Simpson.var(p)

Arguments

genobject	An object of the class "genambig" (or more generally, "gendata" if a value is supplied to d). If there is more than one population, the PopInfo slot should be filled in. genobject is the dataset to be analyzed, although the genotypes themselves will not be used if d has already been calculated. Missing genotypes, however, will indicate individuals that should be skipped in the analysis.
samples	An optional character vector indicating a subset of samples to analyze.
loci	An optional character vector indicating a subset of loci to analyze.
d	A list such as that produced by meandistance.matrix or meandistance.matrix2 when all.distances = TRUE. The first item in the list is a three dimensional array, with the first dimension indexed by locus and the second and third dimensions indexed by sample. These are genetic distances between samples, by locus. The second item in the list is the distance matrix averaged across loci. This mean matrix will be used only if all loci are being analyzed. If loci is a subset of the loci found in d, the mean matrix will be recalculated.
threshold	The maximum genetic distance between two samples that can be considered to be the same genotype.
index	The diversity index to calculate. This should be Shannon, Simpson, or a user-defined function that takes as its first argument a vector of frequencies that sum to one.
...	Additional arguments to pass to index, for example the base argument for Shannon.
p	A vector of counts.
base	The base of the logarithm for calculating the Shannon index. This is exp(1) for the natural log, or 2 for log base 2.

Details

genotypeDiversity runs assignClones on distance matrices for individual loci and then for all loci, for each seperate population. The results of assignClones are used to calculate a vector of genotype frequencies, which is passed to index.

Shannon calculates the Shannon index, which is:

$-\sum \frac{p_i}{N}\ln(\frac{p_i}{N})$

(or log base 2 or any other base, using the base argument) given a vector $p$ of genotype counts, where $N$ is the sum of those counts.

Simpson calculates the Simpson index, which is:

$\sum \frac{p_{i}(p_{i} - 1)}{N(N - 1)}$

Simpson.var calculates the variance of the Simpson index:

$\frac{4N(N-1)(N-2)\sum p_{i}^3 + 2N(N-1)\sum p_{i}^2 - 2N(N-1)(2N-3)(\sum p_{i}^2)^2}{[N(N-1)]^2}$

The variance of the Simpson index can be used to calculate a confidence interval, for example the results of Simpson plus or minus twice the square root of the results of Simpson.var would be the 95% confidence interval.

Value

A matrix of diversity index results, with populations in rows and loci in columns. The final column is called "overall" and gives the results when all loci are analyzed together.

Author(s)

Lindsay V. Clark

References

Shannon, C. E. (1948) A mathematical theory of communication. Bell System Technical Journal 27:379–423 and 623–656.

Simpson, E. H. (1949) Measurement of diversity. Nature 163:688.

Lowe, A., Harris, S. and Ashton, P. (2004) Ecological Genetics: Design, Analysis, and Application. Wiley-Blackwell.

Arnaud-Haond, S., Duarte, M., Alberto, F. and Serrao, E. A. (2007) Standardizing methods to address clonality in population studies. Molecular Ecology 16:5115–5139.

http://www.comparingpartitions.info/index.php?link=Tut4

See Also

assignClones, alleleDiversity

Examples

# set up dataset
mydata <- new("genambig", samples=c("a","b","c"), loci=c("F","G"))
Genotypes(mydata, loci="F") <- list(c(115,118,124),c(115,118,124),
                                   c(121,124))
Genotypes(mydata, loci="G") <- list(c(162,170,174),c(170,172),
                                    c(166,180,182))
Usatnts(mydata) <- c(3,2)

# get genetic distances
mydist <- meandistance.matrix(mydata, all.distances=TRUE)

# calculate diversity under various conditions
genotypeDiversity(mydata, d=mydist)
genotypeDiversity(mydata, d=mydist, base=2)
genotypeDiversity(mydata, d=mydist, threshold=0.3)
genotypeDiversity(mydata, d=mydist, index=Simpson)
genotypeDiversity(mydata, d=mydist, index=Simpson.var)

---

Calculate Probabilities of Unambiguous Genotypes

Description

Given an ambiguous genotype and either a data frame of allele frequencies or a vector of genotype probabilities, genotypeProbs calculates all possible unambiguous genotypes and their probabilities of being the true genotype.

Usage

genotypeProbs(object, sample, locus, freq = NULL, gprob = NULL,
              alleles = NULL)

Arguments

object	An object of class "genambig". The Ploidies and PopInfo slots must be filled in for the sample and locus of interest.
sample	Number or character string indicating the sample to evaluate.
locus	Character string indicating the locus to evaluate.
freq	A data frame of allele frequencies, such as that produced by simpleFreq or deSilvaFreq. This argument should only be provided if the selfing rate is zero.
gprob	A vector of genotype probabilities based on allele frequencies and selfing rate. This is generated by meandistance.matrix2 and passed to genotypeProbs only if the selfing rate is greater than zero.
alleles	An integer vector of all alleles. This argument should only be used if gprob is also being used.

Details

This function is primarily designed to be called by meandistance.matrix2, in order to calculate distances between all possible unambiguous genotypes. Ordinary users won't use genotypeProbs unless they are designing a new analysis.

The genotype analyzed is Genotype(object, sample, locus). If the genotype is unambiguous (fully heterozygous or homozygous), a single unambiguous genotype is returned with a probability of one.

If the genotype is ambiguous (partially heterozygous), a recursive algorithm is used to generate all possible unambiguous genotypes (all possible duplications of alleles in the genotype, up to the ploidy of the individual.)

If the freq argument is supplied:

The probability of each unambiguous genotype is then calculated from the allele frequencies of the individual's population, under the assumption of random mating. Allele frequencies are normalized so that the frequencies of the alleles in the ambiguous genotype sum to one; this converts each frequency to the probability of the allele being present in more than one copy. The product of these probabilities is multiplied by the appropriate polynomial coefficient to calculate the probability of the unambiguous genotype.

$p = \prod_{i=1}^n f_{i}^{c_i} * \frac{(k-n)!}{\prod_{i=1}^n c_i!}$

where p is the probability of the unambiguous genotype, n is the number of alleles in the ambiguous genotype, f is the normalized frequency of each allele, c is the number of duplicated copies (total number of copies minus one) of the allele in the unambiguous genotype, and k is the ploidy of the individual.

If the gprob and alleles arguments are supplied:

The probabilities of all possible genotypes in the population have already been calculated, based on allele frequencies and selfing rate. This is done in meandistance.matrix2 using code from De Silva et al. (2005). Probabilities for the genotypes of interest (those that the ambiguous genotype could represent) are normalized to sum to 1, in order to give the conditional probabilities of the possible genotypes.

Value

probs	A vector containing the probabilities of each unambiguous genotype.
genotypes	A matrix. Each row represents one genotype, and the number of columns is equal to the ploidy of the individual. Each element of the matrix is an allele.

Author(s)

Lindsay V. Clark

References

De Silva, H. N., Hall, A. J., Rikkerink, E., and Fraser, L. G. (2005) Estimation of allele frequencies in polyploids under certain patterns of inheritance. Heredity 95, 327–334

See Also

meandistance.matrix2, GENLIST

Examples

# get a data set and define ploidies
data(testgenotypes)
Ploidies(testgenotypes) <- c(8,8,8,4,8,8,rep(4,14))
# get allele frequencies
tfreq <- simpleFreq(testgenotypes)

# see results of genotypeProbs under different circumstances
Genotype(testgenotypes, "FCR7", "RhCBA15")
genotypeProbs(testgenotypes, "FCR7", "RhCBA15", tfreq)
Genotype(testgenotypes, "FCR10", "RhCBA15")
genotypeProbs(testgenotypes, "FCR10", "RhCBA15", tfreq)
Genotype(testgenotypes, "FCR1", "RhCBA15")
genotypeProbs(testgenotypes, "FCR1", "RhCBA15", tfreq)
Genotype(testgenotypes, "FCR2", "RhCBA23")
genotypeProbs(testgenotypes, "FCR2", "RhCBA23", tfreq)
Genotype(testgenotypes, "FCR3", "RhCBA23")
genotypeProbs(testgenotypes, "FCR3", "RhCBA23", tfreq)

---

Internal Functions in polysat

Description

The internal functions G, INDEXG, GENLIST, RANMUL, and SELFMAT are used for calculating genotype probabilities under partial selfing. The internal function .unal1loc finds all unique alleles at a single locus. The internal function fixloci converts locus names to a format that will be compatible as column headers for allele frequency tables.

Usage

G(q, n)
INDEXG(ag1, na1, m2)
GENLIST(ng, na1, m2)
RANMUL(ng, na1, ag, m2)
SELFMAT(ng, na1, ag, m2)
.unal1loc(object, samples, locus)
fixloci(loci, warn = TRUE)

Arguments

q	Integer.
n	Integer.
ag1	A vector representing an unambiguous genotype.
na1	Integer. The number of alleles, including a null.
m2	Integer. The ploidy.
ng	Integer. The number of genotypes.
ag	An array of genotypes such as that produced by .genlist.
object	A "genambig" object.
samples	Optional, a numeric or character vector indicating which samples to use.
locus	A character string or number indicating which locus to use.
loci	A character vector of locus names.
warn	Boolean indicating whether a warning should be issued if locus names are changed.

Value

G returns

$\frac{(n+q)!}{(q+1)! * (n-1)!}$

INDEXG returns an integer indicating the row containing a particular genotype in the matrix produced by GENLIST.

GENLIST returns an array with dimensions ng, m2, containing all possible unambiguous genotypes, one in each row. The null allele is the highest-numbered allele.

RANMUL returns a list. The first item is a vector of polynomial coefficients for calculating genotype frequencies under random mating. The second is an array showing how many copies of each allele each genotype has.

SELFMAT returns the selfing matrix. Parental genotypes are represented in rows, and offspring genotypes in columns. The numbers indicate relative amounts of offspring genotypes produced when the parental genotypes are self-fertilized.

.unal1loc returns a vector containing all unique alleles, not including Missing(object).

fixloci returns a character vector of corrected locus names.

Author(s)

Lindsay V. Clark

References

De Silva, H. N., Hall, A. J., Rikkerink, E., and Fraser, L. G. (2005) Estimation of allele frequencies in polyploids under certain patterns of inheritance. Heredity 95, 327–334

See Also

deSilvaFreq, meandistance.matrix2, genotypeProbs, genambig.to.genbinary, alleleDiversity

Examples

# Calculation of genotype probabilities in a tetraploid with four
# alleles plus a null, and a selfing rate of 0.5.  This is a translation
# of code in the supplementary material of De Silva et al. (2005).
m2 <- 4
m <- m2/2
na1 <- 5
self <- 0.5
ng <- na1
for(j in 2:m2){
    ng <- ng*(na1+j-1)/j
}
ag <- polysat:::GENLIST(ng, na1, m2)
temp <- polysat:::RANMUL(ng, na1, ag, m2)
rmul <- temp[[1]]
arep <- temp[[2]]
rm(temp)
smat <- polysat:::SELFMAT(ng, na1, ag, m2)
smatdiv <- (polysat:::G(m-1,m+1))^2
p1 <- c(0.1, 0.4, 0.2, 0.2, 0.1) # allele frequencies

# GPROBS subroutine
rvec <- rep(0,ng)
for(g in 1:ng){
    rvec[g] <- rmul[g]
    for(j in 1:m2){
        rvec[g] <- rvec[g]*p1[ag[g,j]]
    }
}
id <- diag(nrow=ng)
smatt <- smat/smatdiv
s3 <- id - self * smatt
s3inv <- solve(s3)
gprob <- (1-self) * s3inv %*% rvec
# gprob is a vector of probabilities of the seventy genotypes.

---

Determine Whether Genotypes Are Missing

Description

isMissing returns Boolean values indicating whether the genotypes for a given set of samples and loci are missing from the dataset.

Usage

isMissing(object, samples = Samples(object), loci = Loci(object))

Arguments

object	An object of one of the subclasses of gendata, containing the genotypes to be tested.
samples	A character or numeric vector indicating samples to be tested.
loci	A character or numeric vector indicating loci to be tested.

Details

isMissing is a generic function with methods for genambig and genbinary objects.

For each genotype in a genambig object, the function evaluates and returns Genotype(object, sample, locus)[1] == Missing(object). For a genbinary object, TRUE %in% (Genotype(object, sample, locus) == Missing(object)) is returned for the genotype. If only one sample and locus are being evaluated, this is the Boolean value that is returned. If multiple samples and/or loci are being evaluated, the function creates an array of Boolean values and recursively calls itself to fill in the result for each element of the array.

Value

If both samples and loci are of length 1, a single Boolean value is returned, TRUE if the genotype is missing, and FALSE if it isn't. Otherwise, the function returns a named array with samples in the first dimension and loci in the second dimension, filled with Boolean values indicating whether the genotype for each sample*locus combination is missing.

Author(s)

Lindsay V. Clark

See Also

Missing, Missing<-, Genotype, find.missing.gen

Examples

# set up a genambig object for this example
mygen <- new("genambig", samples=c("a", "b"), loci=c("locD", "locE"))
Genotypes(mygen) <- array(list(c(122, 126), c(124, 128, 134),
                               Missing(mygen), c(156, 159)),
                          dim=c(2,2))
viewGenotypes(mygen)

# test if some individual genotypes are missing
isMissing(mygen, "a", "locD")
isMissing(mygen, "a", "locE")

# test an array of genotypes
isMissing(mygen, Samples(mygen), Loci(mygen))

---

Calculate Band-Sharing Dissimilarity Between Genotypes

Description

Given two genotypes in the form of vectors of unique alleles, a dissimilarity is calculated as: 1 - (number of alleles in common)/(average number of alleles per genotype).

Usage

Lynch.distance(genotype1, genotype2, usatnt = NA, missing = -9)

Arguments

genotype1	A vector containing all alleles for a particular sample and locus. Each allele is only present once in the vector.
genotype2	A vector of the same form as genotype1, for another sample at the same locus.
usatnt	The microsatellite repeat length for this locus (ignored by the function).
missing	The symbol used to indicate missing data in either genotype vector.

Details

Lynch (1990) defines a simple measure of similarity between DNA fingerprints. This is 2 times the number of bands that two fingerprints have in common, divided by the total number of bands that the two genotypes have. Lynch.distance returns a dissimilarity, which is 1 minus the similarity.

Value

If the first element of either or both input genotypes is equal to missing, NA is returned.

Otherwise, a numerical value is returned. This is one minus the similarity. The similarity is calculated as the number of alleles that the two genotypes have in common divided by the mean length of the two genotypes.

Author(s)

Lindsay V. Clark

References

Lynch, M. (1990) The similarity index and DNA fingerprinting. Molecular Biology and Evolution 7, 478-484.

See Also

Bruvo.distance, meandistance.matrix

Examples

Lynch.distance(c(100,102,104), c(100,104,108))
Lynch.distance(-9, c(102,104,110))
Lynch.distance(c(100), c(100,104,106))

---

Tools for Working With Pairwise Distance Arrays

Description

meandist.from.array produces a mean distance matrix from an array of pairwise distances by locus, such as that produced by meandistance.matrix when all.distances=TRUE. find.na.dist finds missing distances in such an array, and find.na.dist.not.missing finds missing distances that aren't the result of missing genotypes.

Usage

meandist.from.array(distarray, samples = dimnames(distarray)[[2]],
loci = dimnames(distarray)[[1]])

find.na.dist(distarray, samples = dimnames(distarray)[[2]],
loci = dimnames(distarray)[[1]])

find.na.dist.not.missing(object, distarray,
samples = dimnames(distarray)[[2]], loci = dimnames(distarray)[[1]])

Arguments

distarray	A three-dimensional array of pairwise distances between samples, by locus. Loci are represented in the first dimension, and samples are represented in the second and third dimensions. Dimensions are named accordingly. Such an array is the first element of the list produced by meandistance.matrix if all.distances=TRUE.
samples	Character vector. Samples to analyze.
loci	Character vector. Loci to analyze.
object	A genambig object. Typically the genotype object that was used to produce distarray.

Details

find.na.dist.not.missing is primarily intended to locate distances that were not calculated by Bruvo.distance because both genotypes had too many alleles (more than maxl). The user may wish to estimate these distances manually and fill them into the array, then recalculate the mean matrix using meandist.from.array.

Value

meandist.from.array returns a matrix, with both rows and columns named by samples, of distances averaged across loci.

find.na.dist and find.na.dist.not.missing both return data frames with three columns: Locus, Sample1, and Sample2. Each row represents the index in the array of an element containing NA.

Author(s)

Lindsay V. Clark

See Also

meandistance.matrix, Bruvo.distance, find.missing.gen

Examples

# set up the genotype data
samples <- paste("ind", 1:4, sep="")
samples
loci <- paste("loc", 1:3, sep="")
loci
testgen <- new("genambig", samples=samples, loci=loci)
Genotypes(testgen, loci="loc1") <- list(c(-9), c(102,104),
                                        c(100,106,108,110,114),
                                        c(102,104,106,110,112))
Genotypes(testgen, loci="loc2") <- list(c(77,79,83), c(79,85), c(-9),
                                        c(83,85,87,91))
Genotypes(testgen, loci="loc3") <- list(c(122,128), c(124,126,128,132),
                                        c(120,126), c(124,128,130))
Usatnts(testgen) <- c(2,2,2)

# look up which samples*loci have missing genotypes
find.missing.gen(testgen)

# get the three-dimensional distance array and the mean of the array
gendist <- meandistance.matrix(testgen, distmetric=Bruvo.distance,
                                maxl=4, all.distances=TRUE)
# look at the distances for loc1, where there is missing data and long genotypes
gendist[[1]]["loc1",,]

# look up all missing distances in the array
find.na.dist(gendist[[1]])

# look up just the missing distances that don't result from missing genotypes
find.na.dist.not.missing(testgen, gendist[[1]])

# Copy the array to edit the new copy
newDistArray <- gendist[[1]]
# calculate the distances that were NA from genotype lengths exceeding maxl
# (in reality, if this were too computationally intensive you might estimate
# it manually instead)
subDist <- Bruvo.distance(c(100,106,108,110,114), c(102,104,106,110,112))
subDist
# insert this distance into the correct positions
newDistArray["loc1","ind3","ind4"] <- subDist
newDistArray["loc1","ind4","ind3"] <- subDist
# calculate the new mean distance matrix
newMeanMatrix <- meandist.from.array(newDistArray)
# look at the difference between this matrix and the original.
newMeanMatrix
gendist[[2]]

---

Mean Pairwise Distance Matrix

Description

Given a genambig object, meandistance.matrix produces a symmetrical matrix of pairwise distances between samples, averaged across all loci. An array of all distances prior to averaging may also be produced.

Usage

meandistance.matrix(object, samples = Samples(object),
                    loci = Loci(object), all.distances=FALSE,
                    distmetric = Bruvo.distance, progress = TRUE,
                    ...)
meandistance.matrix2(object, samples = Samples(object),
                     loci = Loci(object),
                     freq = simpleFreq(object, samples, loci), self = 0,
                     all.distances = FALSE, distmetric = Bruvo.distance,
                     progress = TRUE, ...)

Arguments

object	A genambig object containing the genotypes to be analyzed. If distmetric = Bruvo.distance, the Usatnts slot should be filled in. For meandistance.matrix2, Ploidies and PopInfo are also required.
samples	A character vector of samples to be analyzed. These should be all or a subset of the sample names used in object.
loci	A character vector of loci to be analyzed. These should be all or a subset of the loci names used in object.
freq	A data frame of allele frequencies such as that produced by simpleFreq or deSilvaFreq.
self	A number ranging from 0 to 1, indicating the rate of selfing.
all.distances	If FALSE, only the mean distance matrix will be returned. If TRUE, a list will be returned containing an array of all distances by locus and sample as well as the mean distance matrix.
distmetric	The function to be used to calculate distances between genotypes. Bruvo.distance, Lynch.distance, or a distance function written by the user.
progress	If TRUE, loci and samples will be printed to the console as distances are calculated, so that the user can monitor the progress of the computation.
...	Additional arguments (such as maxl, add, and loss) to pass to distmetric.

Details

Each distance for the three-dimensional array is calculated only once, to save computation time. Since the array (and resulting mean matrix) is symmetrical, the distance is written to two positions in the array at once.

meandistance.matrix uses ambiguous genotypes exactly as they are, whereas meandistance.matrix2 uses genotypeProbs to calculate all possible unambiguous genotypes and their probabilities under random mating or partial selfing. The distance between each possible pair of unambiguous genotypes for the two samples is calculated with distmetric and weighted by the product of the probabilities of the two gentoypes. As you might expect, meandistance.matrix2 takes longer to process a given "genambig" object than meandistance.matrix does. Additionally, the distance between two identical ambiguous genotypes will be zero when calculated with meandistance.matrix, and greater than zero when calculated with meandistance.matrix2, due to potential differences in copy number of the alleles.

When Bruvo.distance is used, meandistance.matrix2 exaggerates distances between individuals of different ploidy as compared to meandistance.matrix. The use of Bruvo2.distance with meandistance.matrix2 allows individuals with different ploidies to have similar inter-individual distances to those between individuals of the same ploidy. In general, it will be desirable to use Bruvo.distance with meandistance.matrix for complex datasets with high ploidy levels, or Bruvo.distance2 with meandistance.matrix2 for hexaploid or lower datasets (based on how long it takes my personal computer to perform these calculations) where changes in ploidy are due to genome doubling or genome loss. If all individuals have the same ploidy, Bruvo.distance and Bruvo2.distance will give identical results regardless of whether meandistance.matrix or meandistance.matrix2 is used.

meandistance.matrix2 does not allow a genotype to have more alleles than the ploidy of the individual (as listed in the Ploidies slot). Additionally, if self is greater than zero, each population may only have one ploidy at each locus.

Value

A symmetrical matrix containing pairwise distances between all samples, averaged across all loci. Row and column names of the matrix will be the sample names provided in the samples argument. If all.distances=TRUE, a list will be produced containing the above matrix as well as a three-dimensional array containing all distances by locus and sample. The array is the first item in the list, and the mean matrix is the second.

Author(s)

Lindsay V. Clark

See Also

Bruvo.distance, Bruvo2.distance, Lynch.distance, meandist.from.array, GENLIST

Examples

# create a list of genotype data
mygendata <- new("genambig", samples = c("ind1","ind2","ind3","ind4"),
                 loci = c("locus1","locus2","locus3","locus4"))
Genotypes(mygendata) <-
  array(list(c(124,128,138),c(122,130,140,142),c(122,132,136),c(122,134,140),
             c(203,212,218),c(197,206,221),c(215),c(200,218),
             c(140,144,148,150),c(-9),c(146,150),c(152,154,158),
             c(233,236,280),c(-9),c(-9),c(-9)))
Usatnts(mygendata) <- c(2,3,2,1)

# make index vectors of data to use
myloci <- c("locus1","locus2","locus3")
mysamples <- c("ind1","ind2","ind4")

# calculate array and matrix
mymat <- meandistance.matrix(mygendata, mysamples, myloci,
                             all.distances=TRUE)
# view the results
mymat[[1]]["locus1",,]
mymat[[1]]["locus2",,]
mymat[[1]]["locus3",,]
mymat[[2]]

# add addtional info needed for meandistance.matrix2
mygendata <- reformatPloidies(mygendata, output="one")
Ploidies(mygendata) <- 4
PopInfo(mygendata) <- c(1,1,1,1)

# calculate distances taking allele freqs into account
mymat2 <- meandistance.matrix2(mygendata, mysamples, myloci)
mymat2
# now do the same under selfing
mymat3 <- meandistance.matrix2(mygendata, mysamples, myloci, self=0.3)
mymat3

---