Construct a lattice plot from a demographic array.

Description

Construct a lattice plot from an object of class DemographicArray. dplot is much like xyplot, but with extra facilities for aggregating and summarizing, and slightly different defaults.

Usage

dplot(formula, data, ...)

## S4 method for signature 'formula,Counts'
dplot(
  formula,
  data,
  type = NULL,
  panel = panel.dplot,
  groups,
  midpoints = FALSE,
  subarray,
  probs = c(0.025, 0.25, 0.5, 0.75, 0.975),
  horizontal = FALSE,
  overlay = NULL,
  ...
)

## S4 method for signature 'formula,Values'
dplot(
  formula,
  data,
  type = NULL,
  panel = panel.dplot,
  weights,
  midpoints = FALSE,
  subarray,
  probs = c(0.025, 0.25, 0.5, 0.75, 0.975),
  horizontal = FALSE,
  overlay = NULL,
  ...
)

Arguments

Details

If object has class Counts, then the choices for the response on the left of the ~ are as follows:

count

Cell counts are plotted, possibly after aggregation.

Blank

Equivalent to count.

A function of count, eg log(count)

Cell counts are aggregated, tranformed, and plotted.

proportion or percent

A groups argument must be supplied. Cell counts are aggregated, then the distribution across groups is plotted.

If object has class Values, then the choices for the response on the left of the ~ are as follows:

value

Cell values are plotted, possibly after aggregation.

Blank

Equivalent to values.

A function of values, eg log(values)

Cell values are aggregated, tranformed, and plotted.

If midpoints is FALSE, axes representing dimensions with dimscale "Intervals" use a label for each interval. If midpoints is TRUE, intervals are replaced by their midpoints before the plot is constructed, which typically results in less cluttered axes. If names of individual dimensions are supplied, then only these dimensions have their intervals converted to points.

If a subset argument is supplied, this is applied after data is converted to a data frame. Having separate subarray and subset arguments can be useful, because they have different strengths. For instance, subarray allows expressions like age > 60 on intervals, while subset allows more complicated expressions.

The overlay provides a convenient way of adding extra values to graphs. Overlays can include quantiles, even if the main plot does not. Any dimensions of overlay (if overlay has the same class as object) or the values component of overlay (if (overlay) is a list) that are not shared by object will be collapsed away. When overlay or the values component has class Values, the collapsing uses the weights argument. The interface for overlay is likely to change in future.

Value

Object of class "trellis".

Warning

As discussed in the documentation for subarray, the subarray function often does not work when called from within another function. The same is true for the subarray argument in dplot. The solution is typically to use subarray to construct the desired object, and then pass that object to dplot. See below for an example. We are hoping to redesign the

References

Sarkar, Deepayan (2008) Lattice: Multivariate Data Visualization with R, Springer

See Also

Lattice plots are enormously useful, but customizing them can be tricky. See xyplot for an introduction, and the book in the references section for the details.

Internally, dplot calls subarray if a subarray argument is supplied, then collapseDimension to remove any dimensions not included in formula or groups, then as.data.frame to convert the data to a data frame, at which point xyplot takes over.

The plot method for DemographicArray provides a quick graphical summary of a demographic array.

Examples

library(demdata)
popn <- Counts(VAPopn)

## basic plot
dplot(~ age | residence * color, data = popn, groups = sex)

## with simple key
dplot(~ age | residence * color, data = popn,
      groups = sex, auto.key = list(points = FALSE, lines = TRUE))

## horizontal = TRUE
dplot(~ residence | age * color, data = popn,
      groups = sex, horizontal = TRUE)

## percent distribution by sex
dplot(percent ~ age | residence * color, data = popn,
      groups = sex, auto.key = list(points = FALSE, lines = TRUE))

## intervals represented by midpoints
dplot(count ~ age | residence, data = popn, midpoints = TRUE)

## use of subarray argument
dplot(count ~ age | residence, data = popn, subarray = age > 60)

rate <- Values(VADeaths2)

## no aggregation, so no weights needed
dplot(~ age | residence, data = rate, groups = sex)

## aggregating over residence, so weights needed
dplot(~ age, data = rate, groups = sex, weights = popn)

## pass arguments to xyplot to construct a prettier plot
dplot(~ age | residence,
      data = popn,
      groups = sex,
      col = c("dark blue", "salmon"),
      xlab = "Age",
      ylab = "Population",
      prepanel = function(y) list(ylim = c(0, max(y))),
      key = list(text = list(dimnames(popn)$sex),
                 lines = list(col = c("dark blue", "salmon"), type = "o", pch = 21),
                 space = "right"))

## calculate age-specific rate for all groups combined, and overlay on plots
rate.comb <- collapseDimension(rate, margin = "age", weights = popn)
dplot(~ age | sex * residence,
      data = rate,
      col = "blue",
      overlay = list(values = rate.comb, col = "red"),
      midpoints = "age",
      key = list(text = list(c("Rate for region and sex", "Rate for whole population")),
                 lines = list(col = c("blue", "red"), type = "o", pch = 21)))

## example of 'subarray' argument not working when 'dplot'
## called from within another function
## Not run: f <- function(region) {
dplot(count ~ age, data = mig, subarray = island_orig == region)
}
f("South Island")
## End(Not run)