recodeCategories: Change category labels

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

Description

Change the labels used by one or more dimensions with dimscale "Categories".

Usage

recodeCategories(
  object,
  dimension = NULL,
  old = NULL,
  new = NULL,
  concordance = NULL
)

## S4 method for signature 'DemographicArray,ANY,ANY,ANY,missing'
recodeCategories(
  object,
  dimension = NULL,
  old = NULL,
  new = NULL,
  concordance = NULL
)

## S4 method for signature 'DemographicArray,ANY,missing,missing,Concordance'
recodeCategories(
  object,
  dimension = NULL,
  old = NULL,
  new = NULL,
  concordance = NULL
)

Arguments

object	Object of class DemographicArray.
dimension	Character or numeric vector giving the name or index of the dimension where the categories are found - or names or indices if more than one dimension is being changed.
old	The old values for the labels.
new	The new values for the labels.
concordance	A one-to-one Concordance.

Details

There are two ways of specifying the changes in labels. The first is to use arguments old and new; the second is supply a one-to-one Concordance. See below for examples.

If the old and new arguments are used, they must have the same length, and must not contain missing values or duplicates.

Every value in old must also be in the dimension that is being recoded. However, old does not have to contain all the values that are in the dimension being recoded.

With concordances, the opposite rules apply. concordance can have values that are not contained in the dimension being recoded. However, every value that is in the dimension being recoded must also be in concordance.

Roughly speaking, the old-new approach is best suited to changing a small number of labels during interactive use. The concordance approach is often appropriate for production code, since an unanticipated value leads to an error, which may protect against nasty surprises.

recodeCategories works with dimensions with dimscale "Sexes" and "Triangles", both of which are special types of "Categories" dimscales.

Value

A modified version of object with new category labels.

Examples

x <- Counts(array(1:6,
                  dim = c(2, 3),
                  dimnames = list(sex = c("Female",
                                          "Male"),
                                  country = c("China",
                                              "New Zealand",
                                              "USA"))))
x
## single dimension, using 'old' and 'new' arguments
recodeCategories(x,
                 dimension = "country",
                 old = c("New Zealand", "China"),
                 new = c("NZD", "CHN"))
recodeCategories(x,
                 dimension = 2,
                 old = c("New Zealand", "China"),
                 new = c("NZD", "CHN"))
## 'old' cannot contain value not contained
## in dimension being recoded
## Not run: 
recodeCategories(x,
                 dimension = "country",
                 old = c("China",
                         "New Zealand",
                         "Some other country"),
                 new = c("CHN",
                        "NZD",
                        "Whatever"))

## End(Not run)
## single dimension, using a concordance - note 
## that with concordances it is OK to have an
## category - in this case "Australia"
conc <- Concordance(data.frame(long = c("Australia",
                                        "China",
                                        "New Zealand",
                                        "USA"),
                               short = c("AUS",
                                         "CHN",
                                         "NZD",
                                         "USA")))
recodeCategories(x,
                 dimension = "country",
                 concordance = conc)
## but with concordances, every category in the
## dimension must be included in the concordance
conc <- Concordance(data.frame(long = c("New Zealand",
                                        "USA"),
                               short = c("NZD",
                                         "USA")))
## Not run: 
recodeCategories(x,
                 dimension = "country",
                 concordance = conc)

## End(Not run)
## 'recodeCategories' works with dimensions
## with dimscale "Sexes" ...
recodeCategories(x,
                 dimension = "sex",
                 old = c("Female", "Male"),
                 new = c("F", "M"))
## ... though specifying categories that are not
## valid for dimscale "Sexes" is an error
## Not run: 
recodeCategories(x,
                 dimension = "sex",
                 old = c("Female", "Male"),
                 new = c("Ladies", "Gentlemen"))

## End(Not run)
## two dimensions, using 'old' and 'new' arguments
x <- Counts(array(1:9,
                  dim = c(3, 3),
                  dimnames = list(country_orig = c("China",
                                                   "New Zealand",
                                                   "USA"),
                                  country_dest = c("China",
                                                   "New Zealand",
                                                   "USA"))))
x
recodeCategories(x,
                 dimension = c("country_orig", "country_dest"),
                 old = c("China", "New Zealand"),
                 new = c("CHN", "NZD"))
## with origin-destination, or parent-child dimensions
## passing the base name also works
recodeCategories(x,
                 dimension = "country",
                 old = c("China", "New Zealand"),
                 new = c("CHN", "NZD"))

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