`vignettes/introduction.Rmd`

`introduction.Rmd`

This package is designed for applying formatting on vectors and data frames to make data presentation easier, richer, more flexible and hopefully convey more information.

Atomic vectors are fundamental data structures in R. Some data can be read more easily with formatting. A numeric vector, for example, stores percentage numbers but is printed as typical floating numbers. This package provides functions to create data structures with predefined formatting rules so that these objects store the original data but are printed with formatting.

Several typical formattable numeric vectors are provided such as
`percent`

, `comma`

, `currency`

,
`accounting`

and `scientific`

. These functions
basically create numeric vectors with pre-defined formatting rules and
parameters. For example,

```
library(formattable)
p <- percent(c(0.1, 0.02, 0.03, 0.12))
p
```

`## [1] 10.00% 2.00% 3.00% 12.00%`

The percent vector is no different from a numeric vector but has a percentage representation when printed. It works with arithmetic operations and other common functions and preserves its formatting.

`p + 0.05`

`## [1] 15.00% 7.00% 8.00% 17.00%`

`p + percent(0.02)`

`## [1] 12.00% 4.00% 5.00% 14.00%`

`p * 1.1`

`## [1] 11.00% 2.20% 3.30% 13.20%`

`max(p)`

`## [1] 12.00%`

`mean(p)`

`## [1] 6.75%`

It also works with subsetting and sub-assignment:

`p[1:3]`

`## [1] 10.00% 2.00% 3.00%`

`p[[2]]`

`## [1] 2.00%`

```
p[[3]] <- 0.05
p
```

`## [1] 10.00% 2.00% 5.00% 12.00%`

```
balance <- accounting(c(1000, 500, 200, -150, 0, 1200))
balance
```

`## [1] 1,000.00 500.00 200.00 (150.00) 0.00 1,200.00`

`balance + 1000`

`## [1] 2,000.00 1,500.00 1,200.00 850.00 1,000.00 2,200.00`

These functions are specialized applications of what
`formattable()`

is designed to do. `formattable()`

applies customizable formatting functions to objects of a wide range of
classes like `numeric`

, `logical`

,
`factor`

, `Date`

, `data.frame`

,
etc.

When applied to `Date`

, `formattable()`

uses
`format.Date()`

as the default formatter function. The
following code creates a `formattable Date`

vector that is
printed in the format of `%Y%m%d`

. However, it is not a plain
integer or character vector but of `Date`

class and still
allows date calculations.

```
dates <- formattable(as.Date(c("2016-05-01", "2016-05-10")), format = "%Y%m%d")
dates
```

`## [1] 20160501 20160510`

`dates + 30`

`## [1] 20160531 20160609`

When applied to a logical vector, we can customize how
`TRUE`

and `FALSE`

values are printed.

```
lv <- formattable(c(TRUE, FALSE, FALSE, TRUE), "yes", "no")
lv
```

`## [1] yes no no yes`

`!lv`

`## [1] no yes yes no`

Note that `isTRUE()`

does not directly work with values of
`lv`

because `isTRUE()`

uses
`identical(x, TRUE)`

and `lv[[1]]`

, as a
formattable logical value is not identical to a plain
`TRUE`

.

`lv[[1]]`

`## [1] yes`

`isTRUE(lv[[1]])`

`## [1] TRUE`

If `isTRUE()`

has to be applied, `lv == TRUE`

returns a plain logical vector and works with `isTRUE()`

.
Other vectorized logical functions directly work with formattable
logical vector with the formatting preserved.

`all(lv)`

`## [1] no`

`any(lv)`

`## [1] yes`

All formattable functions work with matrices and arrays.

```
## X Y Z
## a 0.7439524 0.9558708 0.8129288
## b 0.7769823 0.8070508 0.9715065
```

```
fpm <- percent(pm)
fpm
```

```
## X Y Z
## a 74.40% 95.59% 81.29%
## b 77.70% 80.71% 97.15%
```

`fpm["a", c("Y", "Z")]`

```
## Y Z
## 95.59% 81.29%
```

```
## , , 1
##
## [,1] [,2] [,3]
## [1,] 0.8460916 0.7313147 0.9224082
## [2,] 0.6734939 0.7554338 0.8359814
##
## , , 2
##
## [,1] [,2] [,3]
## [1,] 0.8400771 0.7444159 0.8497850
## [2,] 0.8110683 0.9786913 0.6033383
```

`percent(pa)`

```
## , , 1
##
## [,1] [,2] [,3]
## [1,] 84.61% 73.13% 92.24%
## [2,] 67.35% 75.54% 83.60%
##
## , , 2
##
## [,1] [,2] [,3]
## [1,] 84.01% 74.44% 84.98%
## [2,] 81.11% 97.87% 60.33%
```

When the formattable vectors are used as columns of a data frame, the
formatting of each column is well preserved. A typical data frame may
look more friendly with `formattable`

column vectors. For
example,

```
p <- data.frame(
id = c(1, 2, 3, 4, 5),
name = c("A1", "A2", "B1", "B2", "C1"),
balance = accounting(c(52500, 36150, 25000, 18300, 7600), format = "d"),
growth = percent(c(0.3, 0.3, 0.1, 0.15, 0.15), format = "d"),
ready = formattable(c(TRUE, TRUE, FALSE, FALSE, TRUE), "yes", "no"))
p
```

```
## id name balance growth ready
## 1 1 A1 52,500 30% yes
## 2 2 A2 36,150 30% yes
## 3 3 B1 25,000 10% no
## 4 4 B2 18,300 15% no
## 5 5 C1 7,600 15% yes
```

The subset of a data frame also preserves the formatting of each column:

`p[1:3, c("name", "balance", "growth")]`

```
## name balance growth
## 1 A1 52,500 30%
## 2 A2 36,150 30%
## 3 B1 25,000 10%
```