Create a user-defined format

The value function creates a user-defined format.

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.

Value

The new format object.

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.

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"))
#> # A user-defined format: 3 conditions
#>   Name Type Expression   Label Order
#> 1    x    U   x == "A" Label A    NA
#> 2    x    U   x == "B" Label B    NA
#> 3    x    U       TRUE   Other    NA
              
# Apply format to vector
fapply(v1, fmt1)
#> [1] "Label A" "Label B" "Other"   "Label B"
# [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))
#> # A user-defined format: 3 conditions
#>   Name Type Expression Label Order
#> 1    x    U   x == "A"     1    NA
#> 2    x    U   x == "B"     2    NA
#> 3    x    U       TRUE     3    NA

# Apply format to vector
fapply(v1, fmt2)
#> [1] 1 2 3 2
# [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"))
#> # A user-defined format: 3 conditions
#>   Name Type      Expression        Label Order
#> 1    x    U           x < 5          Low    NA
#> 2    x    U x >= 5 & x < 10         High    NA
#> 3    x    U            TRUE Out of range    NA
              
# Apply format to vector
fapply(v2, fmt3)
#> [1] "Low"          "High"         "Out of range" "High"        
# [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"))
#> # A user-defined format: 2 conditions
#>   Name Type Expression Label Order
#> 1    x    U      x < 1 < 1.0    NA
#> 2    x    U       TRUE  %.2f    NA
              
fapply(v3, fmt4)
#> [1] "10.40" "12.99" "< 1.0" "11.59"
# [1] "10.40" "12.99" "< 1.0" "11.59"