cvam (version 0.9.3)

coarsened: Coarsened Factors

Description

A coarsened factor is an extended version of a factor or ordered factor whose elements may be fully observed, partially observed or missing. The partially-observed and missing states are represented by extra levels which are interpreted as groupings of the fully observed states. Coarsened factors are specifically designed for modeling with the cvam package.

Usage

coarsened(obj, levelsList = list(), warnIfCoarsened = TRUE)
is.coarsened(x)
# S3 method for coarsened
print(x, quote = FALSE, max.levels = NULL,
   width = getOption("width"), ...)
# S3 method for coarsened
droplevels(x, ...)
# S3 method for coarsened
relevel(x, ...)
# S3 method for coarsened
reorder(x, ...)
# S3 method for coarsened
rep(x, ...)
# S3 method for coarsened
[(x, ...)
# S3 method for coarsened
[[(x, ...)
# S3 method for coarsened
[(x, ...) <- value
# S3 method for coarsened
[[(x, ...) <- value

Value

coarsened returns a coarsened factor.

is.coarsened returns TRUE if x is a coarsened factor and FALSE otherwise.

Arguments

obj

a factor or ordered factor to be converted to a coarsened factor

levelsList

a named list that defines the groupings of levels(obj) to indicate states of partial knowledge

warnIfCoarsened

if TRUE, a warning is issued if obj is already a coarsened factor

x

a coarsened factor or other object

quote

logical, indicating whether or not strings should be printed with surrounding quotes

max.levels

integer, indicating how many base levels and coarse levels should be printed for a coarsened factor; if 0, no extra base levels or coarse levels lines will be printed. The default, NULL, entails choosing max.levels such that the base levels and coarse levels each print on one line of width width

width

only used when max.levels is NULL; see above

...

additional arguments passed to or from other methods

value

character: a set of levels for replacement

Author

Joe Schafer

Details

A coarsened factor, which inherits from class "factor" or c("ordered", "factor"), has two types of levels: base levels, which represent states of complete knowledge, and coarse levels, which represent states of incomplete knowledge. Each coarse level maps to two or more base levels. The mapping is defined by the argument levelsList.

For example, consider a factor whose levels are c("red", "notRed", "green", "yellow"), where "notRed" denotes an observation that is either "green" or "yellow". When the factor is converted to a coarsened factor, c("red", "green", "yellow") becomes the baseLevels, and "notRed" becomes an element of coarseLevels. To produce this result, the argument levelsList should have a component named "notRed", whose value is c("green", "yellow").

The last coarse level is NA, denoting an observation that could belong to any of the base levels. The NA coarse level is created automatically. Calling coarsened with an empty levelsList (the default) produces a coarsened factor with NA as its only coarse level.

If the main argument to coarsened is already a coarsened factor, then a warning is issued (if warnIfCoarsened is TRUE) and the coarsened factor is returned unchanged.

The generic functions droplevels, relevel, and reorder should not be applied to coarsened factors; the S3 methods droplevels.coarsened, relevel.coarsened, and reorder.coarsened will prevent this from happening.

rep.coarsened is a method for the generic function rep that ensures the special attributes of a coarsened factor are preserved.

Extraction and replacement methods `[` and `[[` are also provided to preserve the special attributes of coarsened factors.

References

For more information, refer to the package vignette Understanding Coarsened Factors in cvam.

See Also

cvam, is.naCoarsened, baseLevels, dropCoarseLevels

Examples

fac <- factor( c("red", "green", NA, "yellow", "notRed", "green") )
cFac <- coarsened( fac,
   levelsList = list("notRed" = c("green", "yellow")) )
print(cFac)
# extraction and replacement
print( cFac[2:3] )
cFac[2:3] <- c("NA", "green")