# 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

1 2 3 4 5 6 7 8 9 | ```
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 |

`samples` |
A character vector of samples to be analyzed. These
should be all or a subset of the sample names used in |

`loci` |
A character vector of loci to be analyzed. These should
be all or a subset of the loci names used in |

`freq` |
A data frame of allele frequencies such as that produced
by |

`self` |
A number ranging from 0 to 1, indicating the rate of selfing. |

`all.distances` |
If |

`distmetric` |
The function to be used to calculate distances
between genotypes. |

`progress` |
If |

`...` |
Additional arguments (such as |

### 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

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 | ```
# 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
``` |