PlotNPS {cheddar}

Plot node properties

Description

High-level functions for plotting node properties.

Usage

PlotNPS(community, 
        X,
        Y,
        main = CPS(community)$title, 
        xlab, 
        ylab, 
        xlim = NULL, 
        ylim = NULL, 
        colour.by, 
        colour.spec, 
        col = NULL, 
        symbol.by, 
        symbol.spec, 
        pch = NULL, 
        bg.by, 
        bg.spec, 
        bg = NULL, 
        cex.by = NULL, 
        cex.spec = NULL, 
        cex = NULL, 
        label.colour.by = NULL, 
        label.colour.spec = NULL, 
        label.colour = NULL, 
        link.colour.by = NULL, 
        link.colour.spec = NULL, 
        link.col = NULL, 
        link.line.type.by = NULL, 
        link.line.type.spec = NULL, 
        link.lty = NULL, 
        link.lwd = NULL, 
        highlight.links = NULL, 
        highlight.nodes = Cannibals, 
        lowlight.nodes, 
        show.na = FALSE,
        show.web = TRUE, 
        show.nodes.as = "points", 
        node.labels = NULL, 
        label.cex = 0.6, 
        are.values = FALSE, 
        frame.plot = TRUE,
        ...)

PlotMvN(community, 
        xlab = Log10NLabel(community), 
        ylab = Log10MLabel(community), 
        ...)

PlotNvM(community, 
        xlab = Log10MLabel(community), 
        ylab = Log10NLabel(community), 
        ...)

PlotBvM(community, 
        xlab = Log10MLabel(community), 
        ylab = Log10BLabel(community), 
        ...)

PlotMvB(community, 
        xlab = Log10BLabel(community), 
        ylab = Log10MLabel(community), 
        ...)

Arguments

community

an object of class Community

X

the name of a property that is plotted on the x axis. Must meet the criteria of the properties parameter of NPS. If are.values is TRUE then X and Y should be vectors of length NumberOfNodes.

Y

plotted on the y axis; see X.

xlab

title of the x axis.

ylab

title of the y axis.

main

title of the plot.

xlim

limits of the x axis.

ylim

limits of the y axis.

colour.by

node colours property. Either NULL, a vector of length NumberOfNodes or the name of a property that meets the criteria of the properties parameter of NPS.

colour.spec

node colours specification. Either NULL or a named vector that maps values of colour.by to plotting values.

col

node colours.

symbol.by

node symbols property; must meet the criteria of colour.by.

symbol.spec

node symbols specification.

pch

node symbols.

bg.by

node background colours property; must meet the criteria of colour.by.

bg.spec

node background colours specification; must meet the criteria of colour.spec.

bg

node background colours.

cex.by

node cex values property; must meet the criteria of colour.by.

cex.spec

node cex values specification; must meet the criteria of colour.spec.

cex

node cex values.

label.colour.by

node label colours property; must meet the criteria of colour.by.

label.colour.spec

node label colours specification; must meet the criteria of colour.spec.

label.colour

node label colours.

link.colour.by

link colours; either NULL, a vector of length NumberOfTrophicLinks or the name of a property that meets the criteria of the link.properties parameter of TLPS.

link.colour.spec

link line colour specification; either NULL or a named vector that maps values of link.colour.by to plotting values.

link.col

link colours.

link.line.type.by

link link types; must meet the criteria of link.colour.by.

link.line.type.spec

link line type specification; must meet the criteria of link.colour.spec.

link.lty

link line types.

link.lwd

line line widths.

highlight.links

either NULL, a vector of length NumberOfNodes or a name that meets the criteria of the properties paremeter of NPS..

highlight.nodes

nodes to be highlighted; either NULL, a vector of node names, a vector of node indices or a function that takes a Community as its only parameter and returns a vector of either node names or indices.

lowlight.nodes

nodes to be lowlighted; must meet the criteria of highlight.nodes.

show.na

logical - if TRUE then nodes for which X and/or Y is NA will be placed at the lowest extent of the relevant axis using the PlaceMissingPoints function. If FALSE then these nodes will not be plotted.

show.web

logical - if TRUE and community has trophic links then the food web is plotted using the link* and highlight.links parameters

show.nodes.as

how nodes should be plotted. One of

1. "points" for symbols,

2. "labels" for text (see node.labels, label.cex and label.colour),

3. "points" for symbols and text.

node.labels

Either NULL, a vector of length NumberOfNodes or a name that meets the criteria of the properties paremeter of NPS. If NULL node labels are 1:NumberOfNodes.

label.cex

a character expansion factor; used only if show.nodes.as is equal to "points".

are.values

logical - if TRUE X and Y must be vectors of values of length NumberOfNodes.

frame.plot

logical - default TRUE.

...

other values to plot functions.

Details

The general-purpose function PlotNPS plots one node property against another.

For colour.by, symbol.by, bg.by, cex.by and label.colour.by, if X.by is not NULL and a relevant X.spec is not given, the X.by values are converted to a factor, the levels of which are used as the plot parameter. An error is raised if X.by contains any values not present in X.spec.

If colour.by/bg.by/symbol.by is NULL and community has a node property named ‘category’ then node colours/background colours/symbols are given by ‘category’ using the colour.spec/bg.spec/symbol.spec given by DefaultCategoryColours/DefaultCategorySymbols.

label.colour.by, node.labels and label.cex are used only if show.nodes.as is equal to "points".

The convenience functions PlotMvN, PlotNvM, PlotBvM and PlotMvB are ‘wrappers’ around PlotNPS that plot log10-transformed body mass (M), numerical abundance (N) or biomass (B). All of the parameters of PlotNPS, with the exception of X, Y and are.values, can be used with these four functions.

If show.nodes.as is equal to "points" then labels are plotted using label.cex and label.colour.

Author(s)

Lawrence Hudson

See Also

Community, NPS, DefaultCategoryColours, DefaultCategorySymbols, PlotBSpectrum, PlotCircularWeb, PlotNPSDistribution, PlotNSpectrum, PlotRankNPS, PlotTLPS, PlotWebByLevel PlaceMissingPoints

Examples

data(TL84)
PlotNvM(TL84)

# Set colours and plot symbols directly
PlotNvM(TL84, col=1, pch=19, highlight.nodes=NULL)

# Plot each level of taxonomic resolution in a different colour
PlotNvM(TL84, colour.by='resolved.to', pch=19, highlight.nodes=NULL)

# Plot each level of taxonomic resolution in a specific colour
colour.spec <- c(Species='purple3', Genus='green3', 'red3')
PlotNvM(TL84, colour.by='resolved.to', colour.spec=colour.spec, pch=19, 
        highlight.nodes=NULL)
legend("topright", legend=names(colour.spec), pch=19, col=colour.spec)

# Use PlotNPS to plot trophic height against log10 body mass
PlotNPS(TL84, 'Log10M', 'TrophicHeight', xlab=Log10MLabel(TL84), 
        ylab='Trophic height')


# The 'POM (detritus)' node in the Ythan Estuary dataset lacks both body mass 
# and numerical abundance.
par(mfrow=c(1,2))
data(YthanEstuary)
PlotNvM(YthanEstuary)
PlotNvM(YthanEstuary, show.na=TRUE)