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

Details

During interactive use, objects to be dbinded 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")