dbind {dembase} | R Documentation

## Combine DemographicArray objects.

### Description

Combine two or more `"DemographicArray"` objects to form a new object of the same class. Objects are automatically reshaped to make them compatible before they are bound together.

### Usage

    dbind(..., args = list(), along)

### Arguments

`...` | Objects of class `DemographicArray`.
`args` | List of objects of class `DemographicArray`.
`along` | A dimension name.

### Details

During interactive use, objects to be `dbind`ed are typically specified using .... The `args` argument more likely to be used in programming.

An object in ... or `args` may or may not have the dimension specified by `along`. Different objects' `along` dimensions must not overlap. If an object does not have an `along` dimension, then one is added to it. This new dimension consists of a single value, taken from the name of the object. See below for examples.

Before objects are combined, they are automatically manipulated to make all dimensions other than `along` dimension compatible. The automatic manipulation includes collapsing, adding, and permuting dimensions, collapsing or splitting intervals, and permuting categories. However, objects are not subsetted. If it is not possible to make objects compatible using the manipulations available, then an error is raised.

If `along` has `dimtype` `"iteration"`, the iterations for all objects are reset; if an object does not have a dimension with dimtype `"iteration"`, it is treated as a single iteration. See below for examples.

The categories in `along` are taken from existing `along` dimensions, if any, from names passed as part of `dots`, or from the names of the objects. See below for an example.

### Value

Object of the same class as the objects specified in ... or `args`.

### See Also

`dbind` is based on function `abind` in package abind.

### Examples

    library(demdata)
    popn <- Counts(VAPopn)

    ## Split 'popn' into two
    under60 <- subarray(popn, age < 60)
    over60 <- subarray(popn, age > 60)

    ## then recombine using dbind
    dbind(under60, over60, along = "age")

    ## or with via 'args'
    dbind(args = list(under60, over60), along = "age")

    ## or even both.
    dbind(under60, args = list(over60), along = "age")

    ## Now an example of automatic permuting and extending:
    under60new <- collapseDimension(under60, dimension = "color")
    under60new <- aperm(under60new, perm = c("sex", "residence", "age"))
    ## over60 loses "color" dimension and is permuted,
    ## to match under60new
    dbind(under60new, over60, along = "age")

    ## An example of some categories being taken from existing dimension
    ## and some being taken from the name of an object
    NZ <- Counts(nz.mig)
    NZ <- collapseDimension(NZ, dimension = "island_orig")
    Australia <- array(c(2704276, 8376751, 2192675, 2644374),
                       dim = 4,
                       dimnames = list(age = c("15-24",
                             "25-54", "55-64", "65+")))
    Australia <- Counts(Australia)
    ## categories for 'along' taken from 'along' dimension of
    ## 'NZ' object, plus name of 'Australia' object
    dbind(NZ, Australia, along = "island")
    ## now supply a more descriptive name
    dbind(NZ, "West Island" = Australia, along = "island")

    ## example of iterations being reset
    x <- Counts(array(1:4,
                      dim = c(2, 2),
                      dimnames = list(sex = c("Female", "Male"),
                          iteration = 10:11)))
    y <- Counts(array(5:10,
                      dim = c(2, 3),
                      dimnames = list(sex = c("Female", "Male"),
                          iteration = 5:7)))
    x
    y
    dbind(x, y, along = "iteration")

    ## iterations reset, and 'y' treated as a single iteration
    x <- Counts(array(1:4,
                      dim = c(2, 2),
                      dimnames = list(sex = c("Female", "Male"),
                          iteration = 10:11)))
    y <- Counts(array(5:6,
                      dim = 2,
                      dimnames = list(sex = c("Female", "Male"))))
    x
    y
    dbind(x, y, along = "iteration")

[Package dembase version 0.0.0.119 Index]