collapseOrigDest {dembase} | R Documentation

## Convert data on movements into a less detailed format.

### Description

Convert data on movements classifed by state of origin and state of destination into a less detailed format. The choices of format are

`"out"`

  Total outward moves from each state

`"in"`

  Total inward moves to each state

`"pool"`

  `"out"` and `"in"`

`"net"`

  `"in"` minus `"out"`

### Usage

    collapseOrigDest(
      object,
      base = NULL,
      to = c("net", "pool", "in", "out"),
      weights,
      omitted = ifelse(methods::is(object, "Counts"), 0L, NA_integer_),
      ...
    )

    ## S4 method for signature 'Counts,ANY,ANY,missing'
    collapseOrigDest(
      object,
      base = NULL,
      to = c("net", "pool", "in", "out"),
      omitted = ifelse(methods::is(object, "Counts"), 0L, NA_integer_)
    )

    ## S4 method for signature 'Values,ANY,ANY,ANY'
    collapseOrigDest(
      object,
      base = NULL,
      to = c("net", "pool", "in", "out"),
      weights,
      omitted = ifelse(methods::is(object, "Counts"), 0L, NA_integer_)
    )

### Arguments

`object` | Object of class `DemographicArray`.
`base` | Character vector giving the "base names" for the origin-destination pairs. If `base` is omitted, the base names from all dimensions with `dimtype` `"origin"` and `"destination"` are used.
`to` | The new format(s): `"net"` (the default), `"out"`, and `"in"`.
`weights` | Object of class `Counts` providing the weights to be used. Required if `object` has class `Values`, and prohibited if it has class `Counts`.
`omitted` | Value to be used for omitted origin-destination or parent-child combinations. Defaults to `0` when `object` has class `Counts` and `NA` otherwise.
`...` | Not currently used.

### Details

`collapseOrigDest` calls function `alignPair` before collapsing cells. Argument `omitted` is passed to `alignPair`.

### Value

If `object` has class `linkS4class{Counts}` and `to` is `"net"`, then the return value has class `Net`. If `object` has class `linkS4class{Counts}` and' `to` is `"pool"`, then the return value has class `Pool`. Otherwise the return value has the same class as `object`.

### Warning

If `ans` is the result of applying `collapseOrigDest` to `x`, then `sum(ans)` does not necessarily equal `sum(x)`. For instance, `sum(collapseOrigDest(x, to = "net"))` is always `0`.

### References

Wilson, T. and Bell, M. (2004) Comparative empirical evaluations of internal migration models in subnational population projections. Journal of Population Research. 21(2): 127-160.

### See Also

`alignPair` `collapseCategories`, `collapseIntervals`, `collapseIterations`, `collapseOrigDest`, `collapseDimension`, `dimtypes`, `dimscales`

### Examples

    library(demdata)
    mig <- Counts(nz.mig)
    collapseOrigDest(mig, base = "island", to = "net")

    ## base defaults to all origin-destination base names,
    ## and 'to' defaults to "net"
    collapseOrigDest(mig)

    ## multiple formats, distinguished by dimension "direction"
    collapseOrigDest(mig, to = "pool")
    collapseOrigDest(mig, to = "net")
    collapseOrigDest(mig, to = "out")

    ## different representations imply different totals
    sum(mig)
    sum(collapseOrigDest(mig, to = "net"))
    sum(collapseOrigDest(mig, to = "pool"))

    x <- Counts(array(1:4,
                      dim = c(2, 2),
                      dimnames = list(region_orig = c("a", "b"),
                      region_dest = c("c", "b"))))
    x
    ## extra categories are added to region_orig and
    ## region_dest via 'alignPair' before collapsing
    collapseOrigDest(x, to = "pool")

[Package dembase version 0.0.0.119 Index]