Format: Format Numbers and Dates

Description Usage Arguments Details Value Author(s) See Also Examples

View source: R/DescTools.r

Description

Formatting numbers in R often degenerates into a major intellectual challenge for us little guys. We have several functions available and quite often it's hard to work out which one to use, when an uncommon option is needed. This function wraps those functions and tries to offer a simpler, less technical, but still flexible interface.

There's also an easygoing interface for format templates, defined as a list consisting of any accepted format features. In this way templates can be defined outside and may easily be changed or modified later.

Usage

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
Format(x, digits = NULL, sci = NULL, big.mark = NULL,
       leading = NULL, zero.form = NULL, na.form = NULL,
       fmt = NULL, align = NULL, width = NULL, lang = NULL, ...)

## S3 method for class 'table'
Format(x, digits = NULL, sci = NULL, big.mark = NULL,
       leading = NULL, zero.form = NULL, na.form = NULL,
       fmt = NULL, align = NULL, width = NULL, lang = NULL, ...)

## S3 method for class 'matrix'
Format(x, digits = NULL, sci = NULL, big.mark = NULL,
       leading = NULL, zero.form = NULL, na.form = NULL,
       fmt = NULL, align = NULL, width = NULL, lang = NULL, ...)

## Default S3 method:
Format(x, digits = NULL, sci = NULL, big.mark = NULL,
       leading = NULL, zero.form = NULL, na.form = NULL,
       fmt = NULL, align = NULL, width = NULL, lang = NULL, ...)

Fmt(...)

as.fmt(...)

as.CDateFmt(fmt)

Arguments

x

an atomic numerical, typically a vector of real numbers or a matrix of numerical values. Factors will be converted to strings.

digits

integer, the desired (fixed) number of digits after the decimal point. Unlike formatC you will always get this number of digits even if the last digit is 0.

sci

integer. The power of 10 to be set when deciding to print numeric values in exponential notation. Fixed notation will be preferred unless the number is larger than 10^scipen. If just one value is set it will be used for the left border 10^(-scipen) as well as for the right one (10^scipen). A negative and a positive value can also be set independently. Default is getOption("scipen").

big.mark

character; if not empty used as mark between every 3 decimals before the decimal point. Default is "" (none).

leading

character string that can be used for setting leading zeros. "000" would make sure that at least 3 digits on the left side will be printed. Setting leading to "drop" will yield results like ".452" for 0.452. The default NULL will leave the numbers as they are.

zero.form

character, string specifying how zeros should be specially formatted. Useful for pretty printing 'sparse' objects. If set to NULL (default) no special action will be taken.

na.form

character, string specifying how NAs should be specially formatted. If set to NULL (default) no special action will be taken.

fmt

either a format string, allowing to flexibly define special formats or an object of class fmt, consisting of a list of Format arguments. See Details.

align

the character on whose position the strings will be aligned. Left alignment can be requested by setting sep = "\\l", right alignment by "\\r" and center alignment by "\\c". Mind the backslashes, as if they are omitted, strings would be aligned to the character l, r or c respectively. The default is NULL which would just leave the strings as they are.
This argument is send directly to the function StrAlign() as argument sep.

width

integer, the defined width of the strings.

lang

optional value setting the language for the months and daynames. Can be either "local" for current locale or "engl" for english. If left to NULL, the DescToolsOption "lang" will be searched for and if not found "local" will be taken as default.

...

further arguments to be passed to or from methods.

Details

Format() is used to format numbers. Fmt() can be used to display existing or define new format templates. as.fmt() will convert a list to a format object (class fmt).

The argument fmt can be used be used to generate different formats. When x is a date, it can be formatted with any combination of the format codes d, m and y for day, month or year. Repeting the specific code defines the degree of abbreviation:

Date codes
d day of the month without leading zero (1 - 31)
dd day of the month with leading zero (01 - 31)
ddd abbreviated name for the day of the week (e.g. Mon) in the current user's language
dddd full name for the day of the week (e.g. Monday) in the current user's language
m month without leading zero (1 - 12)
mm month with leading zero (01 - 12)
mmm abbreviated month name (e.g. Jan) in the current user's language
mmmm full month name (e.g. January) in the current user's language
y year without century, without leading zero (0 - 99)
yy year without century, with leading zero (00 - 99)
yyyy year with century. For example: 2005

For numeric values there are the following special codes:

Code
e scientific forces scientific representation of x. The number of digits, alignment
and zero values are respected.
eng engineering forces scientific representation of x, but only with powers that are a multiple of 3.
engabb engineering abbr. same as eng, but replaces the exponential representation by codes. See d.prefix.
% percent will divide the given number by 100 and append the %-sign (without a separator).
p p-value will wrap the function format.pval and return a p-value format.
frac fractions will try to convert numbers to fractions. See fractions().
* significance will produce a significance representation of a p-value consisting of * and .,
while the breaks are set according to the used defaults e.g. in lm as
[0, 0.001] = ***
(0.001, 0.01] = **
(0.01, 0.05] = *
(0.05, 0.1] = .
(0.1,1] =

fmt can as well be an object of class fmt consisting of a list out of the arguments above. This allows to store the full format in a variable or as an option and use it as format template subsequently.
If we would want to define a format for counts, we could create a list with a big mark and with 0 digits and subsequently call the Format function with this format:

fmt.count <- as.fmt(digits=0, big.mark="'")
Format(4231.2, fmt=fmt.count)

where the latter returns the same result as if the arguments would have been supplied directly:
Format(4231.2, digits=0, big.mark="'").

The formats can as well be organized as options. DescToolsOptions("fmt") would display the currently defined formats. The function Fmt() can be used to get, modify and store new formats in dependency of the arguments given. See examples.

Value

the formatted values as characters.
If x was a matrix, then a the result will also be a matrix. (Hope this will not surprise you...)

Author(s)

Andri Signorell <[email protected]>

See Also

format, formatC, prettyNum, sprintf, symnum,
StrAlign, StrPad, Sys.setlocale,
Weekday, Month, DescToolsOptions

Examples

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
Format(as.Date(c("2014-11-28", "2014-1-2")), fmt="ddd, d mmmm yyyy")
Format(as.Date(c("2014-11-28", "2014-1-2")), fmt="ddd, d mmmm yyyy", lang="engl")

x <- pi * 10^(-10:10)

Format(x, digits=3, fmt="%", sci=NA)
Format(x, digits=4, sci=c(4, 6), leading = "drop", width=9, align=".")


# format a matrix
m <- matrix(runif(100), nrow=10,
            dimnames=list(LETTERS[1:10], LETTERS[1:10]))

Format(m, digits=1)

# engineering format
Format(x, fmt="eng",  digits=2)
Format(x, fmt="engabb", leading="00", digits=2)
# combine with grams [g]
paste(Format(x, fmt="engabb", leading="00", digits=2), "g", sep="")

# example form symnum
pval <- rev(sort(c(outer(1:6, 10^-(1:3)))))
noquote(cbind(Format(pval, fmt="p"), Format(pval, fmt="*")))

# use Fmt() to get and define new formats stored as option
Fmt()                        # all defined formats
Fmt("abs")                   # only format named "abs"
Fmt("nexist")                # only format named "nexist" (nonexisting)
Fmt("abs", "per", "nexist")
Fmt("abs", digits=3)         # get Fmt("abs") and overwrite digits
Fmt("abs", na.form="-")      # get Fmt("abs") and add user defined na.form

# define totally new format and store as option
Fmt(nob=as.fmt(digits=10, na.form="nodat"))

# overwrite an existing format
Fmt(nob=Fmt("nob", digits=5))
Fmt("nob")

# change the character to be used as the decimal point
opt <- options(OutDec=",")
Format(1200, digits=2, big.mark = ".")
options(opt)

Example output

[1] Fri, 28 November 2014  Thu,  2 January 2014
[1] Fri, 28 November 2014  Thu,  2 January 2014
 [1]             0.000%             0.000%             0.000%             0.000%
 [5]             0.000%             0.003%             0.031%             0.314%
 [9]             3.142%            31.416%           314.159%          3141.593%
[13]         31415.927%        314159.265%       3141592.654%      31415926.536%
[17]     314159265.359%    3141592653.590%   31415926535.898%  314159265358.979%
[21] 3141592653589.793%
 [1]    3.1416e-10    3.1416e-09    3.1416e-08    3.1416e-07     .0000    
 [6]     .0000         .0003         .0031         .0314         .3142    
[11]    3.1416       31.4159      314.1593     3141.5927        3.1416e+04
[16]    3.1416e+05    3.1416e+06    3.1416e+07    3.1416e+08    3.1416e+09
[21]    3.1416e+10
    A   B   C   D   E   F   G   H   I   J
A 0.4 0.0 0.5 0.8 0.4 0.1 0.5 0.0 0.5 0.7
B 0.1 0.4 0.9 0.4 0.5 0.6 0.5 0.3 0.9 0.0
C 0.4 0.8 0.6 0.0 0.5 0.7 0.1 0.2 0.9 0.2
D 0.7 0.4 0.9 0.9 0.5 0.6 0.3 0.9 0.8 0.1
E 0.6 0.3 0.5 0.8 0.1 0.3 0.8 0.9 0.3 0.9
F 0.0 0.2 0.3 0.5 0.4 0.5 0.9 0.2 0.5 0.2
G 0.9 0.9 0.1 0.8 0.3 0.4 0.4 0.7 0.7 1.0
H 0.4 0.0 0.5 0.2 0.3 0.7 0.0 0.1 0.3 0.6
I 0.7 0.2 0.5 0.0 1.0 0.6 0.0 0.4 0.3 0.8
J 0.5 0.3 0.5 0.3 0.7 0.9 1.0 0.6 0.4 0.2
 [1] 314.16e-12   3.14e-09  31.42e-09 314.16e-09   3.14e-06  31.42e-06
 [7] 314.16e-06   3.14e-03  31.42e-03 314.16e-03   3.14e+00  31.42e+00
[13] 314.16e+00   3.14e+03  31.42e+03 314.16e+03   3.14e+06  31.42e+06
[19] 314.16e+06   3.14e+09  31.42e+09
 [1] 314.16 p  03.14 n  31.42 n 314.16 n  03.14 u  31.42 u 314.16 u  03.14 m
 [9]  31.42 m 314.16 m   03.14    31.42   314.16   03.14 k  31.42 k 314.16 k
[17]  03.14 M  31.42 M 314.16 M  03.14 G  31.42 G
 [1] "314.16 pg" "03.14 ng"  "31.42 ng"  "314.16 ng" "03.14 ug"  "31.42 ug" 
 [7] "314.16 ug" "03.14 mg"  "31.42 mg"  "314.16 mg" "03.14 g"   "31.42 g"  
[13] "314.16 g"  "03.14 kg"  "31.42 kg"  "314.16 kg" "03.14 Mg"  "31.42 Mg" 
[19] "314.16 Mg" "03.14 Gg"  "31.42 Gg" 
      [,1]  [,2]
 [1,] 0.600     
 [2,] 0.500     
 [3,] 0.400     
 [4,] 0.300     
 [5,] 0.200     
 [6,] 0.100 .   
 [7,] 0.060 .   
 [8,] 0.050 *   
 [9,] 0.040 *   
[10,] 0.030 *   
[11,] 0.020 *   
[12,] 0.010 **  
[13,] 0.006 **  
[14,] 0.005 **  
[15,] 0.004 **  
[16,] 0.003 **  
[17,] 0.002 **  
[18,] 0.001 *** 
$abs
Format name:    abs (default)
 Description:   Number format for counts
 Definition:    digits=0, big.mark="'"
 Example:       314'159

$per
Format name:    per (default)
 Description:   Percentage number format
 Definition:    digits=1, fmt="%"
 Example:       31415926.5%

$num
Format name:    num (default)
 Description:   Number format for floats
 Definition:    digits=3, big.mark="'"
 Example:       314'159.265

Format name:    abs (default)
 Description:   Number format for counts
 Definition:    digits=0, big.mark="'"
 Example:       314'159
NULL
$abs
Format name:    abs (default)
 Description:   Number format for counts
 Definition:    digits=0, big.mark="'"
 Example:       314'159

$per
Format name:    per (default)
 Description:   Percentage number format
 Definition:    digits=1, fmt="%"
 Example:       31415926.5%

$<NA>
NULL

Format name:    abs (default)
 Description:   Number format for counts
 Definition:    digits=3, big.mark="'"
 Example:       314'159.265
Format name:    abs (default)
 Description:   Number format for counts
 Definition:    digits=0, big.mark="'", na.form="-"
 Example:       314'159
$abs
Format name:    abs (default)
 Description:   Number format for counts
 Definition:    digits=0, big.mark="'"
 Example:       314'159

$per
Format name:    per (default)
 Description:   Percentage number format
 Definition:    digits=1, fmt="%"
 Example:       31415926.5%

$num
Format name:    num (default)
 Description:   Number format for floats
 Definition:    digits=3, big.mark="'"
 Example:       314'159.265

$nob
Format name:    nob
 Description:   Number format
 Definition:    digits=10, na.form="nodat"
 Example:       314159.2653589793

$abs
Format name:    abs (default)
 Description:   Number format for counts
 Definition:    digits=0, big.mark="'"
 Example:       314'159

$per
Format name:    per (default)
 Description:   Percentage number format
 Definition:    digits=1, fmt="%"
 Example:       31415926.5%

$num
Format name:    num (default)
 Description:   Number format for floating points
 Definition:    digits=0, big.mark="'"
 Example:       314'159

Format name:    nob
 Description:   Number format
 Definition:    digits=5, na.form="nodat"
 Example:       314159.26536
[1] 1.200,00

DescTools documentation built on March 19, 2018, 9:03 a.m.