pems.utils (version 0.3.0.7)

5.1.pems.plots: 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")
#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")
#associated functions
preprocess.WatsonPlot(lattice.like = lattice.like, ...)
panel.WatsonBinPlot(..., ref.line = TRUE, 
         process.panel = NULL, plot.panel = NULL, 
         omit.stopped = FALSE, process = TRUE, 
         plot = TRUE, loa.settings = FALSE)
panel.WatsonContourPlot(..., 
         plot.panel=NULL, process = TRUE, 
         plot = TRUE, loa.settings = FALSE)
panel.WatsonSmoothContourPlot(..., 
         plot.panel=NULL, process = TRUE, 
         plot = TRUE, loa.settings = FALSE)
 
#old plots
latticePlot(x = NULL, data = NULL, plot = lattice::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 = lattice::levelplot,
        fun.name = "XYZPlot")

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.

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. This includes, scheme which sets the default coloring scheme for the plot. See Note below.

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.

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.

Author

Karl Ropkins

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.

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.

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.

See Also

See lattice, latticeExtra, loa.

Examples

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

if (FALSE) {
#plotting pems with other packages

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

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

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

}

###########
##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 = lattice::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)

if (FALSE) {
#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)
}