recodeCategories {dembase} | R Documentation

## Change category labels

### 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"))

[Package dembase version 0.0.0.119 Index]