value {fmtr}

Create a user-defined format

Description

The value function creates a user-defined format.

Usage

value(..., log = TRUE, as.factor = FALSE)

Arguments

...

One or more condition functions.

log

Whether to log the creation of the format. Default is TRUE. This parameter is used internally.

as.factor

If TRUE, the fapply function will return the result as an ordered factor. Otherwise, the result will be returned as a vector. Default is FALSE.

Details

The value function creates a user defined format object, in a manner similar to a SAS® format. The value function accepts one or more condition arguments that define the format. The conditions map an R expression to a label. When applied, the format will return the label corresponding to the first true expression.

The format object is an S3 class of type "fmt". When the object is created, the levels attribute of the object will be set with a vector of values assigned to the labels property of the condition arguments. These labels may be accessed either from the levels function or the labels function. If no order has been assigned to the conditions, the labels will be returned in the order the conditions were passed to the value function. If an order has been assigned to the conditions, the labels will be returned in the order specified.

The format object may be applied to a vector using the fapply function. See fapply for further details.

Note that the label may also be a string format. That means a user-defined format can be used to apply string formats conditionally. This capability is useful when you want to conditionally format data values.

Value

The new format object.

See Also

condition to define a condition, levels or labels.fmt to access the labels, and fapply to apply the format to a vector.

Other fmt: as.data.frame.fmt(), as.fmt(), as.fmt.data.frame(), condition(), is.format(), labels.fmt(), print.fmt()

Examples

## Example 1: Character to Character Mapping ##
# Set up vector
v1 <- c("A", "B", "C", "B")

# Define format
fmt1 <- value(condition(x == "A", "Label A"),
              condition(x == "B", "Label B"), 
              condition(TRUE, "Other"))
              
# Apply format to vector
fapply(v1, fmt1)
# [1] "Label A" "Label B" "Other"   "Label B"

## Example 2: Character to Integer Mapping ##
fmt2 <- value(condition(x == "A", 1),
              condition(x == "B", 2),
              condition(TRUE, 3))

# Apply format to vector
fapply(v1, fmt2)
# [1] 1 2 3 2

## Example 3: Categorization of Continuous Variable ##
# Set up vector
v2 <- c(1, 6, 11, 7)

# Define format
fmt3 <- value(condition(x < 5, "Low"),
              condition(x >= 5 & x < 10, "High"), 
              condition(TRUE, "Out of range"))
              
# Apply format to vector
fapply(v2, fmt3)
# [1] "Low"          "High"         "Out of range" "High" 

### Example 4: Conditional formatting
v3 <- c(10.398873, 12.98762, 0.5654, 11.588372)

fmt4 <- value(condition(x < 1, "< 1.0"),
              condition(TRUE, "%.2f"))
              
fapply(v3, fmt4)
# [1] "10.40" "12.99" "< 1.0" "11.59"