Package 'bedrock'

Description

The function duplicated() returns a logical vector indicating which elements of x are duplicates, but it does not flag the first occurrence of subsequently duplicated elements.

Usage

allDuplicated(x)

Arguments

Details

allDuplicated returns a logical vector indicating all elements of x that are involved in ties (i.e., have frequency > 1).

Note that allDuplicated flags all occurrences of tied values, not only the duplicates beyond the first occurrence.

Consequently, !allDuplicated(x) can be used to identify elements of x that appear exactly once.

Missing values are considered equal to each other, so multiple NAs are flagged as ties. As the function builds on duplicated(), it also works for data frames (row-wise) and matrices.

Value

a logical vector of the same length as x.

See Also

duplicated() for identifying duplicate elements (excluding first occurrences).
unique() for extracting unique values.
split() for grouping tied values.
table() for counting frequencies.

Other data.equal: allIdentical(), compareDataFrames()

Examples

x <- c(1:10, 4:6)

allDuplicated(x)

# Compare with duplicated():
duplicated(x)

# Elements appearing exactly once
x[!allDuplicated(x)]

# Identify and analyse ties
x <- sample(letters[1:10], 20, replace = TRUE)
ties <- split(x, x)

# Number of tied groups
sum(sapply(ties, length) > 1)

# Sizes of tied groups
sizes <- sapply(ties, length)
sizes[sizes > 1]

# Same via table()
tab <- table(x)
tab[tab > 1]

Description

Extends identical() to more than two objects. Returns TRUE if all supplied objects are exactly identical, and FALSE otherwise.

Usage

allIdentical(...)

Arguments

Details

If zero or one object is supplied, the function returns TRUE.

Note that the objects themselves are compared, not their elements. So allIdentical(list(A, B, C)) is TRUE, as a single object is trivially identical to itself. Use do.call(allIdentical, myList) to compare the elements of a list.

Value

logical scalar.

See Also

identical()

Other data.equal: allDuplicated(), compareDataFrames()

Examples

A <- LETTERS[1:5]
B <- LETTERS[1:5]
C <- LETTERS[1:5]
E <- factor(LETTERS[1:5])

allIdentical(A, B, C)        # TRUE
allIdentical(A, B, C, E)     # FALSE

allIdentical(1, 1L)          # FALSE (type matters)

Description

Prepends (or inserts) a column of enumeration labels – lowercase or uppercase Roman numerals, or Arabic numbers.

Usage

appendEnum(
  x,
  type = c("roman-lcase", "roman-ucase", "arabic"),
  suffix = ". ",
  startWith = 1L,
  after = 0L,
  colName = NULL
)

Arguments

Value

x with an additional enumeration column.

See Also

append()

Other data.append: appendRowNames(), appendX(), multMerge()

Examples

d <- data.frame(x = 1:3, y = c("a", "b", "c"))
appendEnum(d)

appendEnum(d, type = "arabic", suffix = ") ")

# insert after the first column instead of prepending
appendEnum(d, after = 1L, colName = "no")

Description

Adds the row names of a data.frame or matrix as a column.

Usage

appendRowNames(x, colName = "rowname", after = 0L, removeRowNames = TRUE)

Arguments

Value

an object of the same class as x with the row names added as a column. Note that for matrices the result is coerced to the common mode, so appending (character) row names to a numeric matrix yields a character matrix.

See Also

append()

Other data.append: appendEnum(), appendX(), multMerge()

Examples

dd <- data.frame(x = 1:5, y = 6:10, z = LETTERS[1:5],
                 row.names = letters[1:5])
appendRowNames(dd)

Description

Generic function to append or insert elements to vectors, matrices, and data frames.

Usage

appendX(x, values, after = NULL, ...)

## Default S3 method:
appendX(x, values, after = NULL, ...)

## S3 method for class 'matrix'
appendX(x, values, after = NULL, rows = FALSE, newNames = NULL, ...)

## S3 method for class 'data.frame'
appendX(x, values, after = NULL, rows = FALSE, newNames = NULL, ...)

## S3 method for class 'TOne'
appendX(x, values, after = NULL, rows = TRUE, newNames = NULL, ...)

Arguments

Value

object of the same class as x.

See Also

append()

Other data.append: appendEnum(), appendRowNames(), multMerge()

Examples

# vectors
appendX(1:5, 99, after = 2)

# matrices: insert a column / a row
m <- matrix(1:6, nrow = 2,
            dimnames = list(c("r1", "r2"), c("a", "b", "c")))
appendX(m, c(9, 9), after = 1, newNames = "z")
appendX(m, 7:9, after = 1, rows = TRUE, newNames = "r1b")

# data frames: insert a column / a row
d <- data.frame(a = 1:3, b = 4:6)
appendX(d, 7:9, after = 1, newNames = "z")
appendX(d, list(a = 99, b = 88), after = 0, rows = TRUE)

Description

Clamps a confidence interval to the range of the parameter and opens the side that a one-sided interval leaves free. One implementation for the whole suite, so that every function reports a one-sided bound the same way.

Usage

applySides(ci, sides = "two.sided", lo = -Inf, hi = Inf)

Arguments

Details

sides names the side carrying the finite bound:

"left"

the informative bound is the lower one; the upper one is opened to hi.

"right"

the informative bound is the upper one; the lower one is opened to lo.

lo and hi are the parameter's range, not infinities. Most statistics are bounded, so reporting the open side at the boundary is the ordinary case rather than an exception: a correlation opens to $\pm 1$, an association measure in $[0, 1]$ to 0 or 1, Pearson's $C$ to $\sqrt{(m-1)/m}$. Where the parameter really is unbounded, $\pm$Inf is passed and the usual half-line comes back. Some statistics need one of each: Cronbach's alpha takes lo = -Inf and hi = 1, a relative risk lo = 0 and hi = Inf.

The two-sided interval is clamped to $[lo, hi]$ as well, so an interval can never claim a value the statistic cannot take.

Value

a named numeric vector with the elements lci and uci.

See Also

checkConfLevel(), checkFlag()

Examples

ci <- c(0.12, 0.58)

applySides(ci, "two.sided", lo = 0, hi = 1)
applySides(ci, "left",      lo = 0, hi = 1)   # uci opens to 1
applySides(ci, "right",     lo = 0, hi = 1)   # lci opens to 0

# an unbounded parameter opens to infinity
applySides(c(-1.4, 2.6), "left", lo = -Inf, hi = Inf)

# and one of each: Cronbach's alpha is bounded above only
applySides(c(0.61, 0.94), "right", lo = -Inf, hi = 1)

# the two-sided interval is clamped too
applySides(c(-0.2, 1.3), "two.sided", lo = 0, hi = 1)

# NA bounds survive
applySides(c(NA, NA), "left", lo = -1, hi = 1)

Description

Converts an object of class "xtabs" to a plain array or matrix by dropping all additional classes such as "xtabs" and "table", along with the call attribute.

Usage

## S3 method for class 'xtabs'
as.array(x, ...)

## S3 method for class 'xtabs'
as.matrix(x, ...)

Arguments

Value

an array (or matrix in the two-dimensional case) with no additional classes.

See Also

Other data.coerce: toBaseR(), type-aliases

Examples

xt <- xtabs(~ cyl + gear, data = mtcars)
class(as.matrix(xt))
# "matrix" "array"

Description

A unified conversion utility for binary variables. Converts a logical, numeric, factor, or character vector to a binary numeric vector coded as 0 and 1.

Usage

asBinary(x, pos = NULL, warn = TRUE)

Arguments

Details

For logical input, TRUE is mapped to 1 and FALSE to 0.

For numeric input, values must already be 0 or 1 (or NA); any other value raises an error.

For factor input, the vector must have exactly two levels. By default the second level is coded as 1. Use pos to specify which level should be coded as 1.

For character input, the vector must have exactly two distinct non-missing values. By default the alphabetically second value is coded as 1. The same pos logic applies.

Value

a numeric vector of 0s and 1s (and NAs where present in x). For factor and character input, the result carries a "coding" attribute, a named integer vector documenting which original value was mapped to 0 and which to 1.

See Also

Other data.recode: combLevels(), dummy(), mReplace(), nf(), recodeX(), revCode(), stringsAsFactors()

Examples

# logical
asBinary(c(TRUE, FALSE, TRUE))

# numeric (already binary)
asBinary(c(0, 1, 1, 0))

# factor: second level coded as 1 by default
asBinary(factor(c("control", "treatment", "control")))

# factor with explicit positive value
asBinary(factor(c("control", "treatment", "control")), pos = "treatment")

# character
asBinary(c("no", "yes", "no", "yes"))

# character with explicit positive value
asBinary(c("F", "U", "F", "U"), pos = "F")

Description

Translates a custom date format string using tokens like yyyy, mm, dd, mmm, etc. into a valid strftime-compatible format string (C-style).

Usage

asCDateFmt(fmt)

Arguments

Details

The function parses the input string sequentially and replaces recognized tokens while leaving all other characters unchanged. This makes it robust to compact formats (e.g. yyyymmdd) and mixed text.

Supported tokens:

• d, dd, ddd, dddd

• m, mm, mmm, mmmm

• y, yy, yyyy

Mapping:

• yyyy -> ⁠%Y⁠

• yy, y -> ⁠%y⁠

• mm, m -> ⁠%m⁠

• mmm -> ⁠%b⁠

• mmmm -> ⁠%B⁠

• dd -> ⁠%d⁠

• d -> ⁠%e⁠

• ddd -> ⁠%a⁠

• dddd -> ⁠%A⁠

Value

character string. A valid strftime format.

Examples

asCDateFmt("yyyy-mm-dd")
asCDateFmt("dd.mm.yy")
asCDateFmt("yyyymmdd")
asCDateFmt("mmm d, yyyy")

Description

Checks the exported functions of an installed package, their arguments and the values of their enumerated arguments against the naming rules of the suite. Meant to run as a test in every package, so that a name which breaks a rule is found when it is introduced and not in a review.

Usage

auditNames(package, exceptions = NULL)

Arguments

Details

The rules checked, with the label used in the column rule:

camelCase

exported functions and arguments are written in lowerCamelCase. A dot is kept in S3 methods, in coercion generics ⁠as.<Class>⁠ that really dispatch, and in argument names that are part of the shared vocabulary (na.rm, conf.level, sig.level, ...).

acronym

only CI, QQ, XY, ECDF, SE and AD keep their capitals inside a name, GCD and LCM as whole names. Every other acronym is written like a word: Rgb, Url, Html. As arguments, FUN, R, N, S and X are capitals by convention.

collision

a function whose name is taken by base, stats, graphics, utils or dplyr carries the suffix X. A name counts as taken if it exists there, or if it differs from one only in the case of the whole word (iqr against IQR()). An internal capital makes a name of its own: combN() is not combn().

suffixX

and no function carries it without such a collision.

dotExport

no function is exported with a leading dot, the graphics helpers of the plotting framework excepted.

forwarded

an argument name taken over from another package (ignore.case, useNA, all.inside, ...) is kept only where the value is passed on to another function.

replaced

names the rules have replaced: alpha (sig.level), seed (the caller uses set.seed()), pkg (package), fun in an exported function (FUN), dat (data), grp (groups), w (weights), level, color and cols (col), obs and resp (ref), the prefix num for a count (n), the suffix Args for a list of arguments, and g and horizontal in plot functions (groups, horiz).

enumValue

the values of an enumerated argument are lower case, words joined by a hyphen ("wald-cc"). Values that belong to the function they are passed on to, such as "two.sided" or the names in p.adjust.methods, are left alone. A value that names an element of the result (which = "tauB" returning ⁠$tauB⁠) follows the rule for results instead; the audit cannot see that and reports it, so such values are listed as exceptions.

Arguments of an S3 method that its generic defines are not checked: print.foo(x, ...) and predict.foo(object, newdata, ...) are given by the generic. Re-exported functions are skipped altogether.

What the audit cannot see is a word boundary that was never written: maxlen and nlow are single lower case words to it. Such names are found by reading, not by this function.

Value

a data frame with one row per finding and the columns package, fun, arg (NA for a finding on the function name), rule, detail and key, the form in which the finding is named in exceptions. It has no rows if the package complies. The attribute "unused" holds the exceptions that matched no finding.

See Also

funArgs(), funList()

Other pkg.funinfo: funArgs(), funCalls(), funKeywords(), funList(), rdLabels(), rdTitle()

Examples

res <- auditNames("bedrock")
res[, c("fun", "arg", "rule", "detail")]

# as a test: no findings beyond the documented exceptions, and no
# exception without a finding
accepted <- c("isNA" = "NA is R's own constant, not an acronym")
res <- auditNames("bedrock", exceptions = names(accepted))
attr(res, "unused")

Description

The between and outside operators are used to check, whether a vector of given values x lie within a defined range (or outside respectively). The values can be numbers, text or dates. Ordered factors are supported.

Usage

x %[]% rng

x %[)% rng

x %(]% rng

x %()% rng

x %][% rng

x %](% rng

x %)[% rng

x %)(% rng

Arguments

Details

The "BETWEEN" operators basically combine two conditional statements into one and simplify the query process.
They are merely a wrapper for: x >= rng[1] & x <= rng[2], where the round bracket ( means strictly greater (>) and the square bracket [ means greater or equal (>=). Numerical values of x will be handled by C-code, which is significantly faster than two comparisons in R (especially when x is huge).

For the matching outside-operator, boundary elements of the corresponding between-range return FALSE; that is, they are not considered outside whenever the negated between-operator includes that boundary.

Both arguments, x and rng, will be recycled to the highest dimension, which is either the length of the vector (x) or the number of rows of the matrix (rng).
See also the routines used to check, whether two ranges overlap (overlapSize(), distance()).

The "OUTSIDE" operators are the negations of the corresponding "BETWEEN" operators, matched by meaning rather than by mirrored bracket symbols:

• ⁠%][%⁠ negates ⁠%()%⁠ (strictly outside both bounds)

• ⁠%](%⁠ negates ⁠%(]%⁠

• ⁠%)[%⁠ negates ⁠%[)%⁠

• ⁠%)(%⁠ negates ⁠%[]%⁠ (strictly outside, both bounds of the between-operator were closed)

Value

a logical vector of the same length as x.

See Also

if(), ifelse()

Other data.interval: intervals, range-operators

Examples

x <- 1:9
x %[]% c(3,5)

# outside
x <- 1:9
x %][% c(3,5)

c(x,NA) %[]% c(3,5)

x %(]% c(3,5)

# no result when from > to:
x %[]% c(5,3)
x %(]% c(5,5)

# no problem:
ordered(x) %[]% c(3,5)

# not meaningful:
factor(x) %[]% c(3,5)

# characters
letters[letters %(]% c("d","h")]

# select numbers between 0.4 and 0.5
x <- runif(20)
x %[]% c(0.4, 0.5)

# use it with an ordered factor
x <- ordered(sample(LETTERS, 20), levels = LETTERS)
x %[)% c("G","K")


# use multiple ranges
2 %[]% cbind(1:4,2:5)

# both arguments are recycled
c(2,3) %[]% cbind(1:4,2:5)

Description

Create a binary tree of a given number of nodes n. Can be used to organize a sorted numeric vector as a binary tree.

Usage

binaryTree(n)

Arguments

Details

If we index the nodes of the tree as 1 for the top, 2–3 for the next horizontal row, 4–7 for the next, ... then the parent-child traversal becomes particularly easy. The basic idea is that the rows of the tree start at indices 1, 2, 4, ....

binaryTree(13) yields the vector c(8, 4, 9, 2, 10, 5, 11, 1, 12, 6, 13, 3, 7) meaning that the smallest element will be in position 8 of the tree, the next smallest in position 4, etc.

Value

an integer vector of length n.

Note

Substantially based on code by Terry Therneau, with major extensions and improvements by the package author.

See Also

pharos::plotBinaryTree

Other data.order: revX(), sortX()

Examples

binaryTree(12)

Description

Safely constructs a file path from a directory and a filename, independent of whether the directory ends with a trailing slash. The resulting path uses forward slashes.

Usage

buildPath(dir, filename)

Arguments

Details

Trailing slashes (or backslashes) in dir are removed before the components are joined, so buildPath("data", "file.csv") and buildPath("data/", "file.csv") yield the same result.

The path is then passed through normalizePath()with mustWork = FALSE, so paths that do not (yet) exist are allowed. Note that normalizePath resolves existing paths to absolute form, while non-existing paths are returned as constructed (i.e. possibly relative).

Both arguments are vectorized in the usual file.path() manner.

Value

a character string representing the file path.

Note

Converting between forward slashes and backslashes is a frequent necessity – and a hassle – especially in Windows. The cycleSlashes() function in the swissValet package is useful for this purpose.

See Also

Other file.path: findDownload(), isFilePath(), isUrl(), splitPath(), urlExists()

Examples

buildPath("data", "file.csv")
buildPath("data/", "file.csv")

Description

Conditionally evaluate a function depending on the value of an argument. This is a convenient helper for optional features such as plotting, logging, or callbacks, where the user can enable, disable, or parameterize a function call via a single argument.

Usage

callIf(FUN, arg, defaults = NULL, forbidden = NULL, warn = TRUE)

Arguments

Details

This function implements a flexible pattern for optional function calls:

• Enable/disable behavior with TRUE/FALSE

• Customize behavior with a list of arguments

• Provide safe defaults and restrict certain arguments

When merging defaults and arg, user-supplied arguments take precedence. Unlike modifyList(), elements with the value NULL are preserved and passed on to FUN (so that an explicit NULL can be used to reset an argument).

Value

returns the result of FUN(...) if called. If arg is FALSE, NULL, or NA, returns NULL invisibly.

See Also

Other pkg.args: extractArgs(), getDotsArg(), mergeArgs(), recycle()

Examples

# Simple usage: skip
callIf(message, FALSE)

# Call with defaults
callIf(message, TRUE, defaults = list("Hello world"))

# Call with explicit arguments
callIf(message, list(x = "Hello from callIf"))

# With defaults + override
callIf(plot, list(x = 1:5),
       defaults = list(y = 1:5, type = "l"))

# Forbid arguments
callIf(plot,
       list(x = 1:5, y = 1:5, col = "red"),
       forbidden = "col")

# Typical use case: optional plotting
x <- 1:10
y <- x^2
callIf(plot, TRUE, defaults = list(x, y))

Description

A dataset representing a standard deck of playing Cards. Each row corresponds to a single card and includes information such as suit, rank and numerical value.

Usage

Cards

Format

A data frame with 52 observations and X variables:

card

Name of the card.

rank

Rank of the card (e.g. 2–10, Jack, Queen, King, Ace).

suit

Suit of the card (e.g. hearts, diamonds, clubs, spades).

Details

The dataset can be used for simulations, probability calculations and teaching examples involving discrete outcomes and combinatorics.

The dataset represents a complete deck without jokers. It is suitable for probability experiments, simulations and demonstrations of categorical data.

Source

Simulated data.

See Also

Other datasets: Pizza, Roulette, Tarot, readCourseData()

Examples

head(Cards)
table(Cards$suit)

Description

Convert characters to their numeric character codes and vice versa.

Usage

charToAscii(x, output = c("vector", "list"))

asciiToChar(x)

Arguments

Details

charToAscii() converts each character in a string to its corresponding numeric code.

asciiToChar() converts numeric codes back to characters.

Only values in the range 1:127 belong to the ASCII standard and therefore have the same meaning across all systems. Values 128:255 depend on the current character encoding (for example ISO-8859-1 or Windows-1252) and may produce different characters on different platforms.

Note that 0 (NUL) cannot be represented in R character strings and is therefore not supported.

The output argument controls the representation returned by charToAscii():

"vector"

Simplifies the result whenever possible.

Returns an integer vector if:

• the input consists of a single string, or

• all input strings have length one.

Otherwise, a list of integer vectors is returned.

"list"

Always returns a list of integer vectors.

Value

• charToAscii() returns either an integer vector or a list of integer vectors, depending on output.

• asciiToChar() returns a character vector.

See Also

charToRaw(), rawToChar()

Other string.transform: mGsub(), strSplitToCol(), strSplitToDummy()

Examples

# basic usage
x <- charToAscii("Silvia")
x

asciiToChar(x)

# multiple strings
charToAscii(c("A", "BC"), output = "list")

# split into individual characters
strsplit(asciiToChar(x), split = NULL)

# comparison with raw representation
charToRaw("Silvia")

Description

Checks that conf.level is a single number in $(0, 1)$, or NA. Intended for the confidence-interval functions across the suite, so that all of them accept the same values and refuse the rest with the same message.

Usage

checkConfLevel(conf.level, allowNA = TRUE)

Arguments

Details

The order of the tests is the point of this function. NA is logical, so a check that leads with !is.numeric() rejects the very default most of these functions carry. And is.na() on a vector of length other than one turns the surrounding if into the error message, which then talks about the condition instead of the argument. Length first, then type, then range.

NaN is excluded explicitly: is.na(NaN) is TRUE, so without that test a NaN would be silently accepted as "no interval wanted".

Value

conf.level, invisibly,
so the check can be used in an assignment: conf.level <- checkConfLevel(conf.level).

See Also

checkFlag(), checkCount(), checkString()

Examples

checkConfLevel(0.95)
checkConfLevel(NA)

# all of these are rejected:
try(checkConfLevel(c(0.9, 0.95)))   # length
try(checkConfLevel(NULL))           # length
try(checkConfLevel(NaN))            # not a level, and not NA either
try(checkConfLevel(0))              # range is open

# where the interval is part of the result, NA is refused as well
try(checkConfLevel(NA, allowNA = FALSE))

Description

Checks that an argument is a single finite integer, not smaller than min. Meant for the many size arguments in the suite - digits, sep, width, nPerm, R and the like - which are conceptually counts rather than numbers and were previously spelled out by hand wherever they occur.

Usage

checkCount(x, min = 0L, name = deparse(substitute(x)))

Arguments

Details

A whole number stored as a double is accepted, as that is what arithmetic on integers produces and what a user typing 2 supplies. TRUE is not, although it would survive as.integer(): a flag that reaches a count argument is a mistake, not a shorthand for one.

The order of the tests is the same as in checkConfLevel(), length first, then type, then value, so that the message names the argument rather than the condition that failed.

Value

x, invisibly.

See Also

checkConfLevel(), checkFlag(), checkString()

Examples

sep <- 2
checkCount(sep)

width <- 80
checkCount(width, min = 1)

# all of these are rejected:
try(checkCount(1.5))           # not a whole number
try(checkCount(-1))            # below the default minimum
try(checkCount(TRUE))          # a flag is not a count

Description

Checks that an argument is a single non-missing TRUE or FALSE. Meant for the many switches in the suite - correct, unbiased, scaled, paired and the like - which were previously either unchecked or checked in three different ways.

Usage

checkFlag(x, name = deparse(substitute(x)))

Arguments

Details

NA is rejected on purpose. It is a logical of length one and therefore passes is.logical(), but a flag that is neither on nor off has no meaning for a switch - and it propagates silently, because ⁠if (NA)⁠ is an error somewhere further down rather than here.

Value

x, invisibly.

See Also

checkConfLevel(), checkCount(), checkString()

Examples

correct <- TRUE
checkFlag(correct)

correct <- NA
try(checkFlag(correct))        # "'correct' must be a single ..."

Description

Checks that an argument is a single non-missing character string. Meant for the labelling arguments across the suite - dataName, captions, axis titles - where a vector or an NA would otherwise travel unnoticed into printed output.

Usage

checkString(x, name = deparse(substitute(x)))

Arguments

Details

An optional argument that may also be NULL is guarded by the caller, if (!is.null(dataName)) checkString(dataName), rather than by a further argument here: whether the absence of a label is admissible is a decision of the function, not of the check.

The empty string is accepted. It is a legitimate label, and a caller that needs a non-empty one says so itself.

Value

x, invisibly.

See Also

checkConfLevel(), checkFlag(), checkCount()

Examples

dataName <- "smoking by sex"
checkString(dataName)

# all of these are rejected:
try(checkString(NA_character_))  # a missing label is not a label
try(checkString(c("a", "b")))    # length
try(checkString(42))             # type

Description

Find the value(s) in a vector closest to a reference value. Multiple values are returned if ties occur or if duplicate values share the same minimum distance.

Usage

closest(x, val, output = "value", na.rm = FALSE)

Arguments

Details

Distance is computed as $|x_i - a|$. Ties are detected via isZero() rather than exact equality, which avoids spurious misses due to floating-point representation (e.g. 0.3 - 0.2 != 0.1).

When na.rm = TRUE, NA elements are excluded from the search but the original index positions of the remaining elements are preserved, so output = "index" always refers to positions in the original x.

When val or output are vectors, each element is processed independently and a list is returned.

Recycling follows standard R rules.

Value

if val and output are scalar:

• numeric vector if output = "value".

• integer vector if output = "index".

If val or output are vectors: a list with one element per value of val.

Returns NA if x is empty or all-NA (with na.rm = TRUE).

See Also

which()

Other math.basic: crossProd(), crossProdN(), dotProd(), roundTo(), unirootAll()

Examples

# basic
set.seed(8)
x <- runif(10) * 10

closest(x, 3.1)

sort(x)

y <- sample(10, size = 10, replace = TRUE)

# multiple observations of the same closest value
closest(y, val = 6)

# get the relevant positions
closest(y, val = 6, output = "index")

# two different values having the same distance (tie)
closest(c(2, 3, 4, 5), val = 3.5)

# na.rm preserves original index positions
closest(
  c(NA, 5, 8),
  val = 6,
  output = "index",
  na.rm = TRUE
)  # 2, not 1

# vectorize "a"
closest(c(2, 3, 4, 5), val = c(3.1, 3.9))

# vectorize "output"
closest(
  c(2, 3, 4, 5),
  val = 3.1,
  output = c("value", "index")
)

closest(
  c(2, 3, 4, 5),
  val = c(3.1, 3.9),
  output = c("value", "index")
)

Description

If several vectors are supplied, the evaluation will be elementwise, resp. rowwise if x is a data.frame or a matrix. The first element of the result is the first non NA element of the first elements of all the arguments, the second element of the result is the one of the second elements of all the arguments and so on.
Shorter inputs (of non-zero length) are NOT recycled: if all inputs have length greater than 1, they must have the same length (the function will bark otherwise). If any input has length 1 or 0, all inputs are flattened into a single vector (dropping NULLs) and the first valid element is returned, in the manner of a scalar SQL COALESCE.
The idea is borrowed from SQL. Might sometimes be useful when preparing data in R instead of in SQL.

Usage

coalesceX(..., method = c("is.na", "is.null", "is.finite"), flatten = TRUE)

Arguments

Value

return a single vector of the first non NA element(s) of the given data structure.

See Also

is.na(), is.finite()

Other vector.na: isNA(), locf(), naIf(), naReplace()

Examples

coalesceX(c(NA, NA, NA, 5, 3))
coalesceX(c(NA, NULL, "a"))
coalesceX(NULL, 5, 3)

d.frm <- data.frame(matrix(c(
  1, 2, NA, 4,
  NA, NA, 3, 1,
  NaN, 2, 3, 1,
  NA, Inf, 1, 1), nrow=4, byrow=TRUE)
)

coalesceX(d.frm)
coalesceX(as.matrix(d.frm))
coalesceX(d.frm$X1, d.frm$X2, d.frm$X3, d.frm$X4)
coalesceX(d.frm$X1, d.frm$X2, d.frm$X3, d.frm$X4, method="is.finite")
coalesceX(list(d.frm[,1], d.frm[,2]))

# returns the first finite element (skips NA, Inf, NaN)
coalesceX(d.frm, method="is.finite")

# returns the first argument that is not NULL
coalesceX(NULL, NULL, 7, method = "is.null")

# with characters (take care, factors won't work!)
# is.finite does not make sense here...
d.frm <- data.frame(matrix(c(
  "a", "b", NA, "4",
  NA, NA, "g", "m",
  NA_character_,"hfdg", "rr", "m",
  NA, Inf, 1, 1), nrow=4, byrow=TRUE)
, stringsAsFactors = FALSE)

coalesceX(d.frm$X1, d.frm$X2, d.frm$X3, d.frm$X4)
coalesceX(d.frm)
coalesceX(as.list(d.frm))

Description

Aggregates a table or ftable object by reassigning the levels of one or more dimensions according to user-supplied mappings, and summing the frequencies within each resulting level combination.

Usage

collapseTable(x, ..., strict = TRUE)

Arguments

Details

Mapping vectors define how factor levels are reassigned. Element i specifies the new label for the i-th original level. Repeated values in a mapping vector cause the corresponding levels to be merged.

Argument matching

• Named arguments are matched to dimensions by name (e.g., age = c("young", "adult")).

• Unnamed arguments are assigned to dimensions in order.

• Mixed usage assigns named arguments first, then remaining unnamed arguments in order.

Constraints

• Each dimension may be specified at most once.

• Mapping vectors must have the same length as the number of levels of the corresponding dimension.

• NA values in mapping vectors are not allowed.

Level ordering The order of the resulting levels follows the first occurrence of each value in the mapping vector.

Error handling

• If strict = TRUE, unknown dimension names result in an error, and positional assignment of unnamed arguments produces a warning.

• If strict = FALSE, unknown dimensions produce a warning (and are ignored), and positional assignment is silent.

Value

a collapsed table object with updated dimensions and aggregated frequencies.

See Also

Other data.reshape: long-wide-reshape, splitAt(), splitX(), untable()

Examples

tab <- xtabs(~ gear + cyl, data = mtcars)
tab

# merge the 4- and 6-cylinder categories
collapseTable(tab, cyl = c("le6", "le6", "8"))

# positional assignment (first dimension), silent with strict = FALSE
collapseTable(tab, c("3-4", "3-4", "5"), strict = FALSE)

Description

Wraps text in a character matrix so that it's displayed over more than one line.

Usage

columnWrap(x, width = NULL)

Arguments

Details

A data.frame containing character columns with long texts is often wrapped by columns. This can lead to a loss of overview. columnWrap() wraps the lines within the columns.

Value

a character matrix with one column per element of x and one row per wrapped line.

See Also

strwrap()

Other data.print: printCharMatrix()

Examples

print(columnWrap("This is a very long text for a table", 12))

Description

Extracts and combines the levels from one or more vectors or factors. Non-factor inputs are coerced to factors before extracting levels.

Usage

combLevels(..., sorted = FALSE, na = FALSE)

Arguments

Details

Each input is coerced to a factor (if not already one), and its levels are extracted. The union of all levels is returned. Unused levels of factor inputs are preserved.

By default, missing values (NA) are not included as a level. Set na = TRUE to include them; NA is then placed last when sorting.

The order of levels follows their first occurrence unless sorted = TRUE.

Value

a character vector containing the unique levels across all inputs.

See Also

Other data.recode: asBinary(), dummy(), mReplace(), nf(), recodeX(), revCode(), stringsAsFactors()

Examples

x <- factor(c("A", "B"))
y <- c("B", "C")

combLevels(x, y)

# Sorted levels
combLevels(x, y, sorted = TRUE)

# Including NA as a level
x <- c("A", NA)
y <- c("B", NA)
combLevels(x, y, na = TRUE)

Description

Return the number of combinations with and without replacement and order.

Usage

combN(n, m, replace = FALSE, ordered = FALSE)

Arguments

Value

a numeric value.

See Also

combn(), choose(), factorial(), vignette("Combinatorics", package = "bedrock")

Other combinatorics: combPairs(), combSet(), pairApply(), permn(), randGroupSplit(), sampleX()

Examples

n <- 5; m <- 2
combN(n, m, replace=TRUE, ordered=FALSE)
combN(n, m, replace=TRUE, ordered=TRUE)
combN(n, m, replace=FALSE, ordered=TRUE)
combN(n, m, replace=FALSE, ordered=FALSE)

Description

Returns all combinations of 2 out of the elements in x or x and y (if defined). Combinations of the same elements will be dropped (no replacing). The vector x need not contain unique values. Duplicate elements in x will result in duplicate pairs.

Usage

combPairs(x, y = NULL)

Arguments

Details

If y = NULL then all combination of 2 out of x are returned.
If y is defined then all combinations of x and y are calculated.

Value

a data.frame with two columns X1 and X2 containing the pairwise combinations.

See Also

combn(), expand.grid(), outer(), lower.tri()

Other combinatorics: combN(), combSet(), pairApply(), permn(), randGroupSplit(), sampleX()

Examples

combPairs(letters[1:4])
combPairs(x = letters[1:4], y = LETTERS[1:2])

# get all pairs of combinations between factors and numerics out of a data.frame
combPairs(which(sapply(CO2, is.numeric)), which(sapply(CO2, is.factor)))

Description

Return the value sets of combinations.

Usage

combSet(x, m, replace = FALSE, ordered = FALSE, output = c("matrix", "list"))

Arguments

Details

Depending on output, the result is returned either as:

• a matrix with one combination per row

• a flat list where each element represents one combination

If m contains more than one value, combinations are generated independently for each value of m.

Value

if output = "matrix":

• a matrix with one combination per row.

• if length(m) > 1, a list of matrices.

If output = "list":

• a flat list with one element per combination.

See Also

combn(), choose(), factorial(), vignette("Combinatorics")

Other combinatorics: combN(), combPairs(), pairApply(), permn(), randGroupSplit(), sampleX()

Examples

x <- letters[1:4]
m <- 2

# combinations with replacement
combSet(x, m, replace = TRUE, ordered = FALSE)

# ordered combinations with replacement
combSet(x, m, replace = TRUE, ordered = TRUE)

# ordered combinations without replacement
combSet(x, m, replace = FALSE, ordered = TRUE)

# unordered combinations without replacement
combSet(x, m, replace = FALSE, ordered = FALSE)

# return as flat list
x <- letters[1:5]

combSet(
  x = x,
  m = c(1, 3, 5),
  output = "list"
)

Description

Compares two data frames row-by-row based on a key column, identifying rows present in only one of the two frames and columns that differ in matched rows.

Usage

compareDataFrames(x, y, key)

Arguments

Details

Only columns present in both data frames are compared. Rows are matched by the key column using identical() for element-wise comparison, so type differences (e.g., integer vs. double) will be flagged as differences.

The values of the key column must be unique in both data frames.

Value

a named list with four elements:

identical

logical. TRUE if the two data frames are identical with respect to the common columns and key.

onlyInX

data frame of rows whose key value appears in x but not in y.

onlyInY

data frame of rows whose key value appears in y but not in x.

diffs

data frame with columns named after the key argument (the key value) and diffCols (a list column of character vectors naming the differing columns for that key).

See Also

Other data.equal: allDuplicated(), allIdentical()

Examples

x <- data.frame(id = c("A", "B", "C"), v1 = 1:3, v2 = c(10, 20, 30))
y <- data.frame(id = c("A", "B", "D"), v1 = c(1L, 9L, 4L), v2 = c(10, 20, 40))
compareDataFrames(x, y, key = "id")

Description

This function checks each element of a data frame or list-like object for missing values (NA) and identifies those that are completely observed, i.e., contain no missing entries.

Usage

completeColumns(x, output = c("names", "logical"))

Arguments

Details

An element is considered complete if it contains zero missing values. Internally, the function uses anyNA() to detect missing values.

Value

if output = "names", a character vector with the names of all complete elements.

If output = "logical", a logical vector of length length(x), where TRUE indicates that the corresponding element contains no missing values.

See Also

anyNA(), is.na(), na.omit(), complete.cases()

Other data.missing: countCompCases()

Examples

# Names of columns without missing values
completeColumns(airquality)

# Logical vector indicating completeness
completeColumns(airquality, output = "logical")

Description

Helper functions to inspect and analyse the use of ⁠\\concept⁠ tags within a package.

Usage

getConcepts(package, prefix = NULL)

conceptMap(package)

conceptAudit(package)

Arguments

Details

These utilities extract concept metadata from Rd files and allow structured auditing of conceptual organisation inside a package.

Functions

• getConcepts() - Returns all unique concepts used in a package.

• conceptMap() - Returns a mapping of concepts to functions.

• conceptAudit() - Returns a summary table of concept usage.

The functions use tools::Rd_db() to parse Rd files and extract ⁠\\concept⁠ tags programmatically.

These tools are intended for package development, documentation consistency checks, and conceptual audits.

Value

getConcepts

character vector of unique concept names, sorted

conceptMap

named list mapping concepts to topics

conceptAudit

data frame with the columns concept and nTopics, ordered by decreasing frequency

Examples

getConcepts("stats")
getConcepts("stats", prefix = "erf")
head(conceptMap("stats"))
head(conceptAudit("stats"))

Description

Return for each variable of a data frame the number of missing values and the complete cases to be expected if this variable would be omitted.

Usage

countCompCases(x)

Arguments

Value

a list with three elements. The first gives the number of rows, the second the number of complete cases for the whole data frame. The third element tab contains the data for the single variables.

See Also

pharos::plotMiss, complete.cases(), is.na(), na.omit()

Other data.missing: completeColumns()

Examples

countCompCases(airquality)

Description

Computes the cross product in three-dimensional space for vectors or matrices. For matrices, the operation can be applied row-wise or column-wise.

Usage

crossProd(x, y, orientation = c("rows", "cols"))

Arguments

Details

For vectors $x = (x_1, x_2, x_3)$ and $y = (y_1, y_2, y_3)$, the cross product is:

$x \times y = (x_2 y_3 - x_3 y_2,\; x_3 y_1 - x_1 y_3,\; x_1 y_2 - x_2 y_1)$

For matrix inputs:

• orientation = "rows": each row is treated as a vector (requires ncol(x) == 3)

• orientation = "cols": each column is treated as a vector (requires nrow(x) == 3)

Numeric and complex inputs can be mixed; standard R coercion rules apply.

Value

• a vector of length 3 if inputs are vectors.

• a matrix if matrices are supplied. Dimension names along the vector axis are propagated from x, the component axis is labelled x, y, z.

See Also

Other math.basic: closest(), crossProdN(), dotProd(), roundTo(), unirootAll()

Examples

# Vector case
crossProd(c(1,0,0), c(0,1,0))

# Row-wise
x <- matrix(c(1,0,0,
              0,1,0), ncol = 3, byrow = TRUE)
y <- matrix(c(0,1,0,
              0,0,1), ncol = 3, byrow = TRUE)
crossProd(x, y, "rows")

# Column-wise
x <- matrix(1:9, nrow = 3)
y <- matrix(9:1, nrow = 3)
crossProd(x, y, "cols")

Description

Computes a vector orthogonal to all rows of a matrix using a determinant-based construction. This generalizes the cross product to higher dimensions.

Usage

crossProdN(x)

Arguments

Details

For a matrix $A$ with dimensions $n x (n+1)$, the result is a vector in $R^{n+1}$ orthogonal to all rows of $A$. The components are given by:

$v_i = (-1)^{i+1} \det(A_{-i})$

where $A_{-i}$ is the matrix obtained by removing the $i$-th column.

For a vector of length 2, the function returns the perpendicular vector $(a_2, -a_1)$, consistent with the formula above.

Internally, the function computes a nullspace vector using SVD (which is numerically stable also for ill-conditioned input) and rescales it to match the magnitude of the determinant-based generalized cross product. For numeric input, the sign is chosen to reproduce the orientation of the determinant formula (and hence anticommutativity: swapping two rows of $A$ flips the sign of the result). For complex input, where det() is not available, the sign is fixed by the convention that the first component with non-zero modulus has a positive real part.

Value

a numeric or complex vector of length $n+1$.

See Also

Other math.basic: closest(), crossProd(), dotProd(), roundTo(), unirootAll()

Examples

# 2D case
crossProdN(c(1, 2))

# 3D case (standard cross product)
A <- matrix(c(1,0,0,
              0,1,0), nrow = 2, byrow = TRUE)
crossProdN(A)

# swapping rows flips the sign (anticommutativity)
crossProdN(A[2:1, ])

Description

Reads a documentation sheet from an Excel file and extracts variable descriptions and coding information.

Usage

dataDescription(file, sheet = "Description")

Arguments

Details

The function reads the specified sheet and trims trailing empty rows.

If a column named "Codes" is present, its contents are split by line breaks and returned as a list of codes per variable, keyed by the "Variable" column.

The Excel sheet is expected to contain at least:

• Variable names

• Descriptions

• Optional coding definitions

If the sheet does not exist or no additional sheets are present, the function returns NULL.

Value

a list with the following components:

• desctable: A data frame containing the description table.

• codes: A named list of code definitions per variable.

See Also

Other label.import: openDataObject()

Examples

fn <- system.file("extdata", "example.xlsx", package = "bedrock")

desc <- dataDescription(fn)
desc$desctable
desc$codes[["gender"]]

Description

Computes the sum of digits for whole-numbered inputs. Negative values are handled by taking the absolute value.

Usage

digitSum(x)

Arguments

Details

The function accepts integer vectors as well as doubles holding whole numbers (e.g. 124 and 124L are both valid). Fractional values raise an error. Missing values (NA) are propagated.

Value

an integer vector containing the digit sums.

See Also

Other number.theory: GCD-LCM, divisors(), factorize(), fibonacci(), isOdd(), isPrime(), primes()

Examples

digitSum(124)
digitSum(c(10L, 99L, -1234L))

Description

Calculate the proper divisors of positive natural numbers.

Usage

divisors(x)

Arguments

Details

Divisibility is a mathematical relationship between two integers. An integer is divisible by another integer if there is no remainder in the division. This function returns the proper divisors of x, i.e. all positive divisors excluding x itself. The number 11 is prime and has only the proper divisor 1, whereas the number 12 has the proper divisors 1, 2, 3, 4 and 6. In elementary number theory, the concept of divisibility is limited to natural numbers. The number of proper divisors can be determined with the function length().

Value

an integer vector containing the proper divisors in ascending order if x is a single number, otherwise a named list of such vectors. A prime number yields 1, and 1 itself yields integer(0) - its only divisor is 1, which is x itself and therefore not a proper one.

See Also

Other number.theory: GCD-LCM, digitSum(), factorize(), fibonacci(), isOdd(), isPrime(), primes()

Examples

divisors(786)

divisors(c(145, 786))

# the number of proper divisors
length(divisors(786))

# a prime has only one, and this one is at the integer limit
divisors(.Machine$integer.max)

Description

Computes the dot product between two numeric or complex vectors, or the column-wise dot products of two matrices with identical dimensions.

Usage

dotProd(x, y)

Arguments

Details

For vectors $x$ and $y$, the dot product is defined as:

$\sum_i \overline{x_i} y_i$

where $\overline{x_i}$ denotes the complex conjugate of $x_i$ (for real input this is simply $\sum_i x_i y_i$).

For matrices, the dot product of each column of x with the corresponding column of y is returned.

Note that crossprod() does not conjugate its first argument for complex input, so it computes $t(X) Y$ rather than the Hermitian inner product; this function does conjugate.

Value

• a scalar if x and y are vectors.

• a numeric or complex vector containing the column-wise dot products if matrices are supplied.

See Also

crossprod()

Other math.basic: closest(), crossProd(), crossProdN(), roundTo(), unirootAll()

Examples

# Vector dot product
dotProd(c(1, 2, 3), c(4, 5, 6))

# Complex vectors (Hermitian inner product)
dotProd(c(1+1i, 2), c(3, 4-1i))

# Matrix (column-wise dot products)
x <- matrix(1:6, ncol = 2)
y <- matrix(6:1, ncol = 2)
dotProd(x, y)

Description

Generate a matrix of dummy codes, also known as class indicators, for a factor or class vector.

Usage

dummy(
  x,
  method = c("treatment", "sum", "helmert", "poly", "full"),
  base = 1,
  levels = NULL
)

Arguments

Details

The argument method controls the contrast coding. The option "full" returns one indicator column for each level of x. This full-rank coding is usually redundant for lm() and related modelling functions.

The base argument is only used by method = "treatment". The other contrast types have no freely choosable baseline: "sum" implicitly uses the last level as reference, "helmert" contrasts each level against the preceding ones, and "poly" uses orthogonal polynomials.

Column names reflect the semantics of the coding: level names for "treatment" (without the baseline), "full" (all levels), "sum" (without the last level) and "helmert" (without the first level); "poly" keeps the standard degree labels (.L, .Q, ...).

Value

a matrix with dummy codes. The number of rows equals length(x). For method = "full", the number of columns equals the number of levels. Otherwise, the number of columns equals the number of levels minus one.

The returned matrix has an attribute "base" containing the baseline level for treatment coding, and NA otherwise.

See Also

model.frame(), contrasts(), contr.treatment(), contr.sum(), contr.helmert(), contr.poly()

Other data.recode: asBinary(), combLevels(), mReplace(), nf(), recodeX(), revCode(), stringsAsFactors()

Examples

x <- c("red", "blue", "green", "blue", "green", "red", "red", "blue")
dummy(x)
dummy(x, base = 2)
dummy(x, method = "sum")

y <- c("Max", "Max", "Max", "Max", "Max", "Bill", "Bill", "Bill")
dummy(y)
dummy(y, base = "Max")
dummy(y, base = "Max", method = "full")

# Revert full dummy coding
m <- dummy(y, method = "full")
apply(m, 1, function(z) colnames(m)[z == 1])

# Revert treatment dummy coding
m <- dummy(y)
apply(
  m,
  1,
  function(z) ifelse(sum(z) == 0, attr(m, "base"), colnames(m)[z == 1])
)

Description

Utility to extract a subset of arguments from a list (typically list(...)) and merge them with default values. Elements of dots override entries in defaults of the same name; explicit NULL values are preserved.

Usage

extractArgs(dots, defaults, validate = NULL, returnRest = FALSE)

Arguments

Value

named list of extracted arguments, or a list with components args and rest if returnRest = TRUE.

See Also

Other pkg.args: callIf(), getDotsArg(), mergeArgs(), recycle()

Examples

dots <- list(col = "red", lwd = 2, 99)
extractArgs(dots, defaults = list(col = "black", lty = 1))

extractArgs(dots, defaults = list(col = "black", lty = 1),
            returnRest = TRUE)

Description

Compute the prime factorization(s) of integer(s) x, using Pollard's rho algorithm with deterministic Miller-Rabin primality testing (64-bit, implemented in C++).

Usage

factorize(x)

Arguments

Details

x must not exceed 2^53 (9007199254740992), the largest integer up to which every integer can be represented exactly. Larger integers can still be representable – every power of two is – but not all of them are, and above this bound x may already have been rounded by R before it reaches this function, so a factorization could silently be correct for a different number than the one entered – for such inputs, use the gmp package's gmp::factorize(), which represents arbitrarily large integers exactly (e.g. via gmp::as.bigz() or a string).

Value

a named list() of the same length as x, each element a 2-column matrix with column "p" the prime factors in increasing order and column "m" their respective exponents (or multiplicities), i.e., for a prime number x, the resulting matrix is cbind(p = x, m = 1).

Each prime appears in exactly one row, so prod(p^m) returns x and p is strictly increasing. x = 1 yields a matrix with zero rows: 1 is the empty product, and prod(numeric(0)) is 1 accordingly.

See Also

Other number.theory: GCD-LCM, digitSum(), divisors(), fibonacci(), isOdd(), isPrime(), primes()

Examples

factorize(47)
factorize(seq(101, 120, by=2))

# the defining invariant
f <- factorize(360)[[1]]
f
prod(f[, "p"]^f[, "m"])

Description

Generate Fibonacci numbers. The Fibonacci numbers can also be calculated using the golden ratio phi, as demonstrated in the examples.

Usage

fibonacci(n)

Arguments

Details

Generates the n-th Fibonacci number, whereas fibonacci(0) = 0.
The golden ratio is defined as phi = 0.5*(1+sqrt(5)).

Values of n are limited to 78, as larger Fibonacci numbers exceed the range in which doubles represent integers exactly (2^53).

Value

an integer-valued numeric vector.

References

https://en.wikipedia.org/wiki/Fibonacci_number
https://mathworld.wolfram.com/GoldenRatio.html

See Also

Other number.theory: GCD-LCM, digitSum(), divisors(), factorize(), isOdd(), isPrime(), primes()

Examples

fibonacci(0)                            # 0
fibonacci(2)                            # 1
fibonacci(0:3)                          # 0 1 1 2
fibonacci(0:25)                         # ... 75025 121393

# Golden ratio = Fib(25)/ Fib(24)
f25 <- quot(fibonacci(24:25))           # 1.618033989
phi <- (sqrt(5) + 1)/2
abs(f25 - phi)                          # 7.945178e-11

# Fibonacci numbers without iteration
fibo <- function(n) {
  phi <- (sqrt(5) + 1)/2
  fib <- (phi^(n+1) - (1-phi)^(n+1)) / (2*phi - 1)
  round(fib)
}

fibo(30:33)                             # 1346269 2178309 3524578 5702887

Description

Returns the full path to a file located in the user's Downloads directory.

Usage

findDownload(file)

Arguments

Details

The function resolves the path to the user's Downloads directory using an internal helper and appends file. It does not perform any downloading; it only locates files that already exist locally.

If the file does not exist, an error is thrown.

Value

a character string giving the full path to the file.

See Also

Other file.path: buildPath(), isFilePath(), isUrl(), splitPath(), urlExists()

Examples

## Not run: 
# cannot be run automatically: reads the personal Downloads
# directory of the user, where no such file exists
findDownload("data.csv")

## End(Not run)

Description

Identify and extract dichotomous (binary) variables from a data frame or matrix using isDichotomous().

Usage

flags(
  x,
  strict = FALSE,
  na.rm = FALSE,
  output = c("data", "names", "index", "logical")
)

Arguments

Details

Variables with only missing values are not considered dichotomous when na.rm = FALSE.

When na.rm = TRUE, such variables are treated as empty vectors and are considered dichotomous only if strict = FALSE.

Internally, variables with indeterminate dichotomous status (i.e. NA returned by isDichotomous()) are treated as non-dichotomous for filtering purposes.

Value

depending on output:

• "data": data frame or matrix.

• "names": character vector.

• "index": integer vector.

• "logical": logical vector.

See Also

Other data.predicate: isDichotomous(), isEuclid(), isLowCardinality(), isNumeric(), isWholeLike(), isZero(), nUnique()

Examples

dat <- data.frame(
  a = c(0, 1, 1, 0),
  b = c(1, 2, 3, 4),
  c = c(TRUE, FALSE, TRUE, TRUE),
  d = c(NA, NA, NA, NA)
)

flags(dat)

# effect of na.rm
flags(dat, na.rm = TRUE)

# return variable names
flags(dat, output = "names")

# return column indices
flags(dat, output = "index")

Description

Returns the formal arguments of a function together with their default values.

Usage

funArgs(
  fun,
  package = NULL,
  sorted = FALSE,
  output = c("data.frame", "list", "string")
)

Arguments

Value

depending on output:

• "data.frame": a data frame with columns name and value.

• "list": a named list of formal arguments.

• "string": a character vector of length one.

See Also

formals(), args()

Other pkg.funinfo: auditNames(), funCalls(), funKeywords(), funList(), rdLabels(), rdTitle()

Examples

funArgs("combN")

funArgs("combN", output = "list")

funArgs("combN", output = "string")

cat(funArgs("combN", output = "string"))

Description

For screening purposes it can be useful to get a list of all function calls our function may depend on. funCalls() parses the function source and returns all found function calls grouped by their package.

Usage

funCalls(fun, package = NULL, sorted = FALSE)

Arguments

Details

The source packages are resolved via find(), which only sees attached packages. Calls to functions from packages that are not on the search path are reported under "<not found>".

Value

a list of character vectors with the function calls, grouped by the environment the called functions were found in.

Note

Based on code by Nicholas Cooper, adapted to conform to package standards.

See Also

getParseData()

Other pkg.funinfo: auditNames(), funArgs(), funKeywords(), funList(), rdLabels(), rdTitle()

Examples

funCalls("combN", package="bedrock")

Description

List the keywords for specific R man pages or return a list of valid R keywords.

Usage

funKeywords(topic)

Arguments

Details

If topic is provided, return a list of the Keywords associated with topic. Otherwise, display the list of valid R Keywords from the R doc/Keywords file.

Value

if topic is missing, the R keywords documentation file is opened for display via file.show(), invisibly returning NULL. Otherwise, a character vector of topic names whose keywords match topic.

Note

Substantially based on the keywords() function from the gtools package by Gregory R. Warnes, with minor adaptations by the package author.

See Also

help()

Other pkg.funinfo: auditNames(), funArgs(), funCalls(), funList(), rdLabels(), rdTitle()

Examples

## Show all valid R Keywords
funKeywords()

## Show Keywords associated with the 'merge' function
funKeywords(merge)
funKeywords("merge")

Description

List all the functions in a package.

Usage

funList(package, exported = TRUE)

Arguments

Details

This is just a wrapper for the namespace inspection functions (as I always forgot how to do the trick). By default only the exported functions are returned; with exported = FALSE all functions defined in the package namespace are listed, including internal ones.

Value

a sorted character vector with the function names.

References

Becker, R. A., Chambers, J. M. and Wilks, A. R. (1988) The New S Language. Wadsworth & Brooks/Cole.

See Also

ls(), ls.str(), lsf.str(), getNamespaceExports()

Other pkg.funinfo: auditNames(), funArgs(), funCalls(), funKeywords(), rdLabels(), rdTitle()

Examples

funList("bedrock")

Description

Calculates the greatest common divisor (GCD) and least common multiple (LCM) of all the values present in its arguments.

Usage

GCD(..., na.rm = FALSE)

LCM(..., na.rm = FALSE)

Arguments

Details

The computation is based on the Euclidean algorithm without using the extended version. The greatest common divisor for all numbers in the integer vector x will be computed (the multiple GCD). Negative values are allowed and enter via their absolute value; logical vectors are coerced to integer.

Value

a numeric (integer) value.

Zero

Zero behaves differently in the two functions, which is why they do not treat it the same way. For the greatest common divisor it is neutral - every number divides 0, so GCD(0, a) is abs(a) and zeros can simply be dropped. For the least common multiple it is absorbing - 0 is a multiple of every number and the smallest non-negative one, so LCM(0, a) is 0. GCD(0, 0) and LCM(0, 0) are both 0.

Note

The following relation is always true:

n * m = GCD(n, m) * LCM(n, m)

It also holds when one of the values is zero, and that is the shortest way to see why LCM(0, 6) has to be 0 rather than 6.

See Also

Other number.theory: digitSum(), divisors(), factorize(), fibonacci(), isOdd(), isPrime(), primes()

Examples

GCD(12, 10)
GCD(144, 233)    # Fibonacci numbers are relatively prime to each other

LCM(12, 10)
LCM(144, 233)    # = 144 * 233

# all elements will be flattened by unlist
GCD(2, 3, c(5, 7) * 11)
GCD(c(2*3, 3*5, 5*7))
LCM(c(2, 3, 5, 7) * 11)
LCM(2*3, 3*5, 5*7)

# zero is neutral for the GCD and absorbing for the LCM
GCD(0, 6)
LCM(0, 6)

# n * m == GCD(n, m) * LCM(n, m), zero included
GCD(0, 6) * LCM(0, 6)

Description

Lightweight helper to extract a single named argument from a list (typically list(...)). If the argument is not present, a default value is returned.

Usage

getDotsArg(dots, name, default = NULL)

Arguments

Value

the value of the argument or default.

See Also

For extracting several arguments at once use extractArgs().

Other pkg.args: callIf(), extractArgs(), mergeArgs(), recycle()

Examples

f <- function(...) {
  dots <- list(...)
  getDotsArg(dots, "col", default = "black")
}

f(col = "red", lwd = 2)
f(lwd = 2)

Description

Functions for computing relationships between numeric intervals. All functions accept intervals as numeric vectors of length 2 or matrices with 2 columns (one interval per row). Unordered bounds are silently sorted; rows are recycled to equal length.

Usage

overlapSize(x, y)

overlaps(x, y)

distance(x, y)

x %overlaps% y

Arguments

Details

Intervals are treated as closed, i.e., $[a, b]$. Consequently:

• Two intervals sharing only a boundary point have overlap 0 but overlaps returns TRUE.

• distance returns 0 whenever intervals touch or overlap.

• The returned vector is always unnamed, whatever dimnames the inputs carry.

Value

overlap

numeric vector of overlap lengths (0 if no overlap).

overlaps

logical vector; TRUE if intervals share at least one point.

distance

numeric vector of gap lengths between non-overlapping intervals (0 if overlapping or touching).

⁠%overlaps%⁠

logical vector; operator wrapper for overlaps().

See Also

Other data.interval: between-operators, range-operators

Examples

# overlap length
overlapSize(c(1, 5), c(3, 7))   # 2
overlapSize(c(1, 3), c(3, 5))   # 0 (boundary only)

# overlap check
overlaps(c(1, 5), c(3, 7))  # TRUE
overlaps(c(1, 3), c(3, 5))  # TRUE  (boundary counts)
overlaps(c(1, 2), c(3, 4))  # FALSE

# gap distance
distance(c(1, 2), c(4, 5))  # 2
distance(c(1, 5), c(3, 7))  # 0

# operator
c(1, 5) %overlaps% c(3, 7)  # TRUE

# vectorised (matrix input)
m <- matrix(c(1,3, 2,6, 5,8), ncol = 2, byrow = TRUE)
overlapSize(m, c(4, 7))

Description

Determines whether a vector contains at most two distinct values.

Usage

isDichotomous(x, strict = FALSE, na.rm = FALSE)

Arguments

Value

TRUE, FALSE, or NA if the status cannot be determined because of missing values (see na.rm).

See Also

Other data.predicate: flags(), isEuclid(), isLowCardinality(), isNumeric(), isWholeLike(), isZero(), nUnique()

Examples

isDichotomous(c(0, 1, 1))
isDichotomous(c(1, 1, 1))
isDichotomous(c(1, 1, 1), strict = TRUE)
isDichotomous(c(0, 1, NA))               # NA
isDichotomous(c(0, 1, NA), na.rm = TRUE)
isDichotomous(c("A", "A", "B"))
isDichotomous(c("A", "A", "B", "C"))
isDichotomous(factor(c("A", "A", "B", "C")))

Description

Checks whether a distance matrix corresponds to Euclidean distances.

Usage

isEuclid(x, tol = 0.0000001)

Arguments

Details

The test is based on the eigenvalues of the double-centered squared distance matrix $B = -\frac{1}{2} J D^2 J$. A distance matrix is Euclidean if and only if $B$ is positive semi-definite, i.e., all eigenvalues are non-negative (within numerical tolerance).

The tolerance is applied relative to the largest absolute eigenvalue, so that the test is invariant to rescaling of the distances. Note that this holds in both directions: the comparison below uses max(abs(lambda)) without an absolute floor, so shrinking all distances by a constant factor cannot turn a non-Euclidean matrix into a Euclidean one.

The returned logical value carries additional diagnostic information as attributes:

• eigenvalues: Eigenvalues of the centered matrix

• minEigenvalue: Smallest eigenvalue

• tol: Tolerance used for the test

Value

a logical scalar. Returns TRUE if the distance matrix is (approximately) Euclidean, otherwise FALSE.

See Also

Other data.predicate: flags(), isDichotomous(), isLowCardinality(), isNumeric(), isWholeLike(), isZero(), nUnique()

Examples

d <- dist(matrix(rnorm(20), ncol = 2))
res <- isEuclid(d)
res

# Access diagnostics
attr(res, "eigenvalues")
attr(res, "minEigenvalue")

Description

Returns TRUE if the given string looks like a local file path (absolute or relative, Unix/Windows style), FALSE otherwise. Convenience wrapper around the internal .detectInputType() helper.

Usage

isFilePath(x)

Arguments

Value

logical(1) - TRUE if x is a file path, FALSE otherwise.

See Also

isUrl() for the complementary URL check.

Other file.path: buildPath(), findDownload(), isUrl(), splitPath(), urlExists()

Examples

isFilePath("/home/user/data/file.csv")   # TRUE
isFilePath("~/documents/report.pdf")     # TRUE
isFilePath("./relative/path/file.R")     # TRUE
isFilePath("../other/folder/data.rds")   # TRUE
isFilePath("C:/Users/Hans/file.xlsx")    # TRUE
isFilePath("https://example.com/f.csv")  # FALSE

Description

Checks whether x contains at most maxUnique unique, non-missing values. Unlike nUnique(), this stops counting as soon as the threshold is exceeded, which makes it considerably faster for large, high-cardinality vectors.

Usage

isLowCardinality(x, maxUnique = 12)

Arguments

Value

a logical of length one: TRUE if x has maxUnique or fewer unique, non-NA values, FALSE otherwise.

See Also

nUnique() for the uncapped count.

Other data.predicate: flags(), isDichotomous(), isEuclid(), isNumeric(), isWholeLike(), isZero(), nUnique()

Examples

isLowCardinality(c(1, 2, 2, 3, NA))

isLowCardinality(1:100, maxUnique = 12)

Description

Check whether an object is a single missing value (NA).

Usage

isNA(x)

Arguments

Details

This is a strict helper that returns TRUE only if x is an atomic vector of length one and equal to NA. In contrast to is.na(), which is vectorized, isNA is intended for scalar checks, e.g. in conditional statements.

This function differs from is.na() in that it:

• Only returns TRUE for length-one inputs

• Returns a single logical value (not vectorized)

• Works consistently across all NA types

Value

logical scalar. Returns TRUE if x is a single missing value (NA), and FALSE otherwise.

See Also

Other vector.na: coalesceX(), locf(), naIf(), naReplace()

Examples

isNA(NA)             # TRUE
isNA(NA_real_)       # TRUE
isNA(NA_integer_)    # TRUE

isNA(c(NA, NA))      # FALSE (length > 1)
isNA(NULL)           # FALSE
isNA(1)              # FALSE
isNA(c(1, NA))       # FALSE

Description

Validates that an object is numeric and optionally satisfies additional structural constraints such as integer-valuedness or positivity.

Usage

isNumeric(
  x,
  isIntegerValued = FALSE,
  isPositive = FALSE,
  tol = sqrt(.Machine$double.eps),
  na.rm = FALSE
)

Arguments

Details

The function checks:

• Whether x is numeric.

• Whether all values are finite.

• Optional integer-like constraint via isWholeLike().

• Optional positivity constraint.

This function is intended for internal validation in statistical routines. Length validation is the responsibility of the caller and should be performed separately with an explicit length() check.

Value

a single logical value.

See Also

Other data.predicate: flags(), isDichotomous(), isEuclid(), isLowCardinality(), isWholeLike(), isZero(), nUnique()

Examples

isNumeric(c(1, 2, 3))
isNumeric(c(1, 2.1, 3), isIntegerValued = TRUE)
isNumeric(c(1, -2, 3), isPositive = TRUE)
isNumeric(c(1, NA), na.rm = TRUE)

Description

Checks whether elements of a numeric vector are odd integers.

Usage

isOdd(x)

Arguments

Details

The function first checks whether values are finite integers. Non-integer values (e.g. 3.5), NA, NaN, or Inf return NA. A bare logical NA is accepted and treated as a missing numeric value.

Value

a logical vector of the same length as x. Returns TRUE for odd integers, FALSE for even integers, and NA for non-integer or non-finite values.

See Also

Other number.theory: GCD-LCM, digitSum(), divisors(), factorize(), fibonacci(), isPrime(), primes()

Examples

isOdd(1:5)
isOdd(c(2, 3, 4.5, NA, Inf))

Description

Determines whether integer values are prime numbers.

Usage

isPrime(x)

Arguments

Details

This function is vectorized and returns a logical vector of the same length as the input.

Internally, a fast deterministic primality test for 64-bit integers is used.

Non-integer, negative, missing, or non-finite values result in FALSE: there the answer is known, it simply is not "prime".

Value

a logical vector indicating whether each element of x is a prime number, NA where x exceeds 2^53.

Upper limit

Values above 2^53 (9007199254740992) return NA with a warning, because for them there is no answer to give. 2^53 is the largest integer up to which every integer is exactly representable; above it the representable integers thin out, so the value that reaches the test need not be the value that was entered: R parses 9007199254740997, which is prime, as 9007199254740996. Every representable double above 2^53 is even, so testing the neighbour would report FALSE for every prime beyond the bound – silently, and with no way for the caller to notice. For larger numbers, use gmp::isprime() with a gmp::as.bigz() or character input.

factorize() carries the same bound but rejects the input with an error instead. The difference is deliberate: factorize() answers one number per call element and can refuse the call, whereas a vectorized predicate should not let a single unrepresentable element discard the result for all the others.

See Also

Other number.theory: GCD-LCM, digitSum(), divisors(), factorize(), fibonacci(), isOdd(), primes()

Examples

isPrime(2)
isPrime(1:10)
isPrime(c(17, 18, 19))

Description

Returns TRUE if the given string starts with a recognised URL scheme, FALSE otherwise. Convenience wrapper around the internal .detectInputType() helper.

Usage

isUrl(x)

Arguments

Value

logical(1) - TRUE if x is a URL, FALSE otherwise.

See Also

For the complementary check on an existing path, see isFilePath().

Other file.path: buildPath(), findDownload(), isFilePath(), splitPath(), urlExists()

Examples

isUrl("https://example.com/data.csv")   # TRUE
isUrl("ftp://files.example.org/x.zip")  # TRUE
isUrl("s3://my-bucket/file.parquet")    # TRUE
isUrl("/home/user/file.csv")            # FALSE
isUrl("./script.R")                     # FALSE

Description

Checks whether values are integer-like within a numerical tolerance. Works for numeric, integer, and complex vectors.

Usage

isWholeLike(
  x,
  all = TRUE,
  isNonNegative = FALSE,
  tol = sqrt(.Machine$double.eps),
  na.rm = FALSE
)

Arguments