Package 'zmisc'

Description

This function replaces non-ASCII characters in a string with their ASCII equivalents. It supports a range of European non-ASCII characters, including Icelandic, Swedish, Norwegian, Danish, Finnish, German, Estonian, Latvian, Lithuanian, Polish, Hungarian, Slovenian, Czech, Slovak, Maltese, Romanian, Albanian, and Croatian.

Usage

asciify(x, verify = TRUE)

Arguments

Value

A character vector with non-ASCII characters replaced by their ASCII equivalents.

Examples

asciify("Jón Þór Birgisson") # "Jon Thor Birgisson"
asciify("förståndshandikapp") # "forstandshandikapp"
asciify("Viðareiði") # "Vidareidi"
asciify("übermensch") # "uebermensch"
asciify("Jürgen Klopp") # "Juergen Klopp"
asciify("rõõmsameelsus") # "roomsameelsus"
asciify("Mężczyzna") # "Mezczyzna"
asciify("Škoda") # "Skoda"

Description

Validity checks for atomic vectors. See chk_composite for lists and other composite objects, and chk_other for various other checks.

Each function below takes the same arguments whenever they apply, including null.ok, na.ok, zero.ok, attr.ok, length and range.

They are meant to be cheap enough to leave at the top of any function, a passing value with default arguments tends to take under a microsecond on a modern computer; with extra specification arguments it can take up to ten microseconds. Assembling a good message happens on the failing path, which runs once and then stops.

• ¹ integerish refers to functional integers (numbers that are very close to integer values), regardless of type (integer or double)

• ² naturalish refers to functional integers restricted to the natural numbers (zero and positive numbers)

• ³ No check functions are provided for scalar factor, complex, or raw

Usage

chk_flag(x, ..., null.ok = FALSE, na.ok = FALSE, attr.ok = "names")

chk_logical(x, ..., null.ok = FALSE, na.ok = TRUE, attr.ok = "names",
  length = NULL)

chk_string(x, ..., null.ok = FALSE, na.ok = FALSE, attr.ok = "names",
  range = NULL)

chk_character(x, ..., null.ok = FALSE, na.ok = TRUE, attr.ok = "names",
  length = NULL, range = NULL)

chk_number(x, ..., null.ok = FALSE, na.ok = FALSE, attr.ok = "names",
  range = NULL)

chk_numeric(x, ..., null.ok = FALSE, na.ok = TRUE, attr.ok = "names",
  length = NULL, range = NULL)

chk_inumber(x, ..., null.ok = FALSE, na.ok = FALSE, attr.ok = "names",
  range = NULL)

chk_integer(x, ..., null.ok = FALSE, na.ok = TRUE, attr.ok = "names",
  length = NULL, range = NULL)

chk_dnumber(x, ..., null.ok = FALSE, na.ok = FALSE, attr.ok = "names",
  range = NULL)

chk_double(x, ..., null.ok = FALSE, na.ok = TRUE, attr.ok = "names",
  length = NULL, range = NULL)

chk_znumber(x, ..., null.ok = FALSE, na.ok = FALSE, attr.ok = "names",
  range = NULL)

chk_integerish(x, ..., null.ok = FALSE, na.ok = TRUE, attr.ok = "names",
  length = NULL, range = NULL)

chk_count(x, ..., null.ok = FALSE, na.ok = FALSE, zero.ok = TRUE,
  attr.ok = "names")

chk_naturalish(x, ..., null.ok = FALSE, na.ok = TRUE, zero.ok = TRUE,
  attr.ok = "names", length = NULL, range = NULL)

chk_factor(x, ..., null.ok = FALSE, na.ok = TRUE, attr.ok = "names",
  length = NULL)

chk_complex(x, ..., null.ok = FALSE, na.ok = TRUE, attr.ok = "names",
  length = NULL)

chk_raw(x, ..., null.ok = FALSE, attr.ok = "names", length = NULL)

chk_day(x, ..., null.ok = FALSE, na.ok = FALSE, attr.ok = "names",
  range = NULL)

chk_date(x, ..., null.ok = FALSE, na.ok = TRUE, attr.ok = "names",
  length = NULL, range = NULL)

chk_instant(x, ..., null.ok = FALSE, na.ok = FALSE, attr.ok = "names",
  range = NULL)

chk_posixct(x, ..., null.ok = FALSE, na.ok = TRUE, attr.ok = "names",
  length = NULL, range = NULL)

chk_scalar(x, ..., null.ok = FALSE, na.ok = FALSE, attr.ok = "names")

chk_atomic(x, ..., na.ok = TRUE, attr.ok = "names", length = NULL)

Arguments

Value

The original object if the check passes.

See Also

chk_composite for lists and list-based objects, and chk_other for classes, conditions, and various other checks

Examples

# A check returns its input (invisibly), so it composes in a pipe
c(2, 4, 6) |> chk_numeric(length = 3) |> sum()

# One parameter set across the whole family
chk_string("abc", range = c(1, 3))
chk_integer(1:5, length = c(1, 10))

# On failure, the error names the argument as the caller wrote it
my_mean <- function(x) {
  chk_numeric(x)
  sum(x) / length(x)
}
tryCatch(my_mean("seven"), error = wrap_error)

Description

Checks for composite objects. See chk_atomic for scalar and vector types, and chk_other for various other checks.

Usage

chk_environment(x, ..., null.ok = FALSE, contains = character())

chk_list(x, ..., null.ok = FALSE, attr.ok = "names", length = NULL)

chk_data_frame(x, ..., null.ok = FALSE)

chk_data_table(x, ..., null.ok = FALSE)

chk_tibble(x, ..., null.ok = FALSE)

Arguments

Value

The original object if the check passes.

See Also

chk_atomic for the scalar and vector types, and chk_other for classes, conditions, and the rlang aliases.

Examples

chk_data_frame(mtcars)
chk_list(list(a = 1, b = 2), length = 2)

# chk_list() only accepts bare (unclassed) lists
tryCatch(chk_list(mtcars), error = wrap_error)

Description

Various checks not directly related to atomic vectors (see chk_atomic), or composite objects (see chk_composite).

chk_true() is a catch-all function that can be used to implement arbitrary checks (by checking any expression that should be true).

chk_that() provides an alternative for checking that an expression is true, but separates the value to be checked (x) from the expression evaluated on it (expr), which makes an arbitrary condition usable on an object passing through a pipe.

chk_class() provides a quick way to check the class of an object.

chk_match() can be used either as an equivalent to rlang::arg_match() or match.arg() for checking a function argument against default values in a function, or to check that any variable x is an element of a vector of values. Both must be bare atomic vectors of the same type, except that integer and double count as one type. When used to select default value in a function, it must be called as arg <- chk_match(arg).

chk_dots_empty() verifies that no arguments were passed to the ... parameters, similarly to rlang::check_dots_empty().

chk_any(...) can be used to combine multiple other checks, and will fail only if all constituent checks fail.

Usage

chk_true(x, ..., na.ok = FALSE)

chk_that(x, expr, ..., na.ok = FALSE, bindings = ".")

chk_class(x, classes, ..., null.ok = FALSE, ordered = FALSE)

chk_match(x, values = NULL, ..., multiple = NULL)

chk_dots_empty()

chk_any(...)

Arguments

Details

chk_any() evaluates its arguments in turn and returns the value of the first that passes. If none pass, it raises one error reporting every failure. It is how a composite requirement is written, where each individual ⁠chk_*()⁠ function states only one thing:

chk_any(chk_string(x), chk_number(x))

Only the checks chk_any() calls itself are candidates. One reached through a helper function, or from inside a lambda passed to lapply(), throws where it stands, and so does everything that is not a failed check: a misspelled function, an argument that does not exist, an object that was never bound.

The arguments are captured as expressions and evaluated in the calling environment, which rules out two ways of reaching chk_any() indirectly. ... cannot be forwarded into it from another function, and an object cannot be piped into it. Both raise an error rather than being accommodated, since the first would evaluate the checks in the wrong scope and the second would return the piped object as a branch that passed. Write the checks at the call site, naming the object in each.

Value

The original object if the check passes. chk_match() returns the matched value visibly, chk_dots_empty() returns NULL invisibly, and chk_any() returns the value of the first argument that passes, which is the object that was checked.

See Also

chk_atomic for the scalar and vector types, and chk_composite for lists and composite objects.

Examples

# Any property that can be written as a condition
chk_true(nrow(mtcars) > 10)
mtcars |> chk_that(nrow(.) > 10) |> ncol()

# Match an argument against the values in its own default
plot_kind <- function(kind = c("scatter", "line", "bar")) chk_match(kind)
plot_kind()
tryCatch(plot_kind("pie"), error = wrap_error)

# Any bare atomic type, with integer and double interchangeable
chk_match(2, 1:3)

# chk_any() takes the first check that passes
x <- "a"
chk_any(chk_string(x), chk_number(x))
tryCatch(chk_any(chk_number(x), chk_logical(x)), error = wrap_error)

Description

Applies glue::glue() to each element of a character vector using a template string, enabling pipe-friendly, element-wise interpolation. Useful when the vector to process is not encapsulated in a data.frame or other environment-like object.

The glue::glue() and glue::glue_data() functions are also re-exported for convenience

Usage

glue_vector(., template = "{.}",
  ...,
  .sep = "", .envir = parent.frame(), .open = "{", .close = "}",
  .na = "NA", .null = character(), .comment = "#", .literal = FALSE,
  .transformer = glue::identity_transformer, .trim = TRUE
)

Arguments

Value

A character vector with interpolated values. The length is determined by tidyverse recycling rules for all referenced variables.

Examples

letters |> glue_vector("Letters include {.} and {LETTERS}")

Description

The lookup() function implements lookup of values (such as variable names) from a lookup table which maps keys onto values (such as variable labels or descriptions).

The lookup table can be in the form of a two-column data.frame, in the form of a named vector, or in the form of a list. If the table is in the form of a data.frame, the key column should be named either key or name, and the value column should be named value (for the value). If the lookup table is in the form of a named vector or list, the names are used as the key, and the returned value is taken from the values in the vector or list.

The underlying lookup is done using base::match(), and all atomic data types except factor are supported. Factors are omitted due to the ambiguity in what should be looked up (the values or the levels). It is important that x, .default and the columns of lookup_table are all of the same type (specifically of the same base::mode()). If the lookup table is specified as a vector or list, only the character variables are supported, because name(lookup_table) is always of mode character.

Original values are returned if they are not found in the lookup table. Alternatively, a .default can be specified for values that are not found. Note that it is possible to specify NA as one of the keys to look up NA values (only when using a data.frame as lookup table).

Any names or attributes of x are preserved.

The lookuper() function returns a function equivalent to the lookup() function, except that instead of taking a lookup table as an argument, the lookup table is embedded in the function itself.

This can be very useful, in particular when using the lookup function as an argument to other functions that expect a function which maps character->character (or other data types), but do not offer a good way to pass additional arguments to that function.

Usage

lookup(x, lookup_table, ..., .default = x)

lookuper(lookup_table, ..., .default = NULL)

Arguments

Value

The lookup() function returns a vector based on x, with values replaced with the lookup values from lookup_table. Any values not found in the lookup table are taken from .default.

The lookuper() function returns a function that takes vectors as its argument x, and returns either the corresponding values from the underlying lookup table, or the original values from x for those elements that are not found in the lookup table (or looks them up from the default).

Examples

fruit_lookup_vector <- c(a = "Apple", b = "Banana", c = "Cherry")
lookup(letters[1:5], fruit_lookup_vector)
lookup(letters[1:5], fruit_lookup_vector, .default = NA)

mtcars_lookup_data_frame <- data.frame(
  name = c("mpg", "hp", "wt"),
  value = c("Miles/(US) gallon", "Gross horsepower", "Weight (1000 lbs)"))
lookup(names(mtcars), mtcars_lookup_data_frame)

# A more complex example, with numeric and NA values
numeric_lookup_table <- data.frame(
  key = c(1:5, NA), value = c(sqrt(1:5), 99999))
lookup(c(0:6, NA), numeric_lookup_table)

lookup_fruits <- lookuper(list(a = "Apple", b = "Banana", c = "Cherry"))
lookup_fruits(letters[1:5])
lookup_fruits_nomatch_na <-
  lookuper(list(a = "Apple", b = "Banana", c = "Cherry"), .default = NA)
lookup_fruits_nomatch_na(letters[1:5])

Description

This function adds level/label information as an annotation to either factors or labelled variables. This function is called notate() rather than annotate() to avoid conflict with ggplot2::annotate(). It is a generic that can operate either on individual vectors or on a data.frame.

When printing labelled variables from a tibble in a console, both the numeric value and the text label are shown, but no variable labels. When using the View() function, only variable labels are shown but no value labels. For factors, there is no way to view the integer levels and values at the same time.

In order to allow the viewing of both variable and value labels at the same time, this function converts both factor and labelled variables to character, including both numeric levels (labelled values) and character values (labelled labels) in the output.

Usage

notate(x)

Arguments

Value

The processed data.frame, suitable for viewing, in particular through the View() function.

Examples

if (getRversion() >= "4") {
  d <- data.frame(
    chr = letters[1:4],
    fct = factor(c("alpha", "bravo", "chrly", "delta")),
    lbl = ll_labelled(c(1, 2, 3, NA),
                      labels = c(one=1, two=2),
                      label = "A labelled vector")
  )
  dn <- notate(d)
  dn
  # View(dn)
}

Description

Yet (another urlencode compatible) encoding scheme

Usage

yencode(string, escape = "%", whitelist = c("._~-", "][!$&'()*+,;=:/?@#"))

yencoder(escape = "%", whitelist = c("._~-", "][!$&'()*+,;=:/?@#"))

ydecode(string, escape = "%")

ydecoder(escape = "%")

Arguments

Details

Letters and digits are never escaped. Other characters are escaped unless they appear in whitelist, which may include multi-byte characters. The escape character is removed from the whitelist, with a warning, if present, and must itself be a single ASCII character.

yencode() escapes the UTF-8 representation of string, whatever its declared encoding, so the same text always gives the same result. ydecode() returns strings marked as UTF-8, and raises an error if an escape sequence is malformed or the decoded bytes are not valid UTF-8.

Value

The processed (encoded or decoded) string.

Description

The zample() function duplicates the functionality of sample(), with the exception that it does not attempt the (sometimes dangerous) user-friendliness of switching the interpretation of the first element to a number if the length of the vector is 1.

zample() always treats its first argument as a vector containing elements that should be sampled, so code won't break in unexpected ways when the input vector happens to be of length 1. The sample is taken by subsetting x, so the class and attributes of x are preserved.

If the goal is indeed to sample from an interval between 1 and n, use use sample(n) or sample.int(n) (but make sure to only pass vectors of length one to those functions).

Usage

zample(x, size = length(x), replace = FALSE, prob = NULL)

Arguments

Value

The resulting sample, of the same class as x

Examples

# For vectors of length 2 or more, zample() and sample() are identical
set.seed(42); zample(7:11)
set.seed(42); sample(7:11)

# For vectors of length 1, zample() will still sample from the vector,
# whereas sample() will "magically" switch to interpreting the input
# as a number n, and sampling from the vector 1:n.
set.seed(42); zample(7)
set.seed(42); sample(7)

# The other arguments work in the same way as for sample()
set.seed(42); zample(7:11, size=13, replace=TRUE, prob=(5:1)^3)
set.seed(42); sample(7:11, size=13, replace=TRUE, prob=(5:1)^3)

# Of course, sampling more than the available elements without
# setting replace=TRUE will result in an error
set.seed(42); tryCatch(zample(7, size=2), error=wrap_error)

Description

The zeq() function creates an increasing integer sequence, but differs from the standard one in that it will not silently generate a decreasing sequence when the second argument is smaller than the first. If the second argument is one smaller than the first it will generate an empty sequence, if the difference is greater, the function will throw an error.

Both arguments must be a single integerish value (an integer, or a double that is very close to one), and neither may be NA. Passing a vector of length other than one is an error.

Usage

zeq(from, to)

Arguments

Value

An integer sequence ranging from from to to, or an empty integer vector if to equals from - 1.

Examples

# For increasing sequences, zeq() and seq() are identical
zeq(11,15)
zeq(11,11)

# If second argument equals first-1, an empty sequence is returned
zeq(11,10)

# If second argument is less than first-1, the function throws an error
tryCatch(zeq(11,9), error=wrap_error)

# Each bound must be a single whole number, so this errors as well
tryCatch(zeq(c(11,12),15), error=wrap_error)

Description

zingle() returns the only value present in a vector. If the vector contains more than one distinct value, it throws an error. This is a guard for aggregations where all values within a group should be identical, but where you want that assumption checked rather than assumed. Only values are compared. Names are ignored and the result is unnamed, in line with other aggregation functions.

Usage

zingle(x, ...,
  empty.ok      = FALSE,
  na.ok.partial = FALSE,
  na.ok.all     = FALSE,
  nan.ok.all    = FALSE
)

Arguments

Value

The single element in the vector, unnamed. For na.ok.partial the non-missing value is returned.

Examples

zingle(c("Alpha", "Alpha", "Alpha"))
zingle(c("Alpha", NA, "Alpha"), na.ok.partial = TRUE)
zingle(c(NA, NA), na.ok.all = TRUE)
zingle(c(NaN, NaN), nan.ok.all = TRUE)