counts-values-generator {dembase} | R Documentation

## Create objects of class "Counts" or "Values".

### 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 `NA`s or (unless the dimension has length 0) `NULL`s. 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)

[Package dembase version 0.0.0.119 Index]