A wrapper around various PCoA-based analyses implemented in vegan. The wrapper can handle groups and metadata. PCoA is carried out sample-wise. The na.action is set to na.omit, however envfit cannot deal with missing values, therefore if metadata are provided, they should be free of missing values.

seqPCoA(
abundances,
reference = NULL,
rarefyRef = FALSE,
refName = "ref",
groupAttrib = "",
groups = c(),
groupColors = NULL,
colors = c(),
clusters = c(),
labels = c(),
sizes = c(),
size.legend = "",
time = c(),
hiddenTaxa = c(),
hiddenSamples = c(),
dis = "bray",
rda = FALSE,
scale = FALSE,
doScree = FALSE,
topTaxa = 10,
arrowFactor = 0.5,
centroidFactor = 1,
taxonColor = "brown",
hideGroupLegend = FALSE,
drawEllipse = FALSE,
ellipseOnClusters = FALSE,
ellipseColorMap = NULL,
clusterQualityIndex = "silhouette",
groupDispersion = FALSE,
xlim = NULL,
ylim = NULL,
permut = 1000,
env.permut = 1000,
qvalThreshold = 0.05,
ellipseConf = 0.95,
dimensions = c(1, 2),
...
)

## Details

When a reference and groups are provided and the number of group memberships does not equal the number of samples in the combined abundance table, groups are automatically extended such that reference samples are assigned to a single group with name refName, which is colored in gray. The color vector is likewise extended if provided. If a clusters, time and/or labels vector is provided together with a referene, it has to refer to both data sets. Samples in the abundance matrix are appended after the reference samples, so cluster memberships, time points and/or labels have to be provided in the same order. Different total counts in abundances and reference samples may bias the result, therefore rarefyRef allows to rarefy both to the same total count after matching. RarefyRef will rarefy all samples to the lowest total count found in any sample. Rows with zero counts after rarefaction are removed. When topTaxa is set larger zero, significant top-varying taxa are shown. The permutation test is carried out by shuffling the selected number of top-covarying taxa. Multiple testing correction on parameter-free p-values is then only applied to these top-covarying taxa. The strength of covariance is determined as the norm of the vectors resulting from multiplying the standardized eigen vectors with the taxa. In contrast, envfit p-values are computed for all metadata and multiple-testing correction is consequently applied to all metadata provided, though only the selected number of most significant metadata are shown. Thus, topTaxa ranks taxa by covariance with significance as a filter, whereas topMetadata ranks metadata by significance. The number in the axis label brackets refers to the proportion of variance explained as computed with vegan's eigenvals function. Note that ordination values in plots are not scaled (equivalent to plot.cca(scaling=0)). If groups are provided, drawEllipse can be enabled to draw ellipses with vegan's ordiellipse and to run vegan's adonis (PERMANOVA) to assess whether group composition differs significantly. Adonis is sensitive to differences in within-group variation. To assess whether within-group variation differs, betadisper can be carried out by enabling groupDispersion. In addition, if groups are provided, seqPCoA computes cluster quality indices to assess group separation with package clusterCrit. Concerning interpretation of cluster quality indices: The silhouette index ranges between -1 and 1, a large Dunn's, Silhouette or Calinski-Harabasz index and a small Davies-Bouldin or C-index indicate well-defined clusters, respectively.

## Examples

data("ibd_taxa")
#> [1] "Metadata Age is numeric"
#> [1] "Metadata Diagnosis is categoric"
#> [1] "Metadata Fecal.Calprotectin is numeric"
#> [1] "Metadata antibiotic is binary"
#> [1] "Metadata immunosuppressant is binary"
#> [1] "Metadata mesalamine is binary"
#> [1] "Metadata steroids is binary"seqPCoA(ibd_taxa,groups=as.vector(ibd_metadata$Diagnosis),topTaxa=30, drawEllipse=TRUE)#> [1] "Adonis to test for significant difference in group compositions" #> [1] "Adonis R2: 0.0604, p-value: 0.001" #> [1] "Cluster quality index silhouette" #> [1] -0.02240243 #> [1] "Among the top 30 covarying taxa, 2 are significant." #> [1] "Subdoligranulum_unclassified" #> [1] "Escherichia_unclassified"# remove 65 samples with missing calprotectin measurements or other missing values in the metadata na.indices=unique(which(is.na(ibd_metadata),arr.ind=TRUE)[,1]) indices.to.keep=setdiff(1:nrow(ibd_metadata),na.indices) ibd_metadata=ibd_metadata[indices.to.keep,] ibd_taxa=ibd_taxa[,indices.to.keep] seqPCoA(ibd_taxa,metadata=ibd_metadata,groups=as.vector(ibd_metadata$Diagnosis),topTaxa=30)#> [1] "1 significant numeric metadata found, in order of significance:"
#> [1] "Fecal.Calprotectin"
#> [1] "4 significant categoric metadata found, in order of significance:"
#> [1] "Diagnosis"
#> [1] "antibiotic"
#> [1] "immunosuppressant"
#> [1] "steroids"#> [1] "Cluster quality index silhouette"
#> [1] -0.01835481
#> [1] "Among the top 30 covarying taxa, 4 are significant."
#> [1] "Faecalibacterium_prausnitzii"
#> [1] "Ruminococcus_bromii"
#> [1] "Streptococcus_thermophilus"
#> [1] "Bacteroides_uniformis"