paleotree (version 3.4.7)

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

Description

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.

Usage

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

Value

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

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.

extraMarginForLabels

Argument for extending the space for plotting taxon and site labels. This parameter is currently being tested and may not behave well, especially for plots that aren't being made with very large dimensions.

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.

Author

David W. Bapst

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.

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.

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
    )

if (FALSE) {

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

}