addDimension: Add one or more dimensions to a demographic array.

In StatisticsNZ/dembase: Analysing Cross-Classified Data about Populations

Description

Add one or more dimensions to an object of class DemographicArray. The new dimension(s) can have length 1. If the new dimension(s) have length greater than 1, then by default they simply repeat the contents of the array. The default can be overrided via the scale argument.

Usage

addDimension(
  object,
  name,
  labels,
  after = length(dim(object)),
  dimtype = NULL,
  dimscale = NULL,
  scale = 1L,
  ...
)

## S4 method for signature 'DemographicArray'
addDimension(
  object,
  name,
  labels,
  after = length(dim(object)),
  dimtype = NULL,
  dimscale = NULL,
  scale = 1L
)

Arguments

object	Object of class DemographicArray
name	Character vector with the name of the dimension (or names of the dimensions) to be added.
labels	Character vector with labels to be used by new dimension - or, if several dimensions are being added, and each dimension has different labels, a list of character vectors.
after	Name or index of a dimension of object. The new dimension will be added after this dimension.
dimtype	Optional character with dimtype of new dimension (or dimtypes of new dimensions.)
dimscale	Optional character with dimscale of new dimension (or dimscales of new dimensions.)
scale	Optional numeric vector of scaling factors - or, if several dimensions are being added, and each dimension is scaled differently, a list of numeric vectors.
...	Not currently used.

Details

labels, scale, dimtype, and dimscale are all recycled where appropriate. For instance, if scale is shorter than labels, then scales is recycled until it matches the length of labels. Similarly, if names has length 2 but labels is a single vector, then the same labels vector is used for both dimensions.

Adding dimensions of length greater than 1 generally makes more sense with Values objects than with Counts objects. One case where it does make sense add a dimension of length > 1 to a Counts object is when the Counts object represents exposure to some sort of risk, and the exposure is the same for each category within the new dimension. See below for an example.

Value

Modified version of object

See Also

collapseDimension. To add a dimension with dimtype "destination", use function addPair.

Examples

## Add a time dimension to some population counts
population <- CountsOne(c(10, 12), labels = c("A", "B"), name = "region")
population
addDimension(population, name = "year", labels = "2000", dimscale = "Points")

library(demdata)
deaths <- Values(VADeaths2)
deaths
## assume that Democrats and Republicans have the same death rates
addDimension(deaths,
            name = "party",
            labels = c("Democrat", "Republican"))
## assume that Democrats have slightly higher death rates
addDimension(deaths,
            name = "party",
            labels = c("Democrat", "Republican"),
            scale = c(1.05, 0.95))
## put the new dimension in a different place
addDimension(deaths,
            name = "party",
            labels = c("Democrate", "Republican"),
            after = "age")

income <- Values(array(c(5000, 10000),
                      dim = 2,
                      dimnames = list(age = c("20-34", "35-64"))))
income
## add two dimensions
addDimension(income,
            name = c("residence_orig", "residence_dest"),
            labels = c("Urban", "Rural"))
## now assume that being in an urban area is associated with
## higher income - and note how the scales multiply
addDimension(income,
            name = c("residence_orig", "residence_dest"),
            labels = c("Urban", "Rural"),
            scale = c(1.1, 0.9))
## now with income depending only on origin
addDimension(income,
            name = c("residence_orig", "residence_dest"),
            labels = c("Urban", "Rural"),
            scale = list(c(1.1, 0.9), 1))

## When calculating hospital admissions from different causes,
## use the same population counts as exposure for each
## cause.
admissions <- Counts(array(c(0, 1, 3, 2),
                          dim = c(2, 2),
                          dimnames = list(sex = c("Female", "Male"),
                                          cause = c("Accidents", "Infectious Disease"))))
population <- CountsOne(4:5, labels = c("Female", "Male"), name = "sex")
exposure <- addDimension(population,
                         name = "cause",
                         labels = c("Accidents", "Infectious Disease"))
exposure
admissions / exposure

StatisticsNZ/dembase documentation built on Dec. 25, 2021, 4:49 p.m.