collapseDimension {dembase} | R Documentation

## Collapse one or more dimensions of a demographic array.

### Description

Aggregate values along one or more dimensions of an object of class `DemographicArray`. The aggregated dimensions are dropped.

### Usage

    collapseDimension(
      object,
      dimension = NULL,
      margin = NULL,
      weights,
      na.rm = FALSE,
      ...
    )

    ## S4 method for signature 'Pool,ANY,ANY,missing'
    collapseDimension(object, dimension = NULL, margin = NULL, weights)

    ## S4 method for signature 'Counts,ANY,ANY,missing'
    collapseDimension(
      object,
      dimension = NULL,
      margin = NULL,
      weights,
      na.rm = FALSE
    )

    ## S4 method for signature 'Counts,ANY,ANY,Counts'
    collapseDimension(
      object,
      dimension = NULL,
      margin = NULL,
      weights,
      na.rm = FALSE
    )

    ## S4 method for signature 'Values,ANY,ANY,ANY'
    collapseDimension(
      object,
      dimension = NULL,
      margin = NULL,
      weights,
      na.rm = FALSE
    )

    ## S4 method for signature 'Values,ANY,ANY,missing'
    collapseDimension(object, dimension = NULL, margin = NULL, na.rm = FALSE)

### Arguments

`object` | An object of class `DemographicArray`.
`dimension` | Names or indices of the dimensions to be collapsed.
`margin` | Names or indices of the dimensions that will remain after the collapsing.
`weights` | Object of class `Counts`. `weights` can only be used if `object` has class `Values`. It must have at least as much detail as `object`.
`na.rm` | A logical value indicating whether NA values should be stripped before the computation proceeds.
`...` | Not currently used.

### Details

Either `dimension` or `margin` must be supplied, but not both.

`weights` are required if `object` has class `Values`, and prohibited if `object` has class `Counts`.

If all dimensions are collapsed, the result is equivalent to `sum(object)`.

As discussed in `dimtypes`, some dimensions come in pairs. Members of a pair have the same base name but different suffixes, e.g. `"region_orig"` and `"region_dest"`. Including the base name, e.g. `"region"`, in the `dimension` or `margin` arguments has the same effect as including both names. If only one member of a pair of dimensions is collapsed, the suffix is removed and from the name of the remaining dimension, and the dimtype is changed to `"state"`. See below for examples.

### Value

An object of the same class as `object`, but with fewer dimensions, or a single number.

### See Also

`addDimension`, `collapseCategories`, `collapseIntervals`

### Examples

    library(demdata)
    ## collapse Counts object
    popn <- Counts(VAPopn)
    popn
    collapseDimension(popn, dimension = "age")
    collapseDimension(popn, dimension = c("sex", "color"))
    collapseDimension(popn, margin = c("sex", "color"))

    ## collapse Values object, supplying weights
    rate <- Values(VADeaths2)
    collapseDimension(rate, dimension = "age", weights = popn)

    ## special treatment of origin-destination dimensions
    mig <- Counts(nz.mig)
    mig
    collapseDimension(mig, dimension = "island")
    collapseDimension(mig, margin = "island")
    ## note dimension name and dimtype:
    collapseDimension(mig, margin = "island_orig")

    ## collapse all dimensions
    popn <- Counts(VAPopn)
    collapseDimension(popn, dimension = c("age", "sex", "residence"))
    collapseDimension(popn, margin = character())

[Package dembase version 0.0.0.119 Index]