PlotNPS {cheddar} | R Documentation

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

[Package cheddar version 0.1-633 Index]