subarray: Subset a demographic array.
In StatisticsNZ/dembase: Analysing Cross-Classified Data about Populations

Description Usage Arguments Details Value Warning See Also Examples

Use a logical expression to select a subarray from within an object of class DemographicArray.

subarray(object, ...)

## S4 method for signature 'DemographicArray'
subarray(object, subarray, drop = TRUE)

`object`	Object of class `DemographicArray`.
`...`	Further arguments to be passed to or from other methods.
`subarray`	Logical expression picking out a subarray within `object`.
`drop`	Logical, specifying whether dimensions of length 1 should be retained in the result. Defaults to `TRUE`.

Selections involving dimscales Points or Intervals can be made in the same way as selections involving other dimscales, by specifying labels (in quotes.) However, they can also be made using inequality operators <, <=, >, and >=. An intervals is selected by an inequality operator if the operator takes in the entire interval. For instance, interval (a, a+n) on dimension age is selected by the expression age > x if x <= a. The interval is not selected by a < x, even if x < a + n. Expression age > x has the same effect as age >= x, based on the assumption that no one is age exactly a (and similarly for time).

subarray sometimes modifies the names, dimtypes or dimscales of the return value so that they conform to the rules governing dimtypes and dimscales. For instance, when the return value has only one dimension from an origin-destination pair, subarray will change the dimtype of that dimension to "state", and will remove the "_orig" or "_dest" suffix from its name. See below for a second example where subarray changes the dimtypes and dimscales of an "age" dimension.

Typically an object of class DemographicArray, but maybe a vector in some cases when drop is TRUE.

The documentation for function subset (the inspiration for subarray) warns that the non-standard evaluation of the subset argument can have unanticipated consequences. It recommends that, for programming, subsetting be done via standard functions such as [. The same advice applies to subarray: see below for an example. However, these sorts of problems normally only occur when using subarray within another function. In interactive use, or in simple scripts to extract or manipulate a dataset, the greater transparency and flexibility of subarray typically make it a better choice than [.

subset provides similar functionality for vectors, matrices, or data frames, though without the requirement that the resulting subsets have all the combinations of values required for an array.

library(demdata)
rates <- Values(VADeaths2)
## selection using labels
subarray(rates, residence == "Rural")
subarray(rates, age == "50-54")
subarray(rates, age %in% c("50-54", "55-59"))

## selection using inequalities
subarray(rates, age > 60)
subarray(rates, age > 59)
subarray(rates, age >= 60)

## selection creates a gap in the age groups,
## so dimscales changes to "Categories",
## which means dimtypes must change to "state"
subarray(rates, age < 55 | age > 65)

## can select from multiple dimensions at once
subarray(rates, (age < 60) & (sex == "Male"))
## but only if the selection is 'rectangular'
## - ie results in an array
## Not run: subarray(rates, (age > 60) | (sex == "Male"))

mig <- Counts(nz.mig)
subarray(mig, island_orig == "South Island")

## an example of the problems encountered calling
## 'subarray' from within a function
f <- function(orig) {
    subarray(mig, island_orig = orig)
}
## Not run: f()