Pyramid plots {cheddar}

Pyramid plots

Description

High-level functions that create pyramid plots.

Usage

PlotBPyramid(community, 
             level = floor(PreyAveragedTrophicLevel(community)),
             expected.levels,
             fill.missing.levels = TRUE,
             order.by.expected = TRUE,
             show.level.labels = TRUE, 
             xlab = Log10BLabel(community, name=expression(~sum(italic(B)))), 
             ylab = "", 
             xlim = NULL, 
             col = NULL, 
             text.col = 'black',
             main = CPS(community)$title,
             ...)

PlotNPyramid(community, 
             level = floor(PreyAveragedTrophicLevel(community)),
             expected.levels,
             fill.missing.levels = TRUE,
             order.by.expected = TRUE,
             show.level.labels = TRUE, 
             xlab = Log10NLabel(community, name=expression(~sum(italic(N)))),
             ylab = "", 
             xlim = NULL, 
             col = NULL, 
             text.col = 'black',
             main = CPS(community)$title,
             ...)

Arguments

community

an object of class Community

level

levels by which values are summed. Can be either the name of a node property, in which case it must meet the criteria of the properties parameter of NPS, or a vector of length NumberOfNodes that contains the levels.

expected.levels

the values that are expected to be in level; see Details for more information.

fill.missing.levels

if TRUE, values in expected.levels that are not present in level are shown in the pyramid.

order.by.expected

if TRUE then the levels are plotted in the order given in expected.levels.

show.level.labels

logical - if TRUE then values of level are shown to the left of the pyramid.

xlab

title of the x axis.

ylab

title of the y axis.

xlim

limits of the x axis.

col

fill colour; either a single colour a vector containing a colour per level.

text.col

colour for the text showing the log10-transformed sums in the blocks of the pyramid; ; either a single colour a vector containing a colour per level.

main

title of the plot.

...

other values to plot functions.

Details

PlotBPyramid plots log10-transformed sum biomass abundance in each level and PlotNPyramid plots log10-transformed sum numerical abundance in each level.

expected.levels provides two behaviours. First, it provides error checking: an error is raised if values are in level that are not in expected.levels. Second, it interacts with fill.missing.levels and order.by.expected to control which levels are drawn and how. If fill.missing.levels is TRUE then values in expected.levels that are not present in level are shown on the pyramid plot. If order.by.level is TRUE then the levels are plotted in the order given in expected.levels. If level contains numbers then expected.levels defaults to a sequence of integers floor(min(level)):ceiling(max(level)). If level is ‘category’ then expected.levels defaults to the intersection of values of ‘category’ that are present in community and the usual Cheddar default values: ‘<unnamed>’, ‘producer’, ‘invertebrate’, ‘vert.ecto’, ‘vert.endo’.

Author(s)

Lawrence Hudson

See Also

Community, SumBiomassByClass, SumNByClass, Log10BLabel, Log10NLabel, floor, ceiling

Examples

data(TL84)

# Use a large left-hand margin to show level text
reset.par <- par(mar=c(5,8,1,1))

# Using prey-averaged trophic level
PlotNPyramid(TL84)

# Using chain-averaged of trophic level
PlotNPyramid(TL84, level=floor(ChainAveragedTrophicLevel(TL84)))

# Show by category
PlotNPyramid(TL84, level='category')

# Taxonomic kingdoms as levels
PlotNPyramid(TL84, level='kingdom')

# Taxonomic kingdoms as levels, with a defined order
PlotNPyramid(TL84, level='kingdom', expected.levels=c("<unnamed>", "Plantae", 
             "Chromista","Bacteria","Protozoa","Animalia"))


# Compare the YthanEstuary and the TL84 datasets. YthanEstuary has nodes in 
# each of the categories whereas TL84 only has producer, invertebrate and 
# vert.ecto nodes. Show categories that are not present in TL84
par(mfrow=c(1,2))
data(YthanEstuary)
xlim <- range(c(Log10N(TL84), Log10N(YthanEstuary)), na.rm=TRUE)
PlotNPyramid(TL84, level='category', xlim=xlim, 
             expected.levels=c('<unnamed>', 'producer', 'invertebrate', 
                               'vert.ecto', 'vert.endo'))
PlotNPyramid(YthanEstuary, level='category',  xlim=xlim)
par(mfrow=c(1,1))


# For the BroadstoneStream dataset, the LongestTrophicLevel function returns 
# nodes in levels 1 and 7 to 10 but no nodes in levels 2 to 6. 
# By default all levels between the minimum and maximum are shown, so levels 
# 2 to 6 appear with no boxes.
data(BroadstoneStream)
PlotNPyramid(BroadstoneStream, 
             level=floor(LongestTrophicLevel(BroadstoneStream)))

# Set fill.missing.levels to FALSE to prevent levels 2 to 6 from being drawn.
PlotNPyramid(BroadstoneStream, 
             level=floor(LongestTrophicLevel(BroadstoneStream)), 
             fill.missing.levels=FALSE)

par(reset.par)