DescTools (version 0.99.16)

Format: Format Numbers and Dates

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 a special option is needed. This function wraps those functions and tries to offer a simpler, less technical, but still flexible interface.

Usage

Format(x, digits = NULL, sci = getOption("scipen"), big.mark="",
       leading = NULL, zero.form = NULL, na.form = NULL,
       fmt = NULL, align = NULL, width = NULL, lang = getOption("lang", "local"), ...)

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

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

## S3 method for class 'default':
Format(x, digits = NULL, sci = getOption("scipen"), big.mark="",
       leading = NULL, zero.form = NULL, na.form = NULL,
       fmt = NULL, align = NULL, width = NULL, lang = getOption("lang", "local"), ...)

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 wel

big.mark

character; if not empty used as mark between every 3 decimals before the decimal point.

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 nu

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 omitte

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 option "lang" will be searched for and if not found <

...

further arguments to be passed to or from methods.

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...)

Details

The argument fmt can be used for defining several formats. Dates 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: ll{ 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: lll{ Code e scientific forces scientific representation of x. The number of digits, alignment and zero values are respected. % 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. * 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 of all arguments of the function. This allows the full format to be stored in a variable or as an option and be used as format template subsequently. If we would want to use an user defined format for counts, we could define a format with a big mark and with 0 digits as: fmt.count <- structure(list(digits=0, big.mark="'"), class="fmt") and subsequently call the Format function with this format: Format(4231.2, fmt=fmt.count) which again would return the same as Format(4231.2, digits=0, big.mark="'").

See Also

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

Examples

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)