funchir-utils: Miscellaneous utile functions

In funchir: Convenience Functions by Michael Chirico

Miscellaneous utile functions

Description

Several odds-and-ends functions for data manipulation & representation, etc. See details and examples.

Usage

   create_quantiles(x, num, right = FALSE, na.rm = FALSE,
                    include.lowest = TRUE, labels = 1:num)
   to.pct(x, dig = Inf)
   nx.mlt(x, n)
   divide(x, n, na.rm = FALSE)
   dol.form(x, dig = 0L, suff = "", tex = FALSE)
   ntostr(n, dig = 2L)
   write.packages(con)
   stale_package_check(con)
   embed.mat(mat, M = nrow(mat), N = ncol(mat), m = 1L, n = 1L, fill = 0L)
   get_age(birthdays, ref_dates)
   quick_year(dates)
   quick_mday(dates)
   quick_yday(dates)

Arguments

x	A numeric vector.
num	A number, typically an integer, specifying how many equal-count intervals into which to divide the data.
right	logical, indicating if the intervals should be closed on the right (and open on the left) or vice versa.
na.rm	logical passed to quantile with the usual interpretation.
include.lowest	logical, indicating if an x[i] equal to the lowest (or highest, for right = FALSE) breaks value should be included.
labels	character vector of length num; the labels to be applied to the resulting factor.
dig	The number of digits to be included past the decimal in output; sent directly to round.
suff	The suffix to appended/unit in which to express x. Currently one of c("", "k", "m", "b"), corresponding to plain units, thousands, millions, and billions, respectively.
tex	Should $ be printed as \$ for direct copy-pasting to TeX files?
n	For nx.mlt, divide and ntostr, a number; see details. For embed.mat, an integer specifying the column at which to insert mat.
con	A file/connection where output should be written.
mat	A matrix.
M	An integer specifying the number of rows in the enclosing matrix.
N	An integer specifying the number of columns in the enclosing matrix.
m	An integer specifying the row at which to insert mat.
fill	An atomic vector specifying how to fill the enclosing matrix.
birthdays	A vector of Dates.
ref_dates	A vector of Dates.
dates	A vector of Dates.

Value

create_quantiles is a parsimonious function for generating quantiles of a vector (e.g., quartiles for num=4 or quintiles for num=5). Basically a wrapper for the cut function; the type of the output is factor. Fails for vectors with overlapping quantiles (e.g., with >50% of values of x equal to zero) unless the correct number of labels (i.e., the number of unique quantile breaks) is given in the labels argument.

to.pct converts a number (probably a proportion, i.e., typically between 0 and 1) to a percentage; also has an argument (dig) which can be used to round the output inline.

nx.mlt returns the least multiple of n which (weakly) exceeds x. Convenient for making axes ticks land on pretty numbers.

divide divides the range (min through max) of x into n points (basically a shorthand for seq).

dol.form takes a financial input and converts it to a (American-formatted, American-currency) string for printing–appending a dollar sign ("\$") and inserting commas after every third digit from the left of the decimal point.

ntostr converts n to a character vector with each element width dig. This is particularly nice for converting 99:100 to "99" and "100".

write.packages captures the current package environment (inspired by sessionInfo() and writes it as a JSON to con with writeLines; a list version of this object is returned. This may be essential for tracking across time which package versions were being used.

stale_package_check reads a file (with readLines) and checks which functions are actually used from each loaded package. Currently only checks for library (i.e., not require) calls.

embed.mat inserts a supplied matrix into a (weakly) larger enclosing matrix, typically filled with 0s, at a specified position.

get_age returns the accurate, fractional age (in years) of each individual, quickly. Accuracy deteriorates when non-leap century years are involved (i.e., any year congruent to 0 mod 100 but not 0 mod 400); designed for use with currently-relevant birthdays and ages.

quick_year converts a Date object into its year efficiently; also ignores concerns of leap centuries. quick_mday returns the day of the month. quick_yday returns the day of the year. Returns as an integer.

See Also

cut, prettyNum

Examples

  x <- runif(100)

  # Return which multiple of 1/7 least
  #   exceeds each element of x
  create_quantiles(x, 7)

  to.pct(x)
  to.pct(x, dig = 2) #output of the form xxx.xx

  nx.mlt(x, 1/3)

  dol.form(x, dig=2L)

  ntostr(999:1000, dig = 3L) # c("999","000")
  ntostr(999:1000, dig = 2L) # c("99","00")

  library(stats)
  write.packages()

  inmat <- matrix(1:9, ncol = 3L)
  embed.mat(inmat, M = 4L, N = 4L)
  embed.mat(inmat, N = 6L, n = 4L, fill = NA)

  d1 = as.Date('1987-05-02')
  d2 = as.Date('2016-02-23')
  get_age(d1, d2)
  quick_year(d1)
  quick_mday(d1)

funchir documentation built on April 18, 2022, 1:06 a.m.