row-col-notation {RCLabels}

Row and column notation

Description

It is often convenient to represent matrix row and column names with notation that includes a prefix and a suffix, with corresponding separators or start-end string sequences. There are several functions to generate specialized versions or otherwise manipulate row and column names on their own or as row or column names.

• flip_pref_suff() Switches the location of prefix and suffix, such that the prefix becomes the suffix, and the suffix becomes the prefix. E.g., "a -> b" becomes "b -> a" or "a [b]" becomes "b [a]".

• get_pref_suff() Selects only prefix or suffix, discarding notational elements and the rejected part. Internally, this function calls split_pref_suff() and selects only the desired portion.

• notation_vec() Builds a vector of notation symbols in a standard format. By default, it builds a list of notation symbols that provides an arrow separator (" -> ") between prefix and suffix.

• paste_pref_suff() paste0's prefixes and suffixes, the inverse of split_pref_suff(). Always returns a character vector.

• preposition_notation() Builds a list of notation symbols that provides (by default) square brackets around the suffix with a preposition ("prefix [preposition suffix]").

• split_pref_suff() Splits prefixes from suffixes, returning each in a list with names pref and suff. If no prefix or suffix delimiters are found, x is returned in the pref item, unmodified, and the suff item is returned as "" (an empty string). If there is no prefix, and empty string is returned for the pref item. If there is no suffix, and empty string is returned for the suff item.

• switch_notation() Switches from one type of notation to another based on the from and to arguments. Optionally, prefix and suffix can be flipped.

Parts of a notation vector are "pref_start", "pref_end", "suff_start", and "suff_end". None of the strings in a notation vector are considered part of the prefix or suffix. E.g., "a -> b" in arrow notation means that "a" is the prefix and "b" is the suffix. If sep only is specified for notation_vec() (default is " -> "), pref_start, pref_end, suff_start, and suff_end are set appropriately.

For functions where the notation argument is used to identify portions of the row or column label (such as split_pref_suff(), get_pref_suff(), and the from argument to switch_notation()), (Note: flip_pref_suff() cannot infer notation, because it switches prefix and suffix in a known, single notation.) if notation is a list, it is treated as a store from which the most appropriate notation is inferred by infer_notation(choose_most_specific = TRUE). Because default is RCLabels::notations_list, notation is inferred by default. The argument choose_most_specific tells what to do when two notations match a label: if TRUE (the default), the notation with most characters is selected. If FALSE, the first matching notation in notation will be selected. See details at infer_notation().

If specifying more than one notation, be sure the notations are in a list. notation = c(RCLabels::bracket_notation, RCLabels::arrow_notation) is unlikely to produce the desired result, because the notations are concatenated together to form a long string vector. Rather say notation = list(RCLabels::bracket_notation, RCLabels::arrow_notation).

For functions that construct labels (such as paste_pref_suff()), notation can be a list of notations over which the paste tasks is mapped. If notation is a list, it must have as many items as there are prefix/suffix pairs to be pasted.

If either pref or suff are a zero-length character vector (essentially an empty character vector such as obtained from character()) input to paste_pref_suff(), an error is thrown. Instead, use an empty character string (such as obtained from "").

Usage

notation_vec(
  sep = " -> ",
  pref_start = "",
  pref_end = "",
  suff_start = "",
  suff_end = ""
)

preposition_notation(preposition, suff_start = " [", suff_end = "]")

split_pref_suff(
  x,
  transpose = FALSE,
  inf_notation = TRUE,
  notation = RCLabels::notations_list,
  choose_most_specific = TRUE
)

paste_pref_suff(
  ps = list(pref = pref, suff = suff),
  pref = NULL,
  suff = NULL,
  notation = RCLabels::arrow_notation,
  squish = TRUE
)

flip_pref_suff(
  x,
  notation = RCLabels::notations_list,
  inf_notation = TRUE,
  choose_most_specific = TRUE
)

get_pref_suff(
  x,
  which = c("pref", "suff"),
  inf_notation = TRUE,
  notation = RCLabels::notations_list,
  choose_most_specific = TRUE
)

switch_notation(
  x,
  from = RCLabels::notations_list,
  to,
  flip = FALSE,
  inf_notation = TRUE
)

Arguments

sep

A string separator between prefix and suffix. Default is " -> ".

pref_start

A string indicating the start of a prefix. Default is NULL.

pref_end

A string indicating the end of a prefix. Default is the value of sep.

suff_start

A string indicating the start of a suffix. Default is the value of sep.

suff_end

A string indicating the end of a suffix. Default is NULL.

preposition

A string used to indicate position for energy flows, typically "from" or "to" in different notations.

x

A string or vector of strings to be operated upon.

transpose

A boolean that tells whether to purr::transpose() the result. Set transpose = TRUE when using split_pref_suff() in a dplyr::mutate() call in the context of a data frame. Default is FALSE.

inf_notation

A boolean that tells whether to infer notation for x. Default is TRUE. See infer_notation() for details.

notation

A notation vector generated by one of the ⁠*_notation()⁠ functions, such as notation_vec(), arrow_notation, or bracket_notation.

choose_most_specific

A boolean that tells whether to choose the most specific notation from the notation argument when the notation argument is a list.

ps

A list of prefixes and suffixes in which each item of the list is itself a list with two items named pref and suff.

pref

A string or list of strings that are prefixes. Default is NULL.

suff

A string of list of strings that are suffixes. Default is NULL.

squish

A boolean that tells whether to remove extra spaces in the output of ⁠paste_*()⁠ functions. Default is TRUE.

which

Tells which to keep, the prefix ("pref") or the suffix ("suff").

from

The notation to switch away from.

to

The notation to switch to.

flip

A boolean that tells whether to also flip the notation. Default is FALSE.

Value

For notation_vec(), arrow_notation, and bracket_notation, a string vector with named items pref_start, pref_end, suff_start, and suff_end; For split_pref_suff(), a string list with named items pref and suff. For paste_pref_suff(), split_pref_suff(), and switch_notation(), a string list in notation format specified by various notation arguments, including from, and to. For keep_pref_suff, one of the prefix or suffix or a list of prefixes or suffixes.

Examples

notation_vec()
arrow_notation
bracket_notation
split_pref_suff("a -> b", notation = arrow_notation)
# Or infer the notation (by default from notations_list)
split_pref_suff("a -> b")
split_pref_suff(c("a -> b", "c -> d", "e -> f"))
split_pref_suff(c("a -> b", "c -> d", "e -> f"), transpose = TRUE)
flip_pref_suff("a [b]", notation = bracket_notation)
# Infer notation
flip_pref_suff("a [b]")
get_pref_suff("a -> b", which = "suff")
switch_notation("a -> b", from = arrow_notation, to = bracket_notation)
# Infer notation and flip prefix and suffix
switch_notation("a -> b", to = bracket_notation, flip = TRUE)
# Also works for vectors
switch_notation(c("a -> b", "c -> d"),
                from = arrow_notation,
                to = bracket_notation)
# Functions can infer the correct notation and return multiple matches
infer_notation("a [to b]",
               allow_multiple = TRUE,
               choose_most_specific = FALSE)
# Or choose the most specific notation
infer_notation("a [to b]",
               allow_multiple = TRUE,
               choose_most_specific = TRUE)
# When setting the from notation, only that type of notation will be switched
switch_notation(c("a -> b", "c [to d]"),
                from = arrow_notation,
                to = bracket_notation)
# But if notations are inferred, all notations can be switched
switch_notation(c("a -> b", "c [to d]"), to = bracket_notation)
# A double-switch can be accomplished.
# In this first example, `RCLabels::first_dot_notation` is inferred.
switch_notation("a.b.c", to = arrow_notation)
# In this second example,
# it is easier to specify the `from` and `to` notations.
switch_notation("a.b.c", to = arrow_notation) %>%
  switch_notation(from = first_dot_notation, to = arrow_notation)
# "" can be used as an input
paste_pref_suff(pref = "a", suff = "", notation = RCLabels::from_notation)