counts-values-generator: Create objects of class "Counts" or "Values".

In StatisticsNZ/dembase: Analysing Cross-Classified Data about Populations

Description

Create objects of class Counts or Values from an array-like object with a full set of dimnames.

Usage

Counts(object, dimtypes = NULL, dimscales = NULL)

Values(object, dimtypes = NULL, dimscales = NULL)

## S4 method for signature 'array'
Counts(object, dimtypes = NULL, dimscales = NULL)

## S4 method for signature 'numeric'
Counts(object, dimtypes = NULL, dimscales = NULL)

## S4 method for signature 'ANY'
Counts(object, dimtypes = NULL, dimscales = NULL)

## S4 method for signature 'DemographicArray'
Counts(object, dimtypes = NULL, dimscales = NULL)

## S4 method for signature 'array'
Values(object, dimtypes = NULL, dimscales = NULL)

## S4 method for signature 'numeric'
Values(object, dimtypes = NULL, dimscales = NULL)

## S4 method for signature 'ANY'
Values(object, dimtypes = NULL, dimscales = NULL)

## S4 method for signature 'DemographicArray'
Values(object, dimtypes = NULL, dimscales = NULL)

Arguments

object	An array, an array-like object such as a table, or a vector. The object must have a full set of names and dimnames (see below for details.)
dimtypes	A named character vector describing the dimtypes of one or more dimensions.
dimscales	A named character vector describing the dimscales of one or more dimensions.

Details

A full set of dimnames means that dimnames(object) is a named list with no NAs or (unless the dimension has length 0) NULLs. In addition, within each dimension there should be no repeated dimnames.

If the dimnames for a dimension look like labels for points or intervals, but are not in numeric order, then Counts and Values will permute rows to put them in order. The most common reason for having interval labels out of order is that xtabs has sorted them lexicographically. See below for an example.

Functions Counts and Values infer dimtypes and dimscales from dimnames(object), plus the dimtypes and dimscales arguments, if supplied. Some ways to assist this process are:

• If the dimtypes argument is not used, then dimensions should have names that match the dimtypes, or are equivalent, such as "time" (the dimtype itself), "Year", or "period" (two equivalents). Case is ignored. If Count or Values do not recognize a dimension name, they assume the dimtype is "state".

• Age labels should follow the style "<0", "0", "1-4", "5-9", "10+". "<a" means the interval (Inf, a). When all breaks are integers, "a0-a1" means the interval between exact ages a0 and a1+1, and "a" means the interval between exact ages a and a+1. Counts and Values will in fact recognize some variations on the standard symbols, but in non-interactive use it is safest to use the standard ones.

• Time labels follow a different style from age labels: when all breaks are integers, the lower limit of each interval is increased by one, instead of the upper limit being reduced by one. Thus, for example, "2001-2005" means the interval between exact times 2000 and 2005, and "2001" means interval between exact times 2000 and 2001.

• Counts and Values assume that a set of intervals are referring to age if the maximum (finite) break is less than 1000, and are referring to time otherwise.

• If dimnames for a dimension consist of consecutive integers,such as "0", "1", "2", then Counts and Values cannot tell whether the dimscale should be "Intervals" or "Points". If a dimension has dimtype "age", the default is to assume that the dimscale is "Intervals", though with a message informing the user that this assumption has been made. If a dimension has dimtype "time", an error is raised.

• As discussed in dimtypes, some dimensions come in pairs. The pairs are identified using suffixes "_orig" and "_dest" (for "origin" and "destination" dimensions) and "_parent" and "_child" (for "parent" and "child" dimensions). As discussed in DemographicArray, there on restrictions on which dimscales may be used with which dimtypes. See the Titanic example below.

Value

An object of class Counts or Values.

See Also

Counts, Values, dimtypes, dimscales

Examples

a <- array(rpois(n = 8, lambda = 10),
          dim = c(2, 2, 2),
          dimnames = list(age = c("0-39", "40+"),
                          sex = c("Female", "Male"),
                          year = c("2001-2010", "2011-2020")))
a
Counts(a)
names(dimnames(a)) <- c("aGe", "SEX", "perioD")
Counts(a)

a <- array(rnorm(n = 5), dim = 5, dimnames = list(age = 0:4))
a
Values(a)
Values(a, dimscales = c(age = "Points"))

Counts(occupationalStatus)

Titanic
## Not run: Counts(Titanic) ## fails
## 'Counts' assumes that the dimension called "Age"
## has dimtype "age", but is then unable to derive
## "Points" or "Intervals" dimscales from categories
## "Child" and "Adult".

## One solution is to rename the "Age" dimension
## to something that Counts does not recognize
## as an age group
Titanic2 <- Titanic
names(dimnames(Titanic2))[3] <- "AgeGp"
Counts(Titanic2)

## A better solution is to explicitly set the dimtypes
Counts(Titanic, dimtypes = c(Age = "state"))

## DemographicArray objects can be created from numeric vectors,
## provided that the vectors have enough names
births <- c(Males = 105, Females = 100)
Counts(births)

## 'xtabs' gets the labels in the wrong order,
## but 'Counts' put them back into the right order
d <- data.frame(age = c("0-4", "5-9", "10+", "0-4", "5-9", "10+"),
                sex = c("F", "F", "F", "M", "M", "M"),
                count = 1:6)
xt <- xtabs(count ~ age + sex, data = d)
x <- Counts(xt)

StatisticsNZ/dembase documentation built on Dec. 25, 2021, 4:49 p.m.