Various plots for pems.utils

Share:

Description

Various plot functions and visualization tools for pems objects.

Usage

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
#new plots

#pemsPlot

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

#pemsPlot elements

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

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

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

#WatsonPlot

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

#WatsonPlot elements

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", 
          hijack = FALSE)

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

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

Arguments

x, y, z, 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. cond is a conditioning terms that can be used to subset the supplied data and generate multiple plot panels. See Note Below.

For new plots, these can be supplied either individually or as a formula, e.g. for pemsPlot:

pemsPlot(x, y, z, cond) or
pemsPlot(z~x*y|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) The data source elements in x if not the current environment or a parent.

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). units.add.to.labels = FALSE removes label unit suffixes but retains unit management. units = FALSE disables all unit-related plot handling.

...

(Optional) Other arguments, typically passed on.

fun.name, hijack

(Various) 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, for a Watson plot. As with x above, the first term can be either the x data-series, or a plot formula in form z~x*y|cond.

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 plotting.

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. 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 plot methods for pems and pems.element objects.

However, it also includes a range of higher level plotting functions developed using the lattice and loa packages.

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 two plot call styles by converting conventional plot calls to formula-based calls. It is typically included in a function like pemsPlot at an early stage. After it is run, the returned x can be treated as a formula and y, z and cond can be ignored. 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 also 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 and Examples.

Value

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

If supplied speed and accel 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.

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.

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, other arguments:

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 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. It is simply made using two panels, panel.grid and panel.xyplot, both in lattice. edit{panel.PEMSXYPlot} to have a look at it. 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 as building blocks.

XYZPlot:

The default plot option for latticePlot is levelplot.

pemsPlot:

pemsPlot and subsequent plot functions use an alternative convention. Here, plot is a logical, which is used with another logical, process, to tell the plot function that data processing and plotting steps need to be handled separately. This option is particularly useful if a calculation is carried in-plot panel that affects the plot appearance and this needs to be integrated 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 functions 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 been the most flexible.

See Also

See lattice, latticeExtra, loa.

Examples

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
###########
##example 1
###########

#plotting pems with other packages

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

##in lattice, xyplot(velocity~local.time, data = pemsData(pems.1), type = "l")
#Note: to use lattice functions directly with pems objects
#      just pass data component with data = pemsData(pems) 
#      (NOT data = pems)
#Note: See also latticePlot as an alternative to data = pemsData(pems) 

#in ggplot2

#Note: Suggests only so you need to load this...
##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 = wireframe, shade=TRUE)


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

#basic usage of pemsPlot

#like latticePlot example above 
pemsPlot(~local.time*velocity, data=pems.1, type="l")

#note formula format z~x*y, with z ignored for standard scatter plot

#or in conventional plot(x, y, ...) format
#pemsPlot(local.time, velocity, data=pems.1, type="l")


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

#basic usage of WatsonPlot

#use object generated in example 3 
WatsonPlot(velocity, accel, data=a)

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