pprop: Approximations of proportions that look pretty and are easy...
In prettyprint/prettyprint: Don't Just Print, Pretty Print

Description Usage Arguments Details Value Methods (by generic) References See Also Examples

User friendly descriptions of proportions.

pprop(prop, char = getOption("pprop.char"),
  char.method = getOption("pprop.char.method"),
  fixed.divisors = getOption("pprop.fixed.divisors"),
  simple.signif.digits = getOption("pprop.simple.signif.digits"),
  simple.max.num = getOption("pprop.simple.max.num"),
  h = getOption("pprop.h"))

## S3 method for class 'pprop'
as.character(x, char.method = getOption("pprop.char.method"),
  ...)

## S3 method for class 'pprop'
as.double(x, ...)

`prop`	A proportion or vector of proportions. Must be between 0 and 1.
`char`	TRUE (default) = return a character vector. FALSE = return objects of class `pprop`, which contain more information. NA = FALSE if `prop` is a singleton, TRUE if `prop` has more than one element.
`char.method`	Which proportion approximation method to default to when `char = TRUE`? Possibilities are "fixed" (default) and "simple". "fixed" gives more user-friendly results, "simple" gives more exact results.
`fixed.divisors`	For the "fixed" proportion approximation method, a vector of possible denominators. Only these denominators can be used in the approximation.
`simple.signif.digits`	For the "simple" proportion approximation method, the number of significant digits in the denominator. Default = 1.
`simple.max.num`	For the "simple" proportion approximation method, a value used in calculating the numerator. The maximum value of the numerator is approximately this, though it could be a little higher.
`h`	A list of cutoffs to determine how close the proportion is to the approximate proportion. Must have the following elements: `eq`, `about`, `ok`. See Details for an explanation.
`x`	Output of `pprop` when `char = FALSE`.
`...`	Ignored.

Generally, you just need to supply a proportion, or a vector of proportions, which must be between 0 and 1. The approximate proportions may contain a descriptive prefix. This prefix indicates the distance between the proportion and the approximate proportion.

When char = NA, then consider the length of the input (and the output). If length > 1, then return just the character representations of the proportions. This allows, for example, adding a column to a data.frame with these descriptions. When length == 1, return an object of class pprop, which contains more information.

When returning a character, use the char.method proportion approximation method. However, if that method gives an answer that is not satisfactory – the distance between the proportion and its approximation is too high – then use the method with the lowest distance.

The two methods are "fixed" and "simple". In "fixed", only the denominators specified in fixed.divisors are allowed. This is the more user-friendly method, though it might not give a good approximation when the proportion is close to 0 or to 1. This can be remedied by allowing more denominators, by changing fixed.divisors.

In the "simple" method, numerators between 0 and approximately simple.max.num are allowed. Denominators have simple.signif.digits significant digits. This method is more exact but less user friendly.

With default parameter values, the "fixed" method is used. When it does not perform well, which is near 0 and 1, the "simple" method is used automatically.

The distance between a proportion and its approximation is measured using Cohen's h effect size. h is a list that must contain 3 elements: eq, about, ok. If h between a proportion and its approximation is less than eq, then they are so close that no descriptive prefix is used. If h is between eq and about, then the "about" prefix is used. If h is between about and ok then the "more than" / "less than" language is used. If h is greater than ok, then the approximation is considered to be too far away from the proportion. According to Cohen's rule of thumb, h < 0.20 indicates that the difference between two proportions is trivial. Therefore, by default, h$ok = 0.20.

If char = TRUE, return a character vector. If char = FALSE, return objects of class pprop, which contain more information. Specifically, pprop has the following columns:

method: The name of the approximation method.
prop: The proportion that was approximated.
num, denom: the numerator and denominator of the approximation.
e.prop: Decimal representation of the approximate proportion – num / denom.
es.h: Distance between the proportion and its approximation, measured using effect size h.
diff: Difference between the proportion and its approximation.
ok: Is es.h < h$ok?
prop.char: Approximation of the proportion, as a character. Possibly includes a descriptive prefix. When char = TRUE, this is what's returned.

as.character: Convert pprop object to character. For a list of pprop objects, use sapply(x, as.character, char.method).
as.double: Convert pprop object to numeric. Simply returns the original proportion.

Cohen, J. (1988). Statistical power analysis for the behavioral sciences (2nd ed.). Hillsdale,NJ: Lawrence Erlbaum.

ES.h, fractions.

# Basic usage
## one proportion
pprop(0.618034)	# 3 / 5
## descriptive prefix is added when necessary
pprop(0.1234)	# about 1 / 10
## default method ("fixed") does not produce
## a satisfactory answer -- switching to 
## another method
pprop(0.01234)	# about 1 / 50

## many proportions
set.seed(42)
x = data.frame(prop = runif(100))
x$desc = pprop(x$prop)
pp(x)

# Show details: char=FALSE or options(pprop.char = FALSE)
options(pprop.char = FALSE)

pprop(0.618034)	# 3 / 5 or 37 / 60
## Not as pretty
MASS::fractions(0.618034)	# 55/89

## "fixed" method does not produce a satisfactory answer
pprop(2 / 123)
## Can use the "simple" method, OR allow more divisors for the "fixed" method.
pprop(2 / 123, 
	fixed.divisors = c(getOption("pprop.fixed.divisors"), 20))

## Increasing simple.signif.digits makes results of the 
## "simple" method less pretty but more exact.
pprop(0.618034, simple.signif.digits = 2)

# compare "fixed" method, "simple" method, and MASS::fractions
options(pprop.char = TRUE)	# reset this option
x = data.frame(prop = runif(100))
x$prop.fixed = pprop(x$prop)
x$prop.simple = pprop(x$prop, char.method = "simple")
x$prop.MASS = as.character(MASS::fractions(x$prop))
pp(x)

## Above, pprop() runs twice -- once for each method.
## With a lot of data, you might want to do this, 
## which only runs pprop() once. 
x = data.frame(prop = runif(100))
pprop. = pprop(x$prop, char=FALSE)
x$prop.fixed = sapply(pprop., as.character, "fixed")
x$prop.simple = sapply(pprop., as.character, "simple")
x$prop.MASS = as.character(MASS::fractions(x$prop))
pp(x)

## All proportions from 0.0% to 100.0%.
n = 1000
x = data.frame(x = (0:n), n)
x$prop = x$x / x$n
pprop. = pprop(x$prop, char=FALSE)
x$prop.fixed = sapply(pprop., as.character, "fixed")
x$prop.simple = sapply(pprop., as.character, "simple")
x$prop.MASS = as.character(MASS::fractions(x$prop))
pp(x)