prabclus: communitydist – R documentation

Become an expert in R — Interactive courses, Cheat Sheets, certificates and more!

communitydist

Distances between communities

Description

Constructs distances between communities: chord- (Cavalli-Sforza and Edwards, 1967), phiPT/phiST (Peakall and Smouse, 2012, Meirmans, 2006), three versions of the shared allele distance between communities, and geographical distance between communities.

Usage

communitydist(alleleobj,comvector="auto",distance="chord",
                          compute.geodist=TRUE,out.dist=FALSE,
                          grouping=NULL,geodist=NA,diploid=TRUE,
                          phiptna=NA,...)

Arguments

`alleleobj`	if `diploid=TRUE`, an object of class `alleleobject` as produced by function `alleleinit`. This has the required information on the individuals that are grouped into communities. In case `diploid=FALSE`, a list that needs to have components `n.variables` (number of loci), `alevels` (vector of allele names, see `alleleinit`) and `charmatrix` (matrix of characters with one row for every individual and one column for every locus giving the alleles; see examples below for how this can be constructed for a `prabobject` with presence-absence data).
`comvector`	either a vector of integers indicating to which community an individual belongs (these need to be numbered from 1 to a maximum number without interruption), or `"auto"`, which indicates that communities are automatically generated by the `communities`-function.
`distance`	one of `"chord"`, `"phipt"`, `"shared.average"`, `"shared.chakraborty"`, `"shared.problist"`. See Details.
`compute.geodist`	logical, indicating whether geographical distances between communities should be generated.
`out.dist`	logical, indicating whether `dist`-objects are given out or rather distance matrices.
`grouping`	something that can be coerced into a factor, for passing on to `communities` in case that `comvector=="auto"`. This implies that individuals in different groups indicated by `grouping` cannot be together in the same community. Furthermore (also if `comvector` is something else), a vector of groups of communities will be computed, see output component `comgroup`. In any case individuals in different groups are not allowed to be in the same community.
`geodist`	matrix or `dist`-object providing geographical distances between individuals. Required if `compute.geodist==TRUE` or `comvector=="auto"`.
`diploid`	logical, indicating whether loci are diploid, see `alleleobj`.
`phiptna`	if `distance="phipt"`, value to be given out as phiPT-distance in case that the original definition amounts to 0/0 (particularly if communities have just one member).
`...`	optional arguments to be passed on to `communities`.

Details

All genetic distances between communities are based on the information given in alleleobj; either on the alleles directly or on a genetic distance (distmat-component, see alleleinit). The possible genetic distance measures between communities are as follows:

"chord": chord-distance (Cavalli-Sforza and Edwards, 1967)
"phipt": phiPT-distance implemented according to Peakall and Smouse, 2012. This also appears in the literature under the name phiST (Meirmans, 2006, although the definition there is incomplete and we are not sure whether this is identical).
"shared.average": average of between-community genetic distances.
"shared.chakraborty": between-community shared allele distance according to Chakraborty and Jin (1993).
"shared.problist": this implements the shared allele distance (Bowcock et al., 1994) for individuals directly for communities (one minus proportion of alleles shared by two communities averaged over loci).

Value

list with components

`comvector`	integer vector of length of the number of individuals, indicating their community membership.
`dist`	genetic distances between communities. Parameter `out.dist` determines whether this is a `dist`-object or a matrix.
`cgeodist`	if `compute.geodist`, geographical distance between communities defined as average distance of all pairs of individuals belonging to different ones of the two communities between which the distance is computed. Parameter `out.dist` determines whether this is a `dist`-object or a matrix.
`comgroup`	vector of length of the number of communities. If `grouping` was provided, this is a vector giving the group memberships of all communities, otherwise it is a vector of 1s.

Author(s)

Christian Hennig christian.hennig@unibo.it https://www.unibo.it/sitoweb/christian.hennig/en

References

Bowcock, A. M., Ruiz-Linares, A., Tomfohrde, J., Minch, E., Kidd, J. R., Cavalli-Sforza, L. L. (1994) High resolution of human evolutionary trees with polymorphic microsatellites. Nature 368, 455-457.

Cavalli-Sforza, L. L. and Edwards, A. W. F. (1967) Phylogenetic Analysis - Models and Estimation Procedures. The American Journal of Human Genetics 19, 233-257.

Chakraborty, R. and Jin, L. (1993) Determination of relatedness between individuals using DNA fingerprinting. Human Biology 65, 875-895.

Meirmans, P. G. (2006) Using the AMOVA framework to estimate a standardized genetic differentiation measure. Evolution 60, 2399-2402.

Peakall, R. and Smouse P.E. (2012) GenAlEx Tutorial 2. https://biology-assets.anu.edu.au/GenAlEx/Tutorials.html

Examples

options(digits=4)
  data(tetragonula)
  tnb <-
  coord2dist(coordmatrix=tetragonula.coord[83:120,],cut=50,
    file.format="decimal2",neighbors=TRUE)
  ta <- alleleconvert(strmatrix=tetragonula[83:120,])
  tai <- alleleinit(allelematrix=ta,neighborhood=tnb$nblist)
  tetraspec <- c(rep(1,11),rep(2,13),rep(3,14))
  tetracoms <-
  c(rep(1:3,each=3),4,5,rep(6:11,each=2),12,rep(13:19,each=2))
  c1 <- communitydist(tai,comvector=tetracoms,distance="chord",
    geodist=tnb$distmatrix,grouping=tetraspec)
  c2 <- communitydist(tai,comvector=tetracoms,distance="phipt",
    geodist=tnb$distmatrix,grouping=tetraspec,compute.geodist=FALSE)
  c3 <- communitydist(tai,comvector=tetracoms,distance="shared.average",
    geodist=tnb$distmatrix,grouping=tetraspec,compute.geodist=FALSE)
  c4 <- communitydist(tai,comvector=tetracoms,distance="shared.chakraborty",
    geodist=tnb$distmatrix,grouping=tetraspec,compute.geodist=FALSE)
  c5 <- communitydist(tai,comvector=tetracoms,distance="shared.problist",
    geodist=tnb$distmatrix,grouping=tetraspec,compute.geodist=FALSE)
  round(c1$cgeodist,digits=1)
  c1$comvector
  c2$comvector
  c3$comvector
  c4$comvector
  c5$comvector
  round(c1$dist,digits=2)
  round(c2$dist,digits=2)
  round(c3$dist,digits=2)
  round(c4$dist,digits=2)
  round(c5$dist,digits=2)

prabclus

Functions for Clustering and Testing of Presence-Absence, Abundance and Multilocus Genetic Data

v2.3-2

GPL

Authors

Christian Hennig <christian.hennig@unibo.it>, Bernhard Hausdorf <Hausdorf@zoologie.uni-hamburg.de>

Initial release

2020-01-06