dplot {dembase} | R Documentation

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

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

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

[Package dembase version 0.0.0.119 Index]