PlotNPS: 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

"points" for symbols,
"labels" for text (see node.labels, label.cex and label.colour),
"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.

Author

Lawrence Hudson

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.

Examples

Run this code

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)