twoWayEcologyCluster function

R-Mode vs Q-Mode Two-Way Cluster Analyses and Abundance Plot for Community Ecology Data

This mode plots both R-mode (across sites) and Q-mode (across taxa) dendrograms for a community ecology data set, with branches aligned with a grid of dots representing the relative abundance of taxa at each site in the dataset.

twoWayEcologyCluster(
  xDist,
  yDist,
  propAbund,
  clustMethod = "average",
  marginBetween = 0.1,
  abundExpansion = 3,
  cex.axisLabels = 1,
  trimChar = 5,
  xAxisLabel = "Across Sites",
  yAxisLabel = "Across Taxa"
)

Arguments

• xDist: The pair-wise distance matrix for the cluster diagram drawn along the horizontal axis of the graphic. Should be a distance matrix, or a matrix that can be coerced to a distance matrix, for the same number of units as rows in propAbund.

• yDist: The pair-wise distance matrix for the cluster diagram drawn along the vertical axis of the graphic. Should be a distance matrix, or a matrix that can be coerced to a distance matrix, for the same number of units as columns in propAbund.

• propAbund: A matrix of abundance data, preferably relative abundance scaled as proportions of the total number of individuals at each site. This data determines the size scale of the taxon/site dots.

• clustMethod: The agglomerative clustering method used, as with argument method with function hclust. clustMethod must be one of "average"

  (the default method for this function, also known as average-linkage or as UPGMA), "ward.D", "ward.D2", "single", "complete", "mcquitty" (also known as WPGMA), "median"

  (also known as WPGMC) or "centroid" (also known as UPGMC).

• marginBetween: Argument controlling space placed between the cluster diagrams and the abundance plot. Default is 0.1.

• abundExpansion: An argument that is a multiplier controlling the size of dots plotted for reflecting relative abundance.

• cex.axisLabels: Character expansion parameter for controlling the plotting of axis labels on the abundance dot-grid only.

• trimChar: How many characters should the axis labels be trimmed to? Default is 5, which means only the first five letters of each taxon/site label will be shown on the dot-abundance plot.

• xAxisLabel: The label placed on the horizontal axis of the plot.

• yAxisLabel: The label placed on the vertical axis of the plot.

Returns

This function creates a plot, and returns nothing, not even invisible output.

Details

You might be able to apply this to datasets that aren't community ecology datasets of proportional abundance, but I can't guarantee or even predict what will happen.

Examples

set.seed(1)

# generate random community ecology data
    # using a Poisson distribution
data<-matrix(rpois(5*7,1),5,7)

# get relative abundance, distance matrices
propAbundMat<-t(apply(data,1,function(x) x/sum(x)))
rownames(propAbundMat)<-paste0("site ", 1:nrow(propAbundMat))
colnames(propAbundMat)<-paste0("taxon ", 1:ncol(propAbundMat))

# for simplicity, let's calculate
    # the pairwise square chord distance
    # between sites and taxa

squareChordDist<-function(mat){
    res<-apply(mat,1,function(x)
        apply(mat,1,function(y)
            sum((sqrt(x)-sqrt(y))^2)
            )
        )
    #
    res<-as.dist(res)
    return(res)
    }

# its not a very popular distance metric
    # but it will do
    # quite popular in palynology

siteDist<-squareChordDist(propAbundMat)
taxaDist<-squareChordDist(t(propAbundMat))

dev.new(width=10)    

twoWayEcologyCluster(
    xDist = siteDist, 
    yDist = taxaDist,
    propAbund = propAbundMat
    )

## Not run:

# now let's try an example with the example kanto dataset
# and use bray-curtis distance from vegan

library(vegan)

data(kanto)

# get distance matrices for sites and taxa
    # based on bray-curtis dist
    # standardized to total abundance

# standardize site matrix to relative abundance
siteStandKanto <- decostand(kanto, method = "total")

# calculate site distance matrix (Bray-Curtis)
siteDistKanto <- vegdist(siteStandKanto, "bray")

# calculate taxa distance matrix (Bray-Curtis)
    # from transposed standardized site matrix 
taxaDistKanto <- vegdist(t(siteStandKanto), "bray")

dev.new(width=10)    

twoWayEcologyCluster(
    xDist = siteDistKanto,
    yDist = taxaDistKanto,
    propAbund = siteStandKanto,
    cex.axisLabels = 0.8
    )
## End(Not run)

References

The function here was designed to emulate previous published 'two-way' cluster diagrams, particularly the one in Miller, 1988:

Miller, A. I. 1988. Spatial Resolution in Subfossil Molluscan Remains: Implications for Paleobiological Analyses. Paleobiology 14(1):91-103.

See Also

Several other functions for community ecology data in paleotree are described at the communityEcology help file. Also see the example dataset, kanto.

Author(s)

David W. Bapst