R: Various plots for pems.utils

5.1.pems.plots {pems.utils}

R Documentation

Various plots for pems.utils

Description

Various plot functions and visualization tools for use with pems objects.

Usage


#pemsPlot

pemsPlot(x, y = NULL, z = NULL, groups = NULL, 
         cond = NULL, ..., data = NULL, 
         units = TRUE, multi.y = "special", 
         fun.name="pemsPlot",
         panel = panel.pemsPlot, scheme = pems.scheme)

#associated functions

pemsXYZCondUnitsHandler(x, y = NULL, z = NULL, 
         cond = NULL, groups = NULL, data = NULL, 
         units = TRUE, ..., 
         fun.name = "pemsXYZCondHandler")

preprocess.pemsPlot(lattice.like = lattice.like, 
         units = units, ...)

panel.pemsPlot(..., loa.settings = FALSE)

panel.routePath(..., loa.settings = FALSE)

#WatsonPlot

WatsonPlot(speed, accel = NULL, z = NULL, ..., 
         data = NULL, cond = NULL, units = TRUE, 
         plot.type = 2, fun.name="WatsonPlot",
         scheme = pems.scheme)

#associated functions

preprocess.WatsonPlot(lattice.like = lattice.like, ...)

panel.WatsonBinPlot(..., ref.line = TRUE, 
         process.panel = panel.binPlot, 
         plot.panel = panel.binPlot, 
         omit.stopped = FALSE, process = TRUE, 
         plot = TRUE, loa.settings = FALSE)

panel.WatsonContourPlot(..., 
         plot.panel=panel.kernelDensity, process = TRUE, 
         plot = TRUE, loa.settings = FALSE)

panel.WatsonSmoothContourPlot(..., 
         plot.panel=panel.surfaceSmooth,           
         process = TRUE, plot = TRUE, 
         loa.settings = FALSE)
 
#old plots

latticePlot(x = NULL, data = NULL, plot = xyplot, 
         panel = NULL,  ..., greyscale = FALSE, 
         fun.name = "latticePlot")

panel.PEMSXYPlot(..., grid=NULL)

XYZPlot(x = NULL, ..., data = NULL, statistic = NULL, 
         x.res = 10, y.res = 20, plot = levelplot,
        fun.name = "XYZPlot")

Arguments

`x`, `y`, `z`, `groups`, `cond`	(Various) The main plot elements. `x` and `y` are typically plot coordinates. `z` is any additional information that could be used , e.g. to modify points plotted at `(x,y)` coordinates or generate a third axis for a surface plot. `groups` and `cond` are plot grouping and conditioning terms that can be used to subset the supplied data and/or generate multiple plot panels. See Below. For new plots, these should be supplied individually, e.g. for `pemsPlot`: `pemsPlot(x, y, z, groups, cond)` For old plots, these must be formulae. For `latticePlot` the basic formula structure is `y ~ x \| cond`. For `XYZPlot` the basic formula structure is `z ~ y * x \| cond`. `z` is optional, but when it is not supplied `z` it is treated as the bin count. See Notes and Examples.
`data`	(Optional `data.frame` or `pems` object) For most plots, the data source for plot elements, e.g `x`, `y`, `z`, etc, if these are not supplied directly or accessible from the current workspace.
`units`	(Optional `logical` or `list`) for `pemsPlot` only, unit handling information. By default, `pems.utils` adds any known units to plot labels and allows in-plot unit management. Unit management is handled by `convertUnits`, and requested conversions need to assigned to an axis. So, for example, the call `pemsPlot(..., x.to="m/s")` would generate a plot with the x-axis in units of m/s (assuming `pems.utils` knows the unit conversion and the x-axis data series is in units that can be converted). All unit management and associated figure labelling can disabled using `units = FALSE`, or unit suffixes can be removed but unit management retained using `units.add.to.labels = FALSE`.
`multi.y`	(character) `pems.plots` accepted multiple `y` data-series if passed using `cpe`, e.g. `y = cpe(a,b)`. `multi.y` sets how these are handled, options include `'groups'`, `'cond'` and `'special'` (the default), which selects groups if not used in plot call else cond.
`...`	(Optional) Other arguments, typically passed on.
`fun.name`	(Function management argument) `pems.utils` management settings, can typically be ignored by most users.
`panel`, `plot.panel`, `process.panel`	(Functions) These functions are used to generate the content of individual plot panels. Typically, all in-panel data processing and plotting is carried out using `panel`. However, these steps can be handled by separate functions if these are supplied as `plot.panel` and `process.panel`.
`scheme`	(`character` or `list`) The default coloring scheme for the plot. See Note below.
`lattice.like`, `plot`, `process`, `loa.settings`	(Various) Plot management elements. These can typically be ignored by most users, but allow plot developers to fine-tune plots. See Details below.
`speed`, `accel`	(Various) For `WatsonPlot`, the `x` and `y` terms, speed and acceleration, respectively.
`ref.line`	(Logical or list) For `WatsonPlot`. This argument manages the speed = 0 reference added to WatsonPlots. It can be either a logical (`TRUE`/`FALSE`), to turn the line on or off, or a list of parameters to set the properties of the line.
`omit.stopped`	(Logical or character) For WatsonPlot, how to handle idling data: `FALSE` include in plot; `TRUE` or `'points'` removes idle points before plotting; `'cell'` or `'cells'` removes any cells that include idling points before the data is binned.
`plot.type`	(numeric) For WatsonPlot, pre-set plot types: `1` scatter plot; `2` bin plot; `3` contour plot of binned data; `4` smoothed surface of binned data. See also `statistic`
`greyscale`	(Logical) For older plots only, should the plot be greyscale by default? This option resets the `lattice` color themes to greyscale while the plot is beging generated. So: (1) This only effects the plot itself, not subsequent plots; and, (2) any user resets overwrite this, e.g. `latticePlot(..., greyscale=TRUE, col="red")` will place red symbols on an overwise greyscale plot. Newer plots use the alternative `plot(..., scheme = "greyscale")`.
`grid`	(List) If supplied, a list of plot parameters to be used to control the appearance of the grid component of the plot. See Below.
`statistic`	(Function) when binning data with `XYZPlot` and `WatsonPlot`, the function to use when evaluating the elements of each data bin. By default, `length` is used if `z` is not supplied to generate a frequency plot and `mean` is used if `z` is supplied to generate a bin average plot.
`x.res`, `y.res`	(Numerics) when binning data with `XYZPlot`, the number of x- and y-axis bins to generate.

Details

pems.utils includes conventional (generic) plot methods for pems and pems.element objects. See plot.pems and plot.pems.element for further details.

However, it also includes a range of higher-level plotting functions developed for use with pems data.

Early plots, e.g. latticePlot, only allowed plot arguments using the lattice formula format. While this is flexible and very powerful system, some users preferred the more conventional plot(x,y,..) call format. So, newer plots, e.g. pemsPlot, allow both conventional plot and lattice-style formula calls.

pemsXYZCondUnitsHandler handles the pems information associated with the plots. This routine is included as a discrete function within this package and others are welcome to use elsewhere for similar purposes. edit(pemsPlot) to see it.

Newer plots use a combination of lattice and loa functions to provide a range of additional plotting options, such as integrated panel and key management. See loa documentation for further details.

preprocess... and panel... functions handle pre-plot and in-plot elements of plot generation. These use the loa modification of the lattice plotting framework.

See Notes, Examples and extra documentation: pems.plots.

Value

By default, pemsPlot generates a bubble plot, so it plots (x,y) points, and by default color-grades and size-scales them according to z if also supplied.

When supplied speed and accel data-series as x and y cases, the WatsonPlot generates various forms of Watson's classic speed/accel frequency distribution plot.

latticePlot and XYZPlot are general purpose 'xy' and 'xyz' data plotting functions.

fortify is intended for use by ggplot2 functions when users are plotting data in pems objects. See Notes.

Warning

IMPORTANT: Conditioning is currently disabled on XYZPlot.

XYZPlot is a short-term replace for previous function quickPlot. It will most likely be replaced when pems.utils.0.3 is released.

pemsPlot and WatsonPlot no longer accept formula x, y, z inputs.

With all these functions I have tried to make the default plotting options as robust as possible. However, it is not always possible to test all the plot combines that users might try. So, please let me know if anything is not working nicely for you. Thanks.

Note

General:

Like most other plot functions in R, lattice functions use a number of common parameter terms. For example, xlab and ylab reset the x and y labels of a graph; xlim and ylim to set the x- and y-scales of a graph; col sets the color of a plot element; type sets the type ('p' for points, 'l' for lines, etc); pch and cex set plot symbol type and size, respectively; and, lty and lwd set plot line type and thickness, respectively; etc. These terms are passed onto and evaluated by all these plot functions to provide standard plot control.

latticePlot:

The default plot option for latticePlot is xyplot.

panel options for latticePlot: Default panel.xyplot. The alternative panel, panel.PEMSXYPlot supplied as part of this package, adds a grid layer to a standard xy panel. The extra code just allows you to pass specific plot parameters to the grid panel using the argument grid. You can build almost any plot layout using these and other panels in lattice and loa as building blocks.

XYZPlot:

The default plot option for latticePlot is levelplot.

pemsPlot:

pemsPlot and subsequent plot functions use an alternative convention. Here, plots include separate process and plot steps. This option allows the plot to pass on share the results of in-panel calculations with other panels and keys. The handling mechanism is part of the loa package.

The reason for latticePlot, etc:

latticePlot combines a number of lattice and latticeExtra function modifications I regularly use when plotting data. So, it is basically a short cut to save having to write out a lot of code I regularly use. I would encourage anyone to at the very least have a look at lattice.

I also hope those learning lattice, find these functions a helpful introduction and handy 'stop gap' while they are getting to grips with the code behind trellis and panel structures.

Author(s)

Karl Ropkins

References

lattice:

Sarkar, Deepayan (2008) Lattice: Multivariate Data Visualization with R. Springer, New York. ISBN 978-0-387-75968-5

latticeExtra:

Deepayan Sarkar and Felix Andrews (2011). latticeExtra: Extra Graphical Utilities Based on Lattice. R package version 0.6-18. http://CRAN.R-project.org/package=latticeExtra

lattice is one of number of really nice graphical tools in R. Others, like ggplot2 and iplot, help you to very quickly explore your data. But, for me the trellis framework of lattice has always felt the most flexible.

Examples


###########
##example 1
###########

## Not run: 
#plotting pems with other packages

#base 
plot(pems.1)
plot(pems.1$velocity)

#lattice 
xyplot(velocity~local.time, data = pems.1, type = "l")

#in ggplot2

#Note: Suggests only so you need to load this...
#Note: this uses fortify.pems behind scenes...

require(ggplot2)
qplot(time.stamp, velocity, data=pems.1)
ggplot(pems.1, aes(x = time.stamp, y = velocity)) + geom_line() 
#etc


## End(Not run)

###########
##example 2 
###########

#basic usage of latticePlot

latticePlot(velocity~local.time, data = pems.1, type = "l")

latticePlot(velocity~local.time, data = pems.1, col = "red", 
            pch = 20, panel = panel.PEMSXYPlot, 
            grid = list(col ="black", lty=2))

###########
##example 3 
###########

#basic usage of XYZPlot

a <- calcAccel(velocity, local.time, data = pems.1, output="pems")

XYZPlot(~accel*velocity, data=a)

XYZPlot(~accel*velocity, data=a, plot = wireframe, shade=TRUE)


###########
##example 4 
###########

#basic usage of pemsPlot

pemsPlot(local.time, velocity, data=pems.1, type="l")


###########
##example 5 
###########

#basic usage of WatsonPlot

#Note: using 'a' generated in example 3 
WatsonPlot(velocity, accel, data=a)

## Not run: 
#omit.stopped for different handling of idling data
WatsonPlot(velocity, accel, data=a, omit.stopped="points")
WatsonPlot(velocity, accel, data=a, omit.stopped="cells")

#plot.type for different plot methods
WatsonPlot(velocity, accel, data=a, plot.type=1)
WatsonPlot(velocity, accel, data=a, plot.type=2)
WatsonPlot(velocity, accel, data=a, plot.type=3)
WatsonPlot(velocity, accel, data=a, plot.type=4)

## End(Not run)

[Package pems.utils version 0.2.29.1 Index]