Epi: Relevel – R documentation

Become an expert in R — Interactive courses, Cheat Sheets, certificates and more!

Relevel

Reorder and combine levels of a factor

Description

The levels of a factor are re-ordered so that the levels specified by ref appear first and remaining levels are moved down. This is useful for contr.treatment contrasts which take the first level as the reference. Factor levels may also be combined; two possibilities for specifying this are supported: hard coding or table look-up.

Usage

## S3 method for class 'factor'
Relevel( x, ref, first = TRUE, collapse="+",
                 xlevels=TRUE, nogroup=TRUE, ... )

Arguments

`x`	A(n unordered) factor
`ref`	Vector, list or data frame, array, matrix or table. If `ref` is a vector (integer or character), it is assumed it contains the names or numbers of levels to be the first ones; non mentioned levels are kept. If `ref` is a list (but not a data frame), factor levels mentioned in each list element are combined. If the list is named the names are used as new factor levels, otherwise new level names are constructed from the old. If `ref` is a data frame or 2-dimensional array, matrix or table, the first column is assumed to have unique levels of `x` and the second to have groupings of this, respectively.
`first`	Should the levels mentioned in `ref` (if it is a list) come before those not?
`collapse`	String used when constructing names for combined factor levels.
`xlevels`	Logical. Should all levels in the 2nd column of `ref` be maintained as levels of the result, or (if `FALSE`) only the actually occurring.
`nogroup`	Logical. Should levels present in the input but not in the 1st column of `ref` be maintained as levels after the grouping? If `FALSE`, NAs will be returned for such elements.
`...`	Arguments passed on to other methods.

Details

The facility where ref is a two-column matrix mimics the SAS-facility of formats where a dataset can be used to construct a format — SAS format is the grouping tool for variable values.

If ref is a two-column object and ref[,2] is a factor Relevel will preserve the order of levels from ref[,2].

Value

An unordered factor, where levels of x have been reordered and/or collapsed.

Author(s)

Bendix Carstensen http://bendixcarstensen.com, Lars Jorge Diaz

Examples

# Grouping using a list (hard coding)
#
ff <- factor(sample(letters[1:5], 100, replace = TRUE))
table( ff, Relevel(ff, list( AB = 1:2, "Dee" = 4, c(3,5))))
table( ff, Relevel(ff,
                   list( 5:4, Z = c("c", "a") ),
                   coll = "-und-",
                   first = FALSE ) )

## Grouping using a two-column matrix as input:
## A factor with levels to be grouped together
ff <- factor(c("Bear","Bear","Crocodile","Snake","Crocodile","Bear"))
ff
## A grouping table
(gg <- data.frame(Animal = c("Bear","Whale","Crocodile","Snake","Eagle"),
                   Class = c("Mammal","Mammal","Reptile","Reptile","Bird")))
str(gg)
Relevel(ff, gg, xlevels = FALSE)
Relevel(ff, gg )
Relevel(ff, gg[c(1:5,5:1),])

## This crashes with an error
(GG <- rbind( gg, c("Bear","Reptile")))
try(Relevel(ff, GG))

ff <- factor(c(as.character(ff), "Jellyfish", "Spider"))
Relevel(ff, gg)
# excludes non-occupied levels
Relevel(ff, gg, xlevels = FALSE)
# If you do not want unknown animals classified, this returns NAs:
Relevel(ff, gg, nogroup = FALSE)
# Both
Relevel(ff, gg, nogroup = FALSE, xlevels = FALSE)

Epi

Statistical Analysis in Epidemiology

v2.44

GPL-2

Authors

Bendix Carstensen [aut, cre], Martyn Plummer [aut], Esa Laara [ctb], Michael Hills [ctb]

Initial release

2021-02-28