DescTools (version 0.99.13)

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, 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 = "left", width = NULL, ...)

## 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 = "left", width = NULL, ...)

## 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 = "left", width = NULL, ...)

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

Arguments

x

an atomic numerical, typically a vector of real numbers or a matrix of numerical values.

digits

integer, the desired 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 fixed or 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^(-scipe

big.mark

character; if not empty used as mark between every big.interval decimals before (hence big) 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 formatted specially. 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 formatted specially. If set to NULL (default) no special action will be taken.

fmt

a format string, allowing to flexibly define special formats. See Details.

align

one out of "left", "right", "center", "dec". The values can be aligned left, right, center or at the decimal point. The default is NULL which would just leave the strings as they are.

width

integer, the defined width of the strings.

...

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. ll{ dates Dates can be formatted with the format codes d, m and y for day, month or year. Repeting the specific code defines the degree of abbreviation: 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 } ll{ scientific fmt = "e" forces scientific representation of x. The number of digits, alignment and zero values will be respected. percent Setting fmt = "%" will divide the given number by 100 and append the %-sign (without separator). p-value fmt = "p" will wrap the function format.pval. significance The significance representation of a p-value consisting of * and . will be produced by setting fmt = "*". 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 format to be stored in a variable or as an option and be used as format template subsequently. If we would want to define an own format for counts, we would write: fmt.count <- structure(list(digits=0, big.mark="'"), class="fmt") 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

Examples

Format(as.Date(c("2014-11-28", "2014-1-2")), fmt="ddd, d mmmm yyyy")

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

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


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

Format(m, digits=1)