kimisc: Kirill's Miscellaneous Functions

Description

A collection of useful functions not found anywhere else, mainly for programming: Pretty intervals, generalized lagged differences, checking containment in an interval, and an alternative interface to assign().

Author(s)

Maintainer: Kirill Müller kirill@cynkra.com

See Also

Useful links:

• https://krlmlr.github.io/kimisc/

• https://github.com/krlmlr/kimisc

• Report bugs at https://github.com/krlmlr/kimisc/issues

Replaces NA values

Description

This (vectorized) function returns the first non-NA argument, similar to the SQL function COALESCE. If a vector or matrix is passed as first argument, the remaining arguments are recycled to generate a vector/matrix of the same dimension, and coalescing is done element by element.

Usage

coalesce.na(x, ...)

Arguments

Value

A vector of the same length as x.

See Also

Other deprecated functions: df_to_list-deprecated, hms.to.seconds-deprecated, kimisc-deprecated, list_to_df-deprecated, nc-deprecated, nlist-deprecated, ofactor-deprecated, sample.rows-deprecated, seconds.to.hms-deprecated, thisfile-deprecated, tll-deprecated, vswitch-deprecated

Examples

coalesce.na(NA, -1)
coalesce.na(5, 3)
coalesce.na(c(1, NA, NA), c(NA, 2))
coalesce.na(matrix(c(NA, 1:3), nrow = 2))
coalesce.na(NA)

Convert Numeric to Factor, with custom formatting

Description

This is an enhanced version of base::cut() that allows a custom formatting to be applied to the values.

Usage

cut_format(
  x,
  breaks,
  include.lowest = FALSE,
  right = TRUE,
  ordered_result = FALSE,
  ...,
  format_fun = format,
  sep = ", ",
  paren = c("(", "[", ")", "]")
)

Arguments

See Also

https://stackoverflow.com/q/14456371/946850

Examples

cut_format(runif(10), seq(0, 1, by = 0.25), format_fun = function(x) paste(x * 100, "%"))
cut_format(runif(10), seq(0, 1, by = 0.25), paren = c("<", "{", ">", "}"))

Converts a name-value data frame to a named list

Description

This function converts a data frame back to a list. It is the reverse operation to list_to_df().

Usage

df_to_list(df_for_list)

Arguments

Details

In a data frame with more than two columns, heuristics are applied to detect the name and value column.

See Also

Other deprecated functions: coalesce.na-deprecated, hms.to.seconds-deprecated, kimisc-deprecated, list_to_df-deprecated, nc-deprecated, nlist-deprecated, ofactor-deprecated, sample.rows-deprecated, seconds.to.hms-deprecated, thisfile-deprecated, tll-deprecated, vswitch-deprecated

Exports to an environment

Description

This function is a wrapper around export.list() that exports variables by their name to another environment.

Usage

export(..., target.env = .GlobalEnv)

Arguments

Value

Invisible NULL.

Author(s)

Roland

References

https://stackoverflow.com/a/17484932/946850

See Also

export.list(), assign()

Examples

local({
  newly.created.var <- 5
  export(newly.created.var)
})
newly.created.var
rm(newly.created.var)

Exports to an environment

Description

This function is a wrapper around assign() that exports the contents of a named list to an environment. The variable names in the target environment are constructed from the names of the list items or taken from a separate argument.

Usage

export.list(arg.list, arg.names = names(arg.list), target.env = .GlobalEnv)

Arguments

Value

Invisible NULL.

Author(s)

Roland

References

https://stackoverflow.com/a/17484932/946850

See Also

export(), assign()

Examples

export.list(list(newly.created.var = 5))
newly.created.var
rm(newly.created.var)

Generalized lagged differences

Description

Returns suitably lagged and iterated differences using arbitrary difference functions.

Usage

gdiff(x, lag = 1L, differences = 1L, FUN = `-`, ...)

Arguments

Value

If x is a vector of length n and differences = 1, then the computed result is equal to the successive differences FUN(x[(1+lag):n], x[1:(n-lag)]).

If difference is larger than one this algorithm is applied recursively to x. Note that the returned value is a vector which is shorter than x.

If x is a matrix then the difference operations are carried out on each column separately.

See Also

base::diff()

Examples

gdiff(1:4)
gdiff(1:4, FUN = `/`)

Converts a time value given in H:M:S format to the number of seconds since midnight

Description

This function is very similar to strptime with the %X conversion specification. Anything with three numbers between two colons is interpreted as a time, no consistency check is performed on the actual hour, minute and second values. Thus, strings like 25:15:00 and 23:78:101 also will be converted. Incorrectly formatted strings are converted to NA with a warning.

Usage

hms.to.seconds(x)

Arguments

Value

A (vector of) integer values of the same length as x.

See Also

base::strptime()

Other deprecated functions: coalesce.na-deprecated, df_to_list-deprecated, kimisc-deprecated, list_to_df-deprecated, nc-deprecated, nlist-deprecated, ofactor-deprecated, sample.rows-deprecated, seconds.to.hms-deprecated, thisfile-deprecated, tll-deprecated, vswitch-deprecated

Examples

hms.to.seconds(c("00:00:01", "00:01:00", "01:00:00"))
hms.to.seconds(c("25:15:00", "23:78:101"))
hms.to.seconds("invalid")

Checks if values are contained in an interval (open on the left)

Description

This function checks if the values in the x parameter are contained in the interval (lo, hi]. NA values are treated as "not in the interval".

Usage

in.interval.lo(x, lo, hi)

Arguments

Value

A boolean vector of the same length as x.

See Also

in.interval.ro(), nin.interval.lo(), nin.interval.ro()

Examples

in.interval.lo(c(-1, 0, 1, 2), 0, 1)
in.interval.lo(NA, 1, 3)

Checks if values are contained in an interval (open on the right)

Description

This function checks if the values in the x parameter are contained in the interval [lo, hi). NA values are treated as "not in the interval".

Usage

in.interval.ro(x, lo, hi)

Arguments

Value

A boolean vector of the same length as x.

See Also

in.interval.lo(), nin.interval.lo(), nin.interval.ro()

Examples

in.interval.ro(c(-1, 0, 1, 2), 0, 1)
in.interval.ro(NA, 1, 3)

Deprecated functions

Description

The "See also" section contains the deprecated functions in this package.

See Also

Other deprecated functions: coalesce.na-deprecated, df_to_list-deprecated, hms.to.seconds-deprecated, list_to_df-deprecated, nc-deprecated, nlist-deprecated, ofactor-deprecated, sample.rows-deprecated, seconds.to.hms-deprecated, thisfile-deprecated, tll-deprecated, vswitch-deprecated

Converts a list to a name-value data frame

Description

This function coerces its input to a list and returns a data frame with as many rows as there are list items in the input, and two columns (one for the names, one for the values). If the list is not named, the natural sequence will be used as item names.

Usage

list_to_df(list_for_df)

Arguments

See Also

Other deprecated functions: coalesce.na-deprecated, df_to_list-deprecated, hms.to.seconds-deprecated, kimisc-deprecated, nc-deprecated, nlist-deprecated, ofactor-deprecated, sample.rows-deprecated, seconds.to.hms-deprecated, thisfile-deprecated, tll-deprecated, vswitch-deprecated

Smart named vector

Description

This function is a wrapper around c() that assigns names to unnamed arguments based on the unevaluated expression used in the call.

Usage

nc(...)

Arguments

Value

A named vector.

Author(s)

Hadley Wickham

References

https://stackoverflow.com/a/5043280/946850

See Also

c(), nlist()

Other deprecated functions: coalesce.na-deprecated, df_to_list-deprecated, hms.to.seconds-deprecated, kimisc-deprecated, list_to_df-deprecated, nlist-deprecated, ofactor-deprecated, sample.rows-deprecated, seconds.to.hms-deprecated, thisfile-deprecated, tll-deprecated, vswitch-deprecated

Examples

a <- 1
b <- 2
c <- 3
nc(a, b, d = c)
nc(mean(c(a, b, c)))

Checks if values are outside of an interval (open on the left)

Description

This function checks if the values in the x parameter are contained in the interval (lo, hi]. NA values are treated as "not in the interval".

Usage

nin.interval.lo(x, lo, hi)

Arguments

Value

A boolean vector of the same length as x.

See Also

in.interval.lo(), in.interval.ro(), nin.interval.ro()

Examples

nin.interval.lo(c(-1, 0, 1, 2), 0, 1)
nin.interval.lo(NA, 1, 3)

Checks if values are outside of an interval (open on the right)

Description

This function checks if the values in the x parameter are contained in the interval [lo, hi). NA values are treated as "not in the interval".

Usage

nin.interval.ro(x, lo, hi)

Arguments

Value

A boolean vector of the same length as x.

See Also

in.interval.lo(), in.interval.ro(), nin.interval.lo()

Examples

nin.interval.ro(c(-1, 0, 1, 2), 0, 1)
nin.interval.ro(NA, 1, 3)

Smart named list

Description

This function is a wrapper around list() that assigns names to unnamed arguments based on the unevaluated expression used in the call.

Usage

nlist(...)

Arguments

Value

A named list.

Author(s)

Hadley Wickham

References

https://stackoverflow.com/a/5043280/946850

See Also

list()

Other deprecated functions: coalesce.na-deprecated, df_to_list-deprecated, hms.to.seconds-deprecated, kimisc-deprecated, list_to_df-deprecated, nc-deprecated, ofactor-deprecated, sample.rows-deprecated, seconds.to.hms-deprecated, thisfile-deprecated, tll-deprecated, vswitch-deprecated

Examples

a <- 1
b <- 2
c <- 3
nlist(a, b, d = c)
nlist(mean(c(a, b, c)))

Order-preserving factors

Description

The function ofactor() is a convenience wrapper for factor() that orders the levels as they appear in the data if the levels argument is not specified.

Usage

ofactor(x = character(), ...)

Arguments

Value

A factor. See base::factor() for details.

See Also

Other deprecated functions: coalesce.na-deprecated, df_to_list-deprecated, hms.to.seconds-deprecated, kimisc-deprecated, list_to_df-deprecated, nc-deprecated, nlist-deprecated, sample.rows-deprecated, seconds.to.hms-deprecated, thisfile-deprecated, tll-deprecated, vswitch-deprecated

Examples

ofactor(3:1)
ofactor(9:12, exclude = 11)
identical(ofactor(3:1, levels = 1:3), factor(3:1))

Random Samples and Permutations for Data Frames

Description

This function takes a sample of the specified size from the rows of x using either with or without replacement.

Usage

sample.rows(x, size, replace = FALSE, prob = NULL)

Arguments

Details

This function internally calls sample.int().

Value

A data frame of the same shape as x.

See Also

Other deprecated functions: coalesce.na-deprecated, df_to_list-deprecated, hms.to.seconds-deprecated, kimisc-deprecated, list_to_df-deprecated, nc-deprecated, nlist-deprecated, ofactor-deprecated, seconds.to.hms-deprecated, thisfile-deprecated, tll-deprecated, vswitch-deprecated

Examples

set.seed(42)
sample.rows(
  data.frame(a = c(1, 2, 3), b = c(4, 5, 6), row.names = c("a", "b", "c")),
  10,
  replace = TRUE
)

Converts a time value given as number of seconds since midnight to the H:M:S format

Description

This function is very similar to strftime with the %X conversion specification. Hour values larger than 24 are permitted. Fractions will be rounded down to the next integer. Non-numeric values are coerced to NA with a warning.

Usage

seconds.to.hms(x)

Arguments

Value

A (vector of) character values of the same length as x.

See Also

base::strftime()

Other deprecated functions: coalesce.na-deprecated, df_to_list-deprecated, hms.to.seconds-deprecated, kimisc-deprecated, list_to_df-deprecated, nc-deprecated, nlist-deprecated, ofactor-deprecated, sample.rows-deprecated, thisfile-deprecated, tll-deprecated, vswitch-deprecated

Examples

seconds.to.hms(c(1, 60, 3600.5))
seconds.to.hms(c(100000, -4000.5))
seconds.to.hms("invalid")

Determines the path of the currently running script

Description

R does not store nor export the path of the currently running script. This is an attempt to circumvent this limitation by applying heuristics (such as call stack and argument inspection) that work in many cases.

Usage

thisfile()

thisfile_source()

thisfile_r()

thisfile_rscript()

thisfile_knit()

Details

This functions currently work only if the script was sourced, processed with knitr, or run with Rscript or using the --file parameter to the R executable. For code run with Rscript, the exact value of the parameter passed to Rscript is returned.

Value

The path of the currently running script, NULL if it cannot be determined.

Author(s)

Kirill Müller, Hadley Wickham, Michael R. Head

References

https://stackoverflow.com/q/1815606/946850

See Also

base::source(), utils::Rscript(), base::getwd()

Other deprecated functions: coalesce.na-deprecated, df_to_list-deprecated, hms.to.seconds-deprecated, kimisc-deprecated, list_to_df-deprecated, nc-deprecated, nlist-deprecated, ofactor-deprecated, sample.rows-deprecated, seconds.to.hms-deprecated, tll-deprecated, vswitch-deprecated

Examples

## Not run: 
thisfile()

## End(Not run)

Transposes a list of lists

Description

The argument is assumed to be a list of n (named) lists with length m each. It is converted to a (named) list of m elements with length n each.

Usage

tll(l)

Arguments

Value

A list of lists corresponding to a transposition of the argument.

See Also

base::t()

Other deprecated functions: coalesce.na-deprecated, df_to_list-deprecated, hms.to.seconds-deprecated, kimisc-deprecated, list_to_df-deprecated, nc-deprecated, nlist-deprecated, ofactor-deprecated, sample.rows-deprecated, seconds.to.hms-deprecated, thisfile-deprecated, vswitch-deprecated

Examples

tll(list(list(1, 2), list(3, 4)))
tll(list(list(a = 1, b = 2), list(a = 3, b = 4)))
tll(list(x = list(a = 1, b = 2), y = list(a = 3, b = 4)))

Vectorized switch

Description

The function vswitch is a vectorized version of base::switch() optimized for performance.

Usage

vswitch(EXPR, ...)

Arguments

Details

Only the EXPR argument is treated as a vector. In particular, if any of the alternatives (or the default alternative) is a vector, the result will be a list of vectors.

Value

The value of one of the elements of ..., or NA whenever no element is selected. Contrary to base::switch() the result is always visible.

See Also

Other deprecated functions: coalesce.na-deprecated, df_to_list-deprecated, hms.to.seconds-deprecated, kimisc-deprecated, list_to_df-deprecated, nc-deprecated, nlist-deprecated, ofactor-deprecated, sample.rows-deprecated, seconds.to.hms-deprecated, thisfile-deprecated, tll-deprecated