---
title: "Format Apply Function"
date: "`r Sys.Date()`"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Format Apply Function}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r setup, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>"
)
```
### How to use fapply()

The `fapply()` function applies a format to a vector, factor, or list. 
This function 
may be used independently of the `fdata()` function.  Here is an example:
```{r eval=FALSE, echo=TRUE} 
v1 <- c("A", "B", "C", "B")
v1

# [1] "A" "B" "C" "B"

fmt1 <- value(condition(x == "A", "Label A"),
              condition(x == "B", "Label B"),
              condition(TRUE, "Other"))

fapply(v1, fmt1)

# "Label A" "Label B"   "Other" "Label B" 

```
One advantage of using `fapply()` is that your original data is not
altered. The formatted values are assigned to a new object. If your 
original data changes, the formatting function should be reapplied 
to maintain consistency with the original data.

## What kind of formats are available
Data can be formatted with several different types of objects:

  * A formatting string
  * A named vector
  * A user-defined format
  * A vectorized function
  * A formatting list

You can use the type of formatting object that is most suitable to 
your data and situation.  Each type of formatting object has it's own 
strengths and weaknesses.

#### Formatting String
The formatting functions accept formatting strings such as those associated
with the Base R `format()` and `sprintf()` functions.  If the data type of the 
vector is a date or datetime, `fapply()` will use the format codes associated 
with the `format()` function.  For other data types, `fapply()` will use the format
codes associated with `sprintf`.  Here is an example:
```{r eval=FALSE, echo=TRUE} 
v1 <- c(1.367, 8.356, 4.583, 2.873)

fapply(v1, "%.1f%%")

[1] "1.4%" "8.4%" "4.6%" "2.9%"

```

#### Named vectors
Data may be formatted using a named vector as a lookup.  Simply ensure that 
the names on the formatting vector correspond to the values in the data vector.  
The advantage
of using a named vector for formatting is its simplicity.  The disadvantage
is that it only works with character values. Here is an 
example of formatting using a named vector:
```{r eval=FALSE, echo=TRUE} 
v1 <- c("A", "B", "C", "B")

fmt1 <- c(A = "Label A", B = "Label B", C= "Label C")

fapply(v1, fmt1)

# "Label A" "Label B" "Label C" "Label B" 

```
#### User-defined formats
The **fmtr** package provides custom functions for creating user-defined 
formats, in a manner that is similar to a SAS® user-defined format.
These functions are `value()` and `condition()`.
The `value()` function accepts one or more conditions.  The `condition()`
function accepts an expression/label pair.  A user-defined format has the 
advantage of a clear and flexible syntax.  It is excellent for categorizing
data.  Here is an example of a user-defined 
format:
```{r eval=FALSE, echo=TRUE} 
v1 <- c("A", "B", NA, "C")

fmt2 <- value(condition(is.na(x), "Missing"),
              condition(x == "A", "Label A"),
              condition(x == "B", "Label B"),
              condition(TRUE, "Other"))
              
fapply(v1, fmt2)

# "Label A" "Label B"   "Missing" "Other" 

```
The user-defined format may also be used to format values conditionally.
Conditional formatting is accomplished by using a formatting string
as the label. The following example formats a numeric value two decimal
places, unless it exceeds a specified range.
```{r eval=FALSE, echo=TRUE} 
v2 <- c(18.3987, 15.45852, 8.9835, 11.246246, 25.3858, NA)

fmt3 <- value(condition(is.na(x), "Missing"),
              condition(x < 10, "Low"),
              condition(x > 20, "High"),
              condition(TRUE, "%.2f"))
              
fapply(v2, fmt3)

# [1] "18.40"   "15.46"   "Low"     "11.25"   "High"    "Missing"
```

#### Vectorized functions
Vectorized functions provide the most powerful way of formatting 
data.  Vectorized functions can be user-defined, or wrapping an 
available packaged function.  The vectorized function has the advantage 
of being nearly limitless
in the types of formatting you can perform.  The drawback is that a 
vectorized function can be more complicated to write.  Here is an 
example of formatting 
with a user-defined, vectorized function:
```{r eval=FALSE, echo=TRUE} 
v1 <- c("A", "B", NA, "C")

fmt2 <- Vectorize(function(x) {
    
    if (is.na(x)) 
      ret <- "Missing"
    else if (x %in% c("A", "B"))
      ret <- paste("Label", x)
    else 
      ret <- "Other"
    
    return(ret)
    
  })
  
fapply(v1, fmt2)

# "Label A" "Label B"   "Missing" "Other" 

```

#### A formatting list
Sometimes data needs to be formatted differently for each row.  This 
situation is difficult to deal with in any language.  
But it can be made easy in R with the **fmtr** package and a formatting list.

A formatting list is a list that contains one or more of the four types
of formatting objects described above.  It is defined with the `flist()` 
function. A formatting list can be applied in 
two different ways: in order, or with a lookup.  

By default, the 
list is applied in order.  That means the first format in the list is 
applied to the first item in the vector, the second format in the list is 
applied to the second item in the vector, and so on.  The list is recycled 
if the number of list items is shorter than the number of values in the 
vector.

For the lookup method, the formatting object is specified by a lookup vector. 
The lookup vector should contain names 
associated with the elements in the formatting list. The lookup vector should 
also contain the same number of items as the data vector.  For each item
in the data vector, **fmtr** will look up the appropriate format
from the formatting list, and apply that format to the
corresponding data value.

The following is an example of a lookup style formatting list:
```{r eval=FALSE, echo=TRUE} 
# Set up data
v1 <- c("num", "char", "date", "char", "date", "num")
v2 <- list(1.258, "H", as.Date("2020-06-19"),
           "L", as.Date("2020-04-24"), 2.8865)

df <- data.frame(type = v1, values = I(v2))
df

#    type     values
# 1   num      1.258
# 2  char          H
# 3  date 2020-06-19
# 4  char          L
# 5  date 2020-04-24
# 6   num     2.8865

# Set up formatting list
lst <- flist(type = "row", lookup = v1,
             num = "%.1f",
             char = value(condition(x == "H", "High"),
                          condition(x == "L", "Low"),
                          condition(TRUE, "NA")),
             date = "%y-%m")

# Assign formatting list to values column
attr(df$values, "format") <- lst


# Apply formatting
fdata(df)

#   type values
# 1  num    1.3
# 2 char   High
# 3 date  20-06
# 4 char    Low
# 5 date  20-04
# 6  num    2.9


```

Next: [Format Catalogs](fmtr-fcat.html)
