condition: Define a condition for a user-defined format

View source: R/fmt.R

conditionR Documentation

Define a condition for a user-defined format

Description

The condition function creates a condition for a user-defined format. It is typically used in conjunction with the value function.

Usage

condition(expr, label, order = NULL)

Arguments

expr

A valid R expression. The value in the expression is identified by the variable 'x', i.e. x == 'A' or x > 3 & x < 6. The expression should not be quoted. The expression parameter will accept equality, relational, and logical operators. It will also accept numeric or string literals. String literals should be quoted. It will not accept functions or any expression that includes a comma. For these more complex operations, it is best to use a vectorized function. See fapply for an example of a vectorized function.

label

A label to be assigned if the expression is TRUE. The label can any valid literal value. Typically, the label will be a character string. However, the label parameter does not restrict the data type. Meaning, the label could also be a number, date, or other R object type. The label may also be a string format, which allows you to perform conditional formatting.

order

An optional integer order number. When used, this parameter will effect the order of the labels returned from the labels.fmt function. The purpose of the parameter is to control ordering of the format labels independently of the order they are assigned in the conditions. The order parameter is useful when you are using the format labels to assign ordered levels in a factor.

Details

The condition function creates a condition as part of a format definition. The format is defined using the value function. The condition is defined as an expression/label pair. The expression parameter can be any valid R expression. The label parameter can be any valid literal. Conditions are evaluated in the order they are assigned. A default condition is created by assigning the expression parameter to TRUE. If your data can contain missing values, it is recommended that you test for those values first. Any data values that do not meet one of the conditions will fall through the format as-is.

The condition object is an S3 class of type "fmt_cond". The condition labels can be extracted from the format using the labels function.

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

Value

The new condition object.

See Also

fdata to apply formatting to a data frame, value to define a format, 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(), is.format(), labels.fmt(), print.fmt(), value()

Examples

# 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
v2 <- fapply(v1, fmt1)
v2
# [1] "Label A" "Label B" "Other"   "Label B"

dbosak01/fmtr documentation built on June 15, 2024, 4:26 a.m.