addDimension {dembase} | R Documentation

## Add one or more dimensions to a demographic array.

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

[Package dembase version 0.0.0.119 Index]