comstruct

Calculates mean phylogenetic distance (MPD) and mean nearest phylogenetic taxon distance (MNTD; aka MNND) for each sample, and compares them to MPD/MNTD values for randomly generated samples (null communities) or phylogenies.

Usage

ph_comstruct(
  sample,
  phylo,
  null_model = 0,
  randomizations = 999,
  swaps = 1000,
  abundance = TRUE
)

Arguments

sample: (data.frame/character) sample data.frame or path to a sample file
phylo: (character/phylo) One of: phylogeny as a newick string (will be written to a temp file) - OR path to file with a newick string - OR a an ape phylo object. required.
null_model: (integer) which null model to use. See Details.
randomizations: (numeric) number of randomizations. Default: 999
swaps: (numeric) number of swaps. Default: 1000
abundance: (logical) If TRUE (default) computed accounting for abundance. Otherwise, uses presence-absence.

Value

data.frame

Details

See phylocomr-inputs for expected input formats

Null models

0 - Phylogeny shuffle: This null model shuffles species labels across the entire phylogeny. This randomizes phylogenetic relationships among species.
1 - Species in each sample become random draws from sample pool: This null model maintains the species richness of each sample, but the identities of the species occurring in each sample are randomized. For each sample, species are drawn without replacement from the list of all species actually occurring in at least one sample. Thus, species in the phylogeny that are not actually observed to occur in a sample will not be included in the null communities
2 - Species in each sample become random draws from phylogeny pool: This null model maintains the species richness of each sample, but the identities of the species occurring in each sample are randomized. For each sample, species are drawn without replacement from the list of all species in the phylogeny pool. All species in the phylogeny will have equal probability of being included in the null communities. By changing the phylogeny, different species pools can be simulated. For example, the phylogeny could include the species present in some larger region.
3 - Independent swap: The independent swap algorithm (Gotelli and Entsminger, 2003); also known as ‘SIM9’ (Gotelli, 2000) creates swapped versions of the sample/species matrix.

Taxon name case

In the sample table, if you're passing in a file, the names in the third column must be all lowercase; if not, we'll lowercase them for you. If you pass in a data.frame, we'll lowercase them for your. All phylo tip/node labels are also lowercased to avoid any casing problems

Examples

sfile <- system.file("examples/sample_comstruct", package = "phylocomr")
pfile <- system.file("examples/phylo_comstruct", package = "phylocomr")

# from data.frame
sampledf <- read.table(sfile, header = FALSE,
  stringsAsFactors = FALSE)
phylo_str <- readLines(pfile)
(res <- ph_comstruct(sample = sampledf, phylo = phylo_str))
#> # A tibble: 6 × 15
#>   plot   ntaxa   mpd mpd.rnd mpd.sd    nri mpd.ranklow mpd.rankhi  mntd mntd.rnd
#>   <chr>  <int> <dbl>   <dbl>  <dbl>  <dbl>       <int>      <int> <dbl>    <dbl>
#> 1 clump1     8  4.25    7.27  0.290 10.4           999          0  2        4.72
#> 2 clump…     8  4.94    7.15  0.324  6.82          999          0  2        4.70
#> 3 clump…     8  5.83    7.16  0.326  4.06          994          5  2        4.70
#> 4 clump4     8  6.94    7.16  0.337  0.626         799        221  2        4.71
#> 5 even       8  7.75    7.30  0.265 -1.72           11        999  6        4.76
#> 6 random     8  7.11    7.03  0.344 -0.228         508        510  4.88     4.72
#> # ℹ 5 more variables: mntd.sd <dbl>, nti <dbl>, mntd.ranklo <int>,
#> #   mntd.rankhi <int>, runs <int>

# from files
sample_str <- paste0(readLines(sfile), collapse = "\n")
sfile2 <- tempfile()
cat(sample_str, file = sfile2, sep = '\n')
pfile2 <- tempfile()
cat(phylo_str, file = pfile2, sep = '\n')
(res <- ph_comstruct(sample = sfile2, phylo = pfile2))
#> # A tibble: 6 × 15
#>   plot   ntaxa   mpd mpd.rnd mpd.sd    nri mpd.ranklow mpd.rankhi  mntd mntd.rnd
#>   <chr>  <int> <dbl>   <dbl>  <dbl>  <dbl>       <int>      <int> <dbl>    <dbl>
#> 1 clump1     8  4.25    7.27  0.290 10.4           999          0  2        4.72
#> 2 clump…     8  4.94    7.15  0.324  6.82          999          0  2        4.70
#> 3 clump…     8  5.83    7.16  0.326  4.06          994          5  2        4.70
#> 4 clump4     8  6.94    7.16  0.337  0.626         799        221  2        4.71
#> 5 even       8  7.75    7.30  0.265 -1.72           11        999  6        4.76
#> 6 random     8  7.11    7.03  0.344 -0.228         508        510  4.88     4.72
#> # ℹ 5 more variables: mntd.sd <dbl>, nti <dbl>, mntd.ranklo <int>,
#> #   mntd.rankhi <int>, runs <int>

# different null models
ph_comstruct(sample = sfile2, phylo = pfile2, null_model = 0)
#> # A tibble: 6 × 15
#>   plot   ntaxa   mpd mpd.rnd mpd.sd    nri mpd.ranklow mpd.rankhi  mntd mntd.rnd
#>   <chr>  <int> <dbl>   <dbl>  <dbl>  <dbl>       <int>      <int> <dbl>    <dbl>
#> 1 clump1     8  4.25    7.27  0.290 10.4           999          0  2        4.72
#> 2 clump…     8  4.94    7.15  0.324  6.82          999          0  2        4.70
#> 3 clump…     8  5.83    7.16  0.326  4.06          994          5  2        4.70
#> 4 clump4     8  6.94    7.16  0.337  0.626         799        221  2        4.71
#> 5 even       8  7.75    7.30  0.265 -1.72           11        999  6        4.76
#> 6 random     8  7.11    7.03  0.344 -0.228         508        510  4.88     4.72
#> # ℹ 5 more variables: mntd.sd <dbl>, nti <dbl>, mntd.ranklo <int>,
#> #   mntd.rankhi <int>, runs <int>
ph_comstruct(sample = sfile2, phylo = pfile2, null_model = 1)
#> # A tibble: 6 × 15
#>   plot   ntaxa   mpd mpd.rnd mpd.sd    nri mpd.ranklow mpd.rankhi  mntd mntd.rnd
#>   <chr>  <int> <dbl>   <dbl>  <dbl>  <dbl>       <int>      <int> <dbl>    <dbl>
#> 1 clump1     8  4.25    7.08  0.406  6.98          999          0  2        4.53
#> 2 clump…     8  4.94    7.09  0.350  6.13          998          1  2        4.64
#> 3 clump…     8  5.83    7.07  0.360  3.44          990         10  2        4.62
#> 4 clump4     8  6.94    7.10  0.348  0.446         741        286  2        4.63
#> 5 even       8  7.75    7.22  0.33  -1.62            6        999  6        4.60
#> 6 random     8  7.11    6.95  0.39  -0.405         420        592  4.88     4.63
#> # ℹ 5 more variables: mntd.sd <dbl>, nti <dbl>, mntd.ranklo <int>,
#> #   mntd.rankhi <int>, runs <int>
ph_comstruct(sample = sfile2, phylo = pfile2, null_model = 2)
#> # A tibble: 6 × 15
#>   plot   ntaxa   mpd mpd.rnd mpd.sd    nri mpd.ranklow mpd.rankhi  mntd mntd.rnd
#>   <chr>  <int> <dbl>   <dbl>  <dbl>  <dbl>       <int>      <int> <dbl>    <dbl>
#> 1 clump1     8  4.25    7.28  0.285 10.6           999          0  2        4.73
#> 2 clump…     8  4.94    7.17  0.313  7.13          999          0  2        4.74
#> 3 clump…     8  5.83    7.16  0.324  4.09          997          2  2        4.73
#> 4 clump4     8  6.94    7.18  0.291  0.800         817        206  2        4.77
#> 5 even       8  7.75    7.28  0.301 -1.54            6        999  6        4.74
#> 6 random     8  7.11    7.03  0.342 -0.242         508        510  4.88     4.71
#> # ℹ 5 more variables: mntd.sd <dbl>, nti <dbl>, mntd.ranklo <int>,
#> #   mntd.rankhi <int>, runs <int>
# ph_comstruct(sample = sfile2, phylo = pfile2, null_model = 3)