dplot: Construct a lattice plot from a demographic array.
In StatisticsNZ/dembase: Analysing Cross-Classified Data about Populations

Description Usage Arguments Details Value Warning References See Also Examples

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.

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,
  ...
)

`formula`	`formula` object. The symbols to the right of the `~` are interpreted like the right hand side of a standard `xyplot` formula, but the symbols to the left are interpreted differently. See below for details.
`data`	Object of class `DemographicArray`.
`...`	Other arguments, which are passed to the underlying plotting function, `xyplot`.
`type`	Character vector describing the type or types of plot to be drawn, as described in `panel.xyplot`.
`panel`	Panel function. See `xyplot`.
`groups`	A dimension of `data`. Levels for this dimension are overplotted within each panel.
`midpoints`	`TRUE`, `FALSE` (the default), or a character vector.
`subarray`	Expression used to select a subarray from within `data`.
`probs`	Numeric vector used by `collapseIterations` when `object` has a dimension with `dimtype` `"iteration"`.
`horizontal`	Logical, defaulting to `FALSE`. If `TRUE`, the roles of the 'x' and 'y' axes are reversed.
`overlay`	A list describing and overlay.
`weights`	Object of class `Counts`.

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.

Object of class "trellis".

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

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

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.

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)