Relevel: Reorder and combine levels of a factor

Description Usage Arguments Details Value Author(s) See Also Examples

View source: R/Relevel.R

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

1
2
3
## 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. Using this facility will preserve the order of levels if ref[,2] is a factor.

Value

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

Author(s)

Bendix Carstensen, BendixCarstensen.com, Lars Jorge Diaz

See Also

Relevel.Lexis

Examples

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
# 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") ) )
Relevel( ff, gg, xlevels=FALSE )
Relevel( ff, gg )
Relevel( ff, gg[c(1:5,5:1),] )

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

ff <- factor(c(as.character(ff),"Jellyfish","Spider"))
Relevel( ff, gg )
Relevel( ff, gg, xlevels=FALSE )
# If you do not want unknown animals classified, this returns NAs:
Relevel( ff, gg, nogroup=FALSE )
# Will give error because re-classification is ambiguous
( GG <- rbind(gg,c("Eagle","Mammal"),c("Snake","Mammal")) )
try( Relevel( ff, GG ) )

Example output

   
ff  AB Dee c+e
  a 16   0   0
  b 26   0   0
  c  0   0  24
  d  0  17   0
  e  0   0  17
   
ff   b e-und-d  Z
  a  0       0 16
  b 26       0  0
  c  0       0 24
  d  0      17  0
  e  0      17  0
[1] Bear      Bear      Crocodile Snake     Crocodile Bear     
Levels: Bear Crocodile Snake
     Animal   Class
1      Bear  Mammal
2     Whale  Mammal
3 Crocodile Reptile
4     Snake Reptile
5     Eagle    Bird
[1] Mammal  Mammal  Reptile Reptile Reptile Mammal 
Levels: Mammal Reptile
[1] Mammal  Mammal  Reptile Reptile Reptile Mammal 
Levels: Bird Mammal Reptile
[1] Mammal  Mammal  Reptile Reptile Reptile Mammal 
Levels: Bird Mammal Reptile
Warning message:
In tRelevel(x, ref, xlevels, nogroup) :
  Factor levels: Bear / Crocodile / Eagle / Snake / Whale
appear more than once in the table of groupings.
Error in tRelevel(x, ref, xlevels, nogroup) : 
Factor level: 
Bear
is grouped to more than one group.

Note: Some values of factor not among levels grouped.
[1] Mammal    Mammal    Reptile   Reptile   Reptile   Mammal    Jellyfish
[8] Spider   
Levels: Bird Mammal Reptile Jellyfish Spider
Note: Some values of factor not among levels grouped.
[1] Mammal    Mammal    Reptile   Reptile   Reptile   Mammal    Jellyfish
[8] Spider   
Levels: Mammal Reptile Jellyfish Spider
Note: Some values of factor not among levels grouped.
[1] Mammal  Mammal  Reptile Reptile Reptile Mammal  <NA>    <NA>   
Levels: Bird Mammal Reptile
     Animal   Class
1      Bear  Mammal
2     Whale  Mammal
3 Crocodile Reptile
4     Snake Reptile
5     Eagle    Bird
6     Eagle  Mammal
7     Snake  Mammal
Error in tRelevel(x, ref, xlevels, nogroup) : 
Factor levels: 
Eagle / Snake
is grouped to more than one group.

Epi documentation built on Aug. 23, 2018, 9:04 a.m.