The fmtr package helps format data. The package aims to simulate the basic functionality of SAS® formats, but with R. The package contains several functions that make formatting simpler and more powerful.
fmtr contains the following key functions:
fdata()function to apply formatting to any data frame or tibble.
fapply()function to apply formatting to any vector.
fattr()functions to easily assign formatting attributes.
condition()functions to create a user-defined format.
fcat()function to create a format catalog.
flist()function to create a formatting list.
The fmtr package builds heavily on existing R formatting capabilities. For most R programmers, these functions are well-known, and widely used. The examples below make use of standard R formatting codes, such as those associated with the
sprintf() functions. The standard R formatting codes are a flexible and compact way of defining a format. If you are unfamiliar with R formatting codes, please see this summary on the
The simplest way to introduce the fmtr package is to examine the use of the
Note that the format parameter can also be assigned as an attribute on the vector. The
fapply() function will then pick up the format attribute, and apply it to the input vector. The result is the same:
Besides the format attribute, the
fapply() function will also recognize attributes for
justify. These parameters allow to you to control the width and alignment of the data in the vector. If the width parameter is larger than the width of the data, the value will be padded with spaces. Here is an example:
To help simplify assignment of these attributes, the fmtr package includes the
fattr() function, which allows you to set all the above attributes in one function call. Here is an example using the
fattr() function, that ends with the same result as the example above.
fapply() can accept several different types of formats. The examples above focus on a simple numeric format. But
fapply() also accepts date formats, a lookup list, a user-defined format, a vectorized function, and a formatting list.
Here is an example showing the use of a lookup list:
The weakness with using a named vector as a lookup list, as in the above example, is that it will fail if there are any NA values in the data. Additionally, there is no capability to include any sort of logic in the lookup.
A condition accepts an expression and a label. The expression determines which label is assigned. For the expression, you can use logical operators like “&” and “|”, and relational operators like “>” and “<”. The data value is identified with a variable “x”. Here is an example:
library(fmtr) # Create sample data vector v1 <- c("A", "B", "E", "A", NA, "C", "D") u1 <- value(condition(x == "A", "Group A"), condition(x == "B", "Group B"), condition(x == "C" | x == "D", "Group C/D"), condition(TRUE, "Other")) fapply(v1, u1) #  "Group A" "Group B" "Other" "Group A" "Other" "Group C/D" "Group C/D"
Notice that the user-defined format gives you much more capabilities than a simple lookup vector. It allows you to perform categorization, and assign a default. Additionally, the NA missing value does not crash the function. The NA simply falls into the default category. If there is no default category, any values which do not correspond to a category will fall through the format unaltered.
fdata() function works very much the same way as
fapply(), but with data frames and tibbles instead of vectors. In fact, under the hood,
fdata() is simply calling
fapply() for each column in the data frame.
fapply() function, formatting may be assigned to data frame columns using the format, width, and justify attributes. Formatting is then applied by calling the
fdata() function, and passing the data frame as the first parameter.
fdata() will then return a new data frame with the specified formatting applied. This method of formatting provides much greater control than the base R
library(fmtr) # Construct data frame from state vectors df <- data.frame(state = state.abb, area = state.area)[1:10, ] # Calculate percentages df$pct <- df$area / sum(state.area) * 100 # Before formatting df # state area pct # 1 AL 51609 1.42629378 # 2 AK 589757 16.29883824 # 3 AZ 113909 3.14804973 # 4 AR 53104 1.46761040 # 5 CA 158693 4.38572418 # 6 CO 104247 2.88102556 # 7 CT 5009 0.13843139 # 8 DE 2057 0.05684835 # 9 FL 58560 1.61839532 # 10 GA 58876 1.62712846 # Create state name lookup list name_lookup <- state.name names(name_lookup) <- state.abb # Assign formats formats(df) <- list(state = name_lookup, area = function(x) format(x, big.mark = ","), pct = "%.1f%%") # Apply formats fdata(df) # state area pct # 1 Alabama 51,609 1.4% # 2 Alaska 589,757 16.3% # 3 Arizona 113,909 3.1% # 4 Arkansas 53,104 1.5% # 5 California 158,693 4.4% # 6 Colorado 104,247 2.9% # 7 Connecticut 5,009 0.1% # 8 Delaware 2,057 0.1% # 9 Florida 58,560 1.6% # 10 Georgia 58,876 1.6%
In the above example, observe that the
formats() function assigns the format attribute for multiple columns. This assignment is accomplished by sending a named list into the
formats() function, where the names in the list correspond to the column names of the data frame. Also note the use of a lookup style format for the state names, and an anonymous vectorized format function for the state area.
One of the benefits of the above method of formatting is that the data frame attributes can be stored with the data frame, and reapplied in the future. But what if you want to apply the same set of formats to a different data frame?
That is where you need a format catalog.
The format catalog is a collection of formats that can be saved and reused. A format catalog is created with an
fcat() function. To create a format catalog, you call the
fcat() function, passing a set of name/format pairs. In this case, the name of the format is a generic format name. It does not have to correspond to a column name. You may name the formats anything you want. The formats can be accessed in the catalog using dollar sign (“$”) list notation.
library(fmtr) # Construct data frame from state vectors df <- data.frame(state = state.abb, area = state.area)[1:10, ] # Calculate percentages df$pct <- df$area / sum(state.area) * 100 # Before formatting df # state area pct # 1 AL 51609 1.42629378 # 2 AK 589757 16.29883824 # 3 AZ 113909 3.14804973 # 4 AR 53104 1.46761040 # 5 CA 158693 4.38572418 # 6 CO 104247 2.88102556 # 7 CT 5009 0.13843139 # 8 DE 2057 0.05684835 # 9 FL 58560 1.61839532 # 10 GA 58876 1.62712846 # Create state name lookup list name_lookup <- state.name names(name_lookup) <- state.abb # Assign formats to format catalog cat1 <- fcat(state = name_lookup, area = function(x) format(x, big.mark = ","), pct = "%.1f%%") # Apply a format from the catalog using fapply fapply(df$pct, cat1$pct) #  "1.4%" "16.3%" "3.1%" "1.5%" "4.4%" "2.9%" "0.1%" "0.1%" "1.6%" "1.6%" # Assign formats from the catalog to format attributes formats(df) <- cat1 # Apply formats fdata(df) # state area pct # 1 Alabama 51,609 1.4% # 2 Alaska 589,757 16.3% # 3 Arizona 113,909 3.1% # 4 Arkansas 53,104 1.5% # 5 California 158,693 4.4% # 6 Colorado 104,247 2.9% # 7 Connecticut 5,009 0.1% # 8 Delaware 2,057 0.1% # 9 Florida 58,560 1.6% # 10 Georgia 58,876 1.6%
In normal use, of course, the format catalog would likely be created in a separate script and saved to a file using the
write.fcat() function. The format catalog can then be read by any number of programs using the
read.fcat() function, and the formats in the catalog can be applied as needed to your data.