| Title: | Core Utilities for the 'rtemis' Ecosystem |
| Version: | 0.3.1 |
| Date: | 2026-06-30 |
| Description: | Utilities used across packages of the 'rtemis' ecosystem. Includes the msg() messaging system and the fmt() formatting system. Provides a library of 'S7' properties, test_* functions that return logical values, check_* functions that throw informative errors, and clean_* functions that return validated and coerced values. This code began as part of the 'rtemis' package (<doi:10.32614/CRAN.package.rtemis>). |
| License: | GPL (≥ 3) |
| URL: | https://www.rtemis.org, https://github.com/rtemis-org/rtemis.core |
| BugReports: | https://github.com/rtemis-org/rtemis.core/issues |
| Depends: | R (≥ 4.1.0) |
| Encoding: | UTF-8 |
| Imports: | data.table, methods, S7 |
| Suggests: | testthat (≥ 3.0.0) |
| Config/testthat/edition: | 3 |
| Config/testthat/parallel: | true |
| Config/roxygen2/version: | 8.0.0 |
| NeedsCompilation: | no |
| Packaged: | 2026-06-30 08:12:31 UTC; sdg |
| Author: | E.D. Gennatas 
[aut, cre, cph] |
| Maintainer: | E.D. Gennatas <gennatas@gmail.com> |
| Repository: | CRAN |
| Date/Publication: | 2026-06-30 08:40:02 UTC |
rtemis.core: Rtemis Utilities
Description
Core Utilities for rtemis R Packages
Author(s)
Maintainer: E.D. Gennatas gennatas@gmail.com (ORCID) [copyright holder]
Authors:
E.D. Gennatas gennatas@gmail.com (ORCID) [copyright holder]
See Also
Useful links:
Report bugs at https://github.com/rtemis-org/rtemis.core/issues
Abbreviate object class name
Description
Abbreviate object class name
Usage
abbreviate_class(x, n = 4L)
Arguments
x |
Object. |
n |
Integer: Minimum abbreviation length. |
Value
Character: Abbreviated class wrapped in angle brackets.
Author(s)
EDG
Examples
abbreviate_class(iris)
abbreviate_class(iris, n = 3)
Dual-channel error signal
Description
Signals a condition AND optionally writes a styled event line to the operator console. The two channels carry complementary information so nothing is duplicated:
Usage
abort(..., class = NULL, parent = NULL, verbosity = NULL, package = NULL)
Arguments
... |
Message components, concatenated with no separator. |
class |
Character vector: Additional condition classes (prepended
to the base |
parent |
Condition or NULL: Wrapped parent condition. Its message is
echoed to the console (when verbosity allows) and stored on the
signalled condition as |
verbosity |
Integer or NULL: Overrides |
package |
Character or NULL: Package name for verbosity override. |
Details
-
Console echo (when verbosity allows): the most-specific condition class plus the caller bracket - a structured "what failed, where" line. Falls back to
"rtemis_error"whenclass = NULLso the line is always namespace-tagged and recognizable as ours. -
Condition
$message: the corrective human-readable text passed via.... Plain text with all ANSI escapes stripped, so it is safe to serialize into JSON, HTML, or any other ANSI-unaware sink (e.g. browser-side error display), and is whatconditionMessage()/ R's default error printer /tryCatch(error = ...)handlers see.
Use class to add wire-protocol-specific condition classes that callers
can catch via tryCatch(). The base classes "rtemis_error", "error",
and "condition" are always added.
The condition also carries $trace - a pairlist of sys.calls()
captured at the abort site, with abort()'s own frame trimmed. Unlike
base R's traceback() (which only sees .Traceback, populated only
when an error reaches the top-level uncaught), $trace survives
tryCatch() and travels with the condition - so server-side handlers
can ship the stack to a browser-side debug pane, or callers can call
format_trace() to print it.
Value
Does not return - always signals a condition via stop().
Author(s)
EDG
Examples
## Not run:
abort("Could not parse ", "hyperparameters", ".",
class = "rtemislive_invalid_params")
## End(Not run)
Convert ANSI 256 color code to HEX
Description
Convert ANSI 256 color code to HEX
Usage
ansi256_to_hex(code)
Arguments
code |
Integer: ANSI 256 color code (0-255). |
Value
Character: HEX color string.
Author(s)
EDG
Examples
ansi256_to_hex(1)
Make text bold
Description
A fmt() convenience wrapper for making text bold.
Usage
bold(text, reset_code = "\033[22m", output_type = c("ansi", "html", "plain"))
Arguments
text |
Character: Text to make bold. |
reset_code |
Character: ANSI reset code to use after formatting. |
output_type |
Character: Output type ("ansi", "html", "plain"). |
Value
Character: Formatted text with bold styling
Author(s)
EDG
Examples
message(bold("This is bold!"))
Create a bounded double S7 property
Description
Returns a new_property() for a double scalar constrained to a given interval.
Useful for bounds not covered by the pre-built properties.
Usage
bounded_double_property(
lower = -Inf,
upper = Inf,
lower_open = FALSE,
upper_open = FALSE,
nullable = FALSE
)
Arguments
lower |
Numeric scalar. Lower bound. Default |
upper |
Numeric scalar. Upper bound. Default |
lower_open |
Logical scalar. If |
upper_open |
Logical scalar. If |
nullable |
Logical scalar. If |
Value
An S7 property object.
Author(s)
EDG
Examples
# Learning rate in (0, 1]
lr_prop <- bounded_double_property(0, 1, lower_open = TRUE)
Print Size
Description
Get NCOL(x) and NROW{x}
Usage
catsize(x, name = NULL, verbosity = 1L, newline = TRUE)
Arguments
x |
R object (usually that inherits from matrix or data.frame) |
name |
Character: Name of input object |
verbosity |
Integer: Verbosity level. |
newline |
Logical: If TRUE, end with new line character. |
Value
vector of NROW, NCOL invisibly
Author(s)
EDG
Examples
catsize(iris)
Non-empty character scalar S7 property
Description
S7 property accepting a single non-NA, non-empty (after trimming whitespace) string.
Usage
character_scalar
Value
An S7 property object.
Author(s)
EDG
Check character
Description
Check character
Usage
check_character(x, allow_null = TRUE, arg_name = deparse(substitute(x)))
Arguments
x |
Vector to check. |
allow_null |
Logical: If TRUE, NULL values are allowed and return early. |
arg_name |
Character: Name of the variable for error messages. |
Value
Called for side effects. Throws an error if check fails.
Author(s)
EDG
Examples
check_character("papaya")
# Throws error:
try(check_character(42L))
Check character scalar
Description
Check character scalar
Usage
check_character_scalar(x, arg_name = deparse(substitute(x)))
Arguments
x |
Character: Value to check. Must be a single non-NA, non-empty string. |
arg_name |
Character: Argument name to use in error messages. |
Value
Called for side effects. Throws an error if checks fail.
Author(s)
EDG
Examples
check_character_scalar("hello")
# Throw error:
try(check_character_scalar(""))
try(check_character_scalar(NA_character_))
try(check_character_scalar(c("a", "b")))
Check data.table
Description
Check data.table
Usage
check_data.table(x, arg_name = deparse(substitute(x)))
Arguments
x |
Object to check. |
arg_name |
Character: Name of the variable for error messages. |
Value
Called for side effects. Throws an error if input is not a data.table, returns x invisibly otherwise.
Author(s)
EDG
Examples
check_data.table(data.table::as.data.table(iris))
# Throws error:
try(check_data.table(iris))
rtemis.core internal: Dependencies check
Description
Checks if dependencies can be loaded; names missing dependencies if not.
Usage
check_dependencies(..., verbosity = 0L)
Arguments
... |
List or vector of strings defining namespaces to be checked |
verbosity |
Integer: Verbosity level. Note: An error will always printed if dependencies are missing. Setting this to FALSE stops it from printing "Dependencies check passed". |
Value
Called for side effects. Aborts and prints list of missing dependencies, if any.
Author(s)
EDG
Examples
check_dependencies("base")
# Throws error:
try(check_dependencies("zlorbglorb"))
Check double scalar
Description
Check double scalar
Usage
check_double_scalar(x, arg_name = deparse(substitute(x)))
Arguments
x |
Numeric: Value to check. Must be a single non-NA number (integer inputs are accepted). |
arg_name |
Character: Argument name to use in error messages. |
Value
Called for side effects. Throws an error if checks fail.
Author(s)
EDG
Examples
check_double_scalar(3.14)
check_double_scalar(1L)
# Throw error:
try(check_double_scalar(NA_real_))
try(check_double_scalar(c(1.0, 2.0)))
Check if value is in set of allowed values
Description
Checks if a value is in a set of allowed values, and throws an error if not.
Usage
check_enum(x, allowed_values, arg_name = deparse(substitute(x)))
Arguments
x |
Value to check. |
allowed_values |
Vector of allowed values. |
arg_name |
Character: Name of the variable for error messages. |
Value
Called for side effects. Throws an error if x is not in allowed_values, returns x invisibly otherwise.
Author(s)
EDG
Examples
check_enum("apple", c("apple", "banana", "cherry"))
# Throws error:
try(check_enum("granola", c("croissant", "bagel", "scramble")))
Check file exists
Description
Check file exists
Usage
check_file_exists(file)
Arguments
file |
Character: Path to file to check. |
Value
Throws an error if checks fail. Returns the normalized file path invisibly if checks pass.
Author(s)
EDG
Examples
## Not run:
check_file_exists("path/to/file.txt")
## End(Not run)
Check float between 0 and 1, exclusive
Description
Check float between 0 and 1, exclusive
Usage
check_float01exc(x, allow_null = TRUE, arg_name = deparse(substitute(x)))
Arguments
x |
Numeric vector. |
allow_null |
Logical: If TRUE, NULL values are allowed and return early. |
arg_name |
Character: Name of the variable for error messages. |
Value
Called for side effects. Throws an error if checks fail.
Author(s)
EDG
Examples
check_float01exc(c(0.2, 0.7))
# Throws error:
try(check_float01exc(c(0, 0.5, 1)))
Check float between 0 and 1, inclusive
Description
Check float between 0 and 1, inclusive
Usage
check_float01inc(x, allow_null = TRUE, arg_name = deparse(substitute(x)))
Arguments
x |
Numeric vector. |
allow_null |
Logical: If TRUE, NULL values are allowed and return early. |
arg_name |
Character: Name of the variable for error messages. |
Value
Called for side effects. Throws an error if checks fail.
Author(s)
EDG
Examples
check_float01inc(0.5)
Check float greater than or equal to 0
Description
Checks if an input is a numeric vector containing non-negative
(>= 0) values and no NAs. It is designed to validate function arguments.
Usage
check_float0pos(x, allow_null = TRUE, arg_name = deparse(substitute(x)))
Arguments
x |
Numeric vector. |
allow_null |
Logical: If TRUE, NULL values are allowed and return early. |
arg_name |
Character: Name of the variable for error messages. |
Value
Called for side effects. Throws an error if checks fail.
Author(s)
EDG
Examples
check_float0pos(c(0, 0.5, 1))
# Allows integers since they are numeric and can be coerced to double without loss of information
check_float0pos(c(0L, 1L))
# Throws error:
try(check_float0pos(c(-1.5, 0, 1.5)))
Check float -1 <= x <= 1
Description
Check float -1 <= x <= 1
Usage
check_float_neg1_1(x, allow_null = TRUE, arg_name = deparse(substitute(x)))
Arguments
x |
Numeric vector. |
allow_null |
Logical: If TRUE, NULL values are allowed and return early. |
arg_name |
Character: Name of the variable for error messages. |
Value
Called for side effects. Throws an error if checks fail.
Author(s)
EDG
Examples
check_float_neg1_1(c(-1, 0, 1))
# Throws error:
try(check_float_neg1_1(c(-1.5, 0, 1.5)))
Check positive float
Description
Check positive float
Usage
check_floatpos(x, allow_null = TRUE, arg_name = deparse(substitute(x)))
Arguments
x |
Numeric vector. |
allow_null |
Logical: If TRUE, NULL values are allowed and return early. |
arg_name |
Character: Name of the variable for error messages. |
Details
Checking with is.numeric() allows integer inputs as well, which should be ok since it is
unlikely the function that consumes this will enforce double type only, but instead is most
likely to allow implicit coercion from integer to numeric.
Value
Called for side effects. Throws an error if checks fail.
Author(s)
EDG
Examples
check_floatpos(c(0.5, 1.5))
# Allows integers since they are numeric and can be coerced to double without loss of information
check_floatpos(c(1L, 3L))
# Throws error:
try(check_floatpos(c(-1.5, 0.5, 1.5)))
Check float in (0, 1]
Description
Check float in (0, 1]
Usage
check_floatpos1(x, allow_null = TRUE, arg_name = deparse(substitute(x)))
Arguments
x |
Numeric vector. |
allow_null |
Logical: If TRUE, NULL values are allowed and return early. |
arg_name |
Character: Name of the variable for error messages. |
Value
Called for side effects. Throws an error if checks fail.
Author(s)
EDG
Examples
check_floatpos1(c(0.5, 1))
# Throw error:
try(check_floatpos1(c(0, 0.7)))
try(check_floatpos1(c(0.5, 1.5)))
Check class of object
Description
Check class of object
Usage
check_inherits(x, cl, allow_null = TRUE, arg_name = deparse(substitute(x)))
Arguments
x |
Object to check. |
cl |
Character: class to check against. |
allow_null |
Logical: If TRUE, NULL values are allowed and return early. |
arg_name |
Character: Name of the variable for error messages. |
Value
Called for side effects. Throws an error if checks fail.
Author(s)
EDG
Examples
check_inherits("papaya", "character")
# These will throw errors:
try(check_inherits(c(1, 2.5, 3.2), "integer"))
try(check_inherits(iris, "list"))
Check integer scalar
Description
Check integer scalar
Usage
check_integer_scalar(x, arg_name = deparse(substitute(x)))
Arguments
x |
Numeric: Value to check. Must be a single non-NA whole number. |
arg_name |
Character: Argument name to use in error messages. |
Details
Accepts any single numeric value that is a whole number. Integer-typed inputs (1L) and
double-typed whole numbers (1, 100) are both accepted for user convenience.
Value
Called for side effects. Throws an error if checks fail.
Author(s)
EDG
Examples
check_integer_scalar(5L)
check_integer_scalar(100)
# Throw error:
try(check_integer_scalar(1.5))
try(check_integer_scalar(NA_integer_))
Check logical
Description
Check logical
Usage
check_logical(x, allow_null = TRUE, arg_name = deparse(substitute(x)))
Arguments
x |
Vector to check. |
allow_null |
Logical: If TRUE, NULL values are allowed and return early. |
arg_name |
Character: Name of the variable for error messages. |
Value
Called for side effects. Throws an error if checks fail.
Author(s)
EDG
Examples
check_logical(c(TRUE, FALSE))
# Throws error:
try(check_logical(c(0, 1)))
Check logical scalar
Description
Check logical scalar
Usage
check_logical_scalar(x, arg_name = deparse(substitute(x)))
Arguments
x |
Logical: Value to check. Must be a single non-NA |
arg_name |
Character: Argument name to use in error messages. |
Value
Called for side effects. Throws an error if checks fail.
Author(s)
EDG
Examples
check_logical_scalar(TRUE)
check_logical_scalar(FALSE)
# Throw error:
try(check_logical_scalar(NA))
try(check_logical_scalar(1L))
try(check_logical_scalar(c(TRUE, FALSE)))
Check non-negative double scalar
Description
Check non-negative double scalar
Usage
check_nonneg_double_scalar(x, arg_name = deparse(substitute(x)))
Arguments
x |
Numeric: Value to check. Must be a single finite number greater than or equal to zero. |
arg_name |
Character: Argument name to use in error messages. |
Value
Called for side effects. Throws an error if checks fail.
Author(s)
EDG
Examples
check_nonneg_double_scalar(0)
check_nonneg_double_scalar(5)
# Throw error:
try(check_nonneg_double_scalar(-0.001))
try(check_nonneg_double_scalar(Inf))
Check non-negative double vector
Description
Check non-negative double vector
Usage
check_nonneg_double_vector(x, arg_name = deparse(substitute(x)))
Arguments
x |
Numeric: Value to check. Must be a non-empty vector with all elements finite, greater than or equal to zero, and no NAs. |
arg_name |
Character: Argument name to use in error messages. |
Value
Called for side effects. Throws an error if checks fail.
Author(s)
EDG
Examples
check_nonneg_double_vector(c(0, 1, 2.5))
# Throw error:
try(check_nonneg_double_vector(c(-1, 0, 1)))
try(check_nonneg_double_vector(c(1, Inf)))
Check numeric
Description
Checks that x is numeric. Uses is.numeric(), which accepts both
"double" and "integer" inputs - the right semantics for "is this a
number?". Prefer this over check_inherits(x, "numeric"), which
rejects integers because their literal class is "integer", not
"numeric" (a long-standing R/S3 quirk). This trips up wire-format
callers: jsonlite::fromJSON("1") returns an integer, and the value
would then fail inherits(., "numeric") despite being a perfectly
good number.
Usage
check_numeric(x, allow_null = TRUE, arg_name = deparse(substitute(x)))
Arguments
x |
Vector to check. |
allow_null |
Logical: If TRUE, NULL values are allowed and return early. |
arg_name |
Character: Name of the variable for error messages. |
Value
Called for side effects. Throws an error if checks fail.
Author(s)
EDG
Examples
check_numeric(1L)
check_numeric(1.5)
check_numeric(c(1, 2, 3))
# Throws error:
try(check_numeric("1"))
try(check_numeric(TRUE))
Check optional character scalar
Description
Check optional character scalar
Usage
check_optional_character_scalar(x, arg_name = deparse(substitute(x)))
Arguments
x |
Optional Character: Value to check. Must be |
arg_name |
Character: Argument name to use in error messages. |
Value
Called for side effects. Throws an error if checks fail.
Author(s)
EDG
Examples
check_optional_character_scalar(NULL)
check_optional_character_scalar("hello")
# Throw error:
try(check_optional_character_scalar(""))
try(check_optional_character_scalar(c("a", "b")))
Check optional double scalar
Description
Check optional double scalar
Usage
check_optional_double_scalar(x, arg_name = deparse(substitute(x)))
Arguments
x |
Optional Numeric: Value to check. Must be |
arg_name |
Character: Argument name to use in error messages. |
Value
Called for side effects. Throws an error if checks fail.
Author(s)
EDG
Examples
check_optional_double_scalar(NULL)
check_optional_double_scalar(2.5)
# Throw error:
try(check_optional_double_scalar(NA_real_))
Check optional integer scalar
Description
Check optional integer scalar
Usage
check_optional_integer_scalar(x, arg_name = deparse(substitute(x)))
Arguments
x |
Optional Numeric: Value to check. Must be |
arg_name |
Character: Argument name to use in error messages. |
Value
Called for side effects. Throws an error if checks fail.
Author(s)
EDG
Examples
check_optional_integer_scalar(NULL)
check_optional_integer_scalar(10L)
# Throw error:
try(check_optional_integer_scalar(1.5))
Check optional logical scalar
Description
Check optional logical scalar
Usage
check_optional_logical_scalar(x, arg_name = deparse(substitute(x)))
Arguments
x |
Optional Logical: Value to check. Must be |
arg_name |
Character: Argument name to use in error messages. |
Value
Called for side effects. Throws an error if checks fail.
Author(s)
EDG
Examples
check_optional_logical_scalar(NULL)
check_optional_logical_scalar(FALSE)
# Throw error:
try(check_optional_logical_scalar(NA))
Check optional non-negative double scalar
Description
Check optional non-negative double scalar
Usage
check_optional_nonneg_double_scalar(x, arg_name = deparse(substitute(x)))
Arguments
x |
Optional Numeric: Value to check. Must be |
arg_name |
Character: Argument name to use in error messages. |
Value
Called for side effects. Throws an error if checks fail.
Author(s)
EDG
Examples
check_optional_nonneg_double_scalar(NULL)
check_optional_nonneg_double_scalar(0)
# Throw error:
try(check_optional_nonneg_double_scalar(-1))
Check optional non-negative double vector
Description
Check optional non-negative double vector
Usage
check_optional_nonneg_double_vector(x, arg_name = deparse(substitute(x)))
Arguments
x |
Optional Numeric: Value to check. Must be |
arg_name |
Character: Argument name to use in error messages. |
Value
Called for side effects. Throws an error if checks fail.
Author(s)
EDG
Examples
check_optional_nonneg_double_vector(NULL)
check_optional_nonneg_double_vector(c(0, 1, 5))
# Throw error:
try(check_optional_nonneg_double_vector(c(-1, 0)))
Check optional positive double scalar
Description
Check optional positive double scalar
Usage
check_optional_pos_double_scalar(x, arg_name = deparse(substitute(x)))
Arguments
x |
Optional Numeric: Value to check. Must be |
arg_name |
Character: Argument name to use in error messages. |
Value
Called for side effects. Throws an error if checks fail.
Author(s)
EDG
Examples
check_optional_pos_double_scalar(NULL)
check_optional_pos_double_scalar(2.5)
# Throw error:
try(check_optional_pos_double_scalar(0))
Check optional positive double vector
Description
Check optional positive double vector
Usage
check_optional_pos_double_vector(x, arg_name = deparse(substitute(x)))
Arguments
x |
Optional Numeric: Value to check. Must be |
arg_name |
Character: Argument name to use in error messages. |
Value
Called for side effects. Throws an error if checks fail.
Author(s)
EDG
Examples
check_optional_pos_double_vector(NULL)
check_optional_pos_double_vector(c(0.5, 2))
# Throw error:
try(check_optional_pos_double_vector(c(0, 1)))
Check optional positive integer scalar
Description
Check optional positive integer scalar
Usage
check_optional_pos_integer_scalar(x, arg_name = deparse(substitute(x)))
Arguments
x |
Optional Numeric: Value to check. Must be |
arg_name |
Character: Argument name to use in error messages. |
Value
Called for side effects. Throws an error if checks fail.
Author(s)
EDG
Examples
check_optional_pos_integer_scalar(NULL)
check_optional_pos_integer_scalar(5L)
# Throw error:
try(check_optional_pos_integer_scalar(0))
Check optional probability scalar
Description
Check optional probability scalar
Usage
check_optional_prob_scalar(x, arg_name = deparse(substitute(x)))
Arguments
x |
Optional Numeric: Value to check. Must be |
arg_name |
Character: Argument name to use in error messages. |
Value
Called for side effects. Throws an error if checks fail.
Author(s)
EDG
Examples
check_optional_prob_scalar(NULL)
check_optional_prob_scalar(0.5)
# Throw error:
try(check_optional_prob_scalar(2.0))
Check optional probability vector
Description
Check optional probability vector
Usage
check_optional_prob_vector(x, arg_name = deparse(substitute(x)))
Arguments
x |
Optional Numeric: Value to check. Must be |
arg_name |
Character: Argument name to use in error messages. |
Value
Called for side effects. Throws an error if checks fail.
Author(s)
EDG
Examples
check_optional_prob_vector(NULL)
check_optional_prob_vector(c(0.2, 0.8))
# Throw error:
try(check_optional_prob_vector(c(0.5, 2)))
Check Optional Scalar Character
Description
Check Optional Scalar Character
Usage
check_optional_scalar_character(x, arg_name = deparse(substitute(x)))
Arguments
x |
Optional Character: Value to check. |
arg_name |
Character: Argument name to use in error messages. |
Value
Called for side effects.
Author(s)
EDG
Examples
check_optional_scalar_character(NULL, "my_arg")
check_optional_scalar_character("hello", "my_arg")
# Throw error:
try(check_optional_scalar_character(c("hello", "world"), "my_arg"))
try(check_optional_scalar_character(123, "my_arg"))
Check optional open-unit-interval vector
Description
Check optional open-unit-interval vector
Usage
check_optional_unit_open_vector(x, arg_name = deparse(substitute(x)))
Arguments
x |
Optional Numeric: Value to check. Must be |
arg_name |
Character: Argument name to use in error messages. |
Value
Called for side effects. Throws an error if checks fail.
Author(s)
EDG
Examples
check_optional_unit_open_vector(NULL)
check_optional_unit_open_vector(c(0.1, 0.9))
# Throw error:
try(check_optional_unit_open_vector(c(0, 0.5)))
Check positive double scalar
Description
Check positive double scalar
Usage
check_pos_double_scalar(x, arg_name = deparse(substitute(x)))
Arguments
x |
Numeric: Value to check. Must be a single finite number strictly greater than zero. |
arg_name |
Character: Argument name to use in error messages. |
Value
Called for side effects. Throws an error if checks fail.
Author(s)
EDG
Examples
check_pos_double_scalar(0.001)
check_pos_double_scalar(100)
# Throw error:
try(check_pos_double_scalar(0))
try(check_pos_double_scalar(-1))
try(check_pos_double_scalar(Inf))
Check positive double vector
Description
Check positive double vector
Usage
check_pos_double_vector(x, arg_name = deparse(substitute(x)))
Arguments
x |
Numeric: Value to check. Must be a non-empty vector with all elements finite, strictly greater than zero, and no NAs. |
arg_name |
Character: Argument name to use in error messages. |
Value
Called for side effects. Throws an error if checks fail.
Author(s)
EDG
Examples
check_pos_double_vector(c(0.1, 1, 10))
# Throw error:
try(check_pos_double_vector(c(0, 1)))
try(check_pos_double_vector(c(1, Inf)))
Check positive integer scalar
Description
Check positive integer scalar
Usage
check_pos_integer_scalar(x, arg_name = deparse(substitute(x)))
Arguments
x |
Numeric: Value to check. Must be a single non-NA whole number greater than zero. |
arg_name |
Character: Argument name to use in error messages. |
Details
Accepts any single numeric value that is a whole number strictly greater than zero.
Integer-typed inputs (1L) and double-typed whole numbers (1, 100) are both accepted for
user convenience.
Value
Called for side effects. Throws an error if checks fail.
Author(s)
EDG
Examples
check_pos_integer_scalar(1L)
check_pos_integer_scalar(10)
# Throw error:
try(check_pos_integer_scalar(0))
try(check_pos_integer_scalar(-1L))
try(check_pos_integer_scalar(1.5))
Check probability scalar
Description
Check probability scalar
Usage
check_prob_scalar(x, arg_name = deparse(substitute(x)))
Arguments
x |
Numeric: Value to check. Must be a single finite number in |
arg_name |
Character: Argument name to use in error messages. |
Value
Called for side effects. Throws an error if checks fail.
Author(s)
EDG
Examples
check_prob_scalar(0)
check_prob_scalar(0.5)
check_prob_scalar(1)
# Throw error:
try(check_prob_scalar(1.5))
try(check_prob_scalar(-0.1))
Check probability vector
Description
Check probability vector
Usage
check_prob_vector(x, arg_name = deparse(substitute(x)))
Arguments
x |
Numeric: Value to check. Must be a non-empty vector with all elements in |
arg_name |
Character: Argument name to use in error messages. |
Value
Called for side effects. Throws an error if checks fail.
Author(s)
EDG
Examples
check_prob_vector(c(0, 0.5, 1))
# Throw error:
try(check_prob_vector(c(0.5, 1.5)))
try(check_prob_vector(c(0.5, NA)))
Check Scalar Character
Description
Check Scalar Character
Usage
check_scalar_character(x, arg_name = deparse(substitute(x)))
Arguments
x |
Character: Value to check. |
arg_name |
Character: Argument name to use in error messages. |
Value
Called for side effects.
Author(s)
EDG
Examples
check_scalar_character("hello", "my_arg")
# Throw error:
try(check_scalar_character(c("hello", "world"), "my_arg"))
try(check_scalar_character(123, "my_arg"))
Check Scalar Logical
Description
Check Scalar Logical
Usage
check_scalar_logical(x, arg_name = deparse(substitute(x)))
Arguments
x |
Logical: Value to check. |
arg_name |
Character: Argument name to use in error messages. |
Value
Called for side effects.
Author(s)
EDG
Examples
check_scalar_logical(TRUE, "my_arg")
# Throw error:
try(check_scalar_logical(c(TRUE, FALSE), "my_arg"))
try(check_scalar_logical(NA, "my_arg"))
Check object is tabular
Description
Checks if object is of class data.frame, data.table, or tbl_df.
Usage
check_tabular(x)
Arguments
x |
Object to check. |
Value
Called for side effects. Throws an error if input is not tabular, returns x invisibly otherwise.
Author(s)
EDG
Examples
check_tabular(iris)
check_tabular(data.table::as.data.table(iris))
# Throws error:
try(check_tabular(matrix(1:10, ncol = 2)))
Check open-unit-interval scalar
Description
Check open-unit-interval scalar
Usage
check_unit_open_scalar(x, arg_name = deparse(substitute(x)))
Arguments
x |
Numeric: Value to check. Must be a single finite number strictly in |
arg_name |
Character: Argument name to use in error messages. |
Value
Called for side effects. Throws an error if checks fail.
Author(s)
EDG
Examples
check_unit_open_scalar(0.5)
# Throw error:
try(check_unit_open_scalar(0))
try(check_unit_open_scalar(1))
Check open-unit-interval vector
Description
Check open-unit-interval vector
Usage
check_unit_open_vector(x, arg_name = deparse(substitute(x)))
Arguments
x |
Numeric: Value to check. Must be a non-empty vector with all elements strictly in
|
arg_name |
Character: Argument name to use in error messages. |
Value
Called for side effects. Throws an error if checks fail.
Author(s)
EDG
Examples
check_unit_open_vector(c(0.2, 0.5, 0.9))
# Throw error:
try(check_unit_open_vector(c(0, 0.5)))
try(check_unit_open_vector(c(0.5, 1)))
Clean column names
Description
Clean column names by replacing all spaces and punctuation with a single underscore
Usage
clean_colnames(x)
Arguments
x |
Character vector or matrix with colnames or any object with |
Value
Character vector.
Author(s)
EDG
Examples
clean_colnames(iris)
Clean integer input
Description
Clean integer input
Usage
clean_int(x, arg_name = deparse(substitute(x)))
Arguments
x |
Double or integer vector to check. |
arg_name |
Character: Name of the variable for error messages. |
Details
The goal is to return an integer vector. If the input is integer, it is returned as is. If the input is numeric, it is coerced to integer only if the numeric values are integers, otherwise an error is thrown.
Value
Integer vector
Author(s)
EDG
Examples
clean_int(6L)
clean_int(3)
# clean_int(12.1) # Error
clean_int(c(3, 5, 7))
# clean_int(c(3, 5, 7.01)) # Error
Clean names
Description
Clean character vector by replacing all symbols and sequences of symbols with single underscores, ensuring no name begins or ends with a symbol
Usage
clean_names(x, prefix_digits = "V_")
Arguments
x |
Character vector. |
prefix_digits |
Character: prefix to add to names beginning with a digit. Set to NA to skip. |
Value
Character vector.
Author(s)
EDG
Examples
x <- c("Patient ID", "_Date-of-Birth", "SBP (mmHg)")
x
clean_names(x)
Check positive integer
Description
Check positive integer
Usage
clean_posint(x, allow_na = FALSE, arg_name = deparse(substitute(x)))
Arguments
x |
Integer vector. |
allow_na |
Logical: If TRUE, NAs are excluded before checking. If FALSE (default), NAs trigger an error. |
arg_name |
Character: Name of the variable for error messages. |
Value
Integer vector of positive values.
Author(s)
EDG
Examples
clean_posint(5)
Apply 256-color formatting
Description
Apply 256-color formatting
Usage
col256(text, col = "79", bg = FALSE, output_type = c("ansi", "html", "plain"))
Arguments
text |
Character: Text to color |
col |
Character or numeric: Color (ANSI 256-color code, hex for HTML) |
bg |
Logical: If TRUE, apply as background color |
output_type |
Character: Output type ("ansi", "html", "plain") |
Value
Character: Formatted text with 256-color styling
Author(s)
EDG
Examples
col256("Hello", col = 160, output_type = "ansi")
Collapse head of vector with commas followed by ellipsis
Description
Collapse head of vector with commas followed by ellipsis
Usage
collapse_head(x, maxlength = 6L, format_fn = identity)
Arguments
x |
Vector: Input whose first elements are shown. |
maxlength |
Integer: Maximum number of elements to show before truncating with an ellipsis. Use -1 to show all. |
format_fn |
Function: Formatting function applied to each element. |
Details
Used, for example, by repr_ls
Value
Character.
Author(s)
EDG
Examples
collapse_head(98054:99890, maxlength = 5L)
collapse_head(
c("mango", "banana", "tangerine", "sugar", "ackee", "cocoa bean"),
maxlength = 3L, format_fn = toupper
)
Get current date and time
Description
Used by msgdatetime() and log_to_file().
Usage
datetime(datetime_format = "%Y-%m-%d %H:%M:%S")
Arguments
datetime_format |
Character: Format for the date and time. |
Value
Character: Formatted date and time.
Author(s)
EDG
Examples
datetime()
Debug log message
Description
Muted log message gated at verbosity >= 2L. Use for development /
troubleshooting output that should not appear in normal operation.
Usage
dbg(..., verbosity = NULL, package = NULL)
Arguments
... |
Message components, concatenated with no separator. |
verbosity |
Integer or NULL: Overrides |
package |
Character or NULL: Package name for verbosity override. |
Details
Named dbg() rather than debug() to avoid shadowing
base::debug() - the R debugger entry point.
Value
Invisible NULL.
Author(s)
EDG
Examples
dbg("payload bytes: ", 1234L)
Format Numbers for Printing
Description
2 Decimal places, otherwise scientific notation
Usage
ddSci(x, decimal_places = 2, hi = 1e+06, as_numeric = FALSE)
Arguments
x |
Vector of numbers |
decimal_places |
Integer: Return this many decimal places. |
hi |
Float: Threshold at or above which scientific notation is used. |
as_numeric |
Logical: If TRUE, convert to numeric before returning.
This will not force all numbers to print 2 decimal places. For example:
1.2035 becomes "1.20" if |
Details
Numbers will be formatted to 2 decimal places, unless this results in 0.00 (e.g. if input was .0032),
in which case they will be converted to scientific notation with 2 significant figures.
ddSci will return 0.00 if the input is exactly zero.
This function can be used to format numbers in plots, on the console, in logs, etc.
Value
Formatted number
Author(s)
EDG
Examples
x <- .34876549
ddSci(x)
# "0.35"
x <- .00000000457823
ddSci(x)
# "4.6e-09"
Double scalar S7 property
Description
S7 property accepting a single non-NA double value.
Usage
double_scalar
Value
An S7 property object.
Author(s)
EDG
Create an enum S7 property
Description
Returns a new_property() for a character scalar constrained to a fixed set of allowed values.
Usage
enum(values, default = NULL, nullable = FALSE)
Arguments
values |
Character: Allowed values. |
default |
Optional Character: Default value. |
nullable |
Logical scalar. If |
Value
An S7 property object.
Author(s)
EDG
Examples
type_prop <- enum(c("string", "number", "boolean"), default = "string")
Text formatting
Description
Formats text with specified color, styles, and background using ANSI escape codes or HTML, with support for plain text output.
Usage
fmt(
x,
col = NULL,
bold = FALSE,
italic = FALSE,
underline = FALSE,
thin = FALSE,
muted = FALSE,
bg = NULL,
pad = 0L,
reset_code = "\033[0m",
output_type = c("ansi", "html", "plain")
)
Arguments
x |
Character: Text to format. |
col |
Character: Color (hex code, named color, or NULL for no color). |
bold |
Logical: If TRUE, make text bold. |
italic |
Logical: If TRUE, make text italic. |
underline |
Logical: If TRUE, underline text. |
thin |
Logical: If TRUE, make text thin/light. |
muted |
Logical: If TRUE, make text muted/dimmed. |
bg |
Character: Background color (hex code, named color, or NULL). |
pad |
Integer: Number of spaces to pad before text. |
reset_code |
Character: ANSI reset code to use after formatting. |
output_type |
Character: Output type ("ansi", "html", "plain"). |
Details
This function combines multiple formatting options into a single call, making it more efficient than nested function calls. It generates optimized ANSI escape sequences and clean HTML output.
Value
Character: Formatted text with specified styling.
Author(s)
EDG
Examples
# Simple color
fmt("Hello", col = "red")
# Bold red text
fmt("Error", col = "red", bold = TRUE)
# Multiple styles
fmt("Warning", col = "yellow", bold = TRUE, italic = TRUE)
# With background
fmt("Highlight", col = "white", bg = "blue", bold = TRUE)
Gradient text
Description
Gradient text
Usage
fmt_gradient(x, colors, bold = FALSE, output_type = c("ansi", "html", "plain"))
Arguments
x |
Character: Text to colorize. |
colors |
Character vector: Colors to use for the gradient. |
bold |
Logical: If TRUE, make text bold. |
output_type |
Character: Output type ("ansi", "html", "plain"). |
Value
Character: Text with gradient color applied.
Author(s)
EDG
Examples
fmt_gradient("Gradient Text", colors = c("blue", "red")) |> message()
Function to label
Description
Create axis label from function definition and variable name
Usage
fn2label(fn, varname)
Arguments
fn |
Function. |
varname |
Character: Variable name. |
Value
Character: Label.
Author(s)
EDG
Examples
fn2label(\(x) -log10(x), "p-value")
Pretty-print a captured call trace
Description
Formats the $trace carried by an rtemis_error condition (see
abort()) as a numbered, one-line-per-frame string. Most-recent frame
at the bottom, matching base R's traceback() convention. Each frame is
deparsed with a single-line cap so long calls stay readable; no styling
is applied, so the output is safe for any sink (terminal, JSON, HTML).
Usage
format_trace(trace, max_width = 80L)
Arguments
trace |
|
max_width |
Integer: Max characters per deparsed line. Longer calls are truncated with a trailing ellipsis. |
Value
Character scalar with one frame per \n-separated line,
newest frame last. "" if the trace is empty or NULL.
Author(s)
EDG
Examples
## Not run:
cond <- tryCatch(
check_numeric("oops"),
error = identity
)
cat(format_trace(cond), "\n")
## End(Not run)
Get the current rtemis message sink
Description
Get the current rtemis message sink
Usage
get_msg_sink()
Value
The currently registered sink function, or NULL if none is set.
Author(s)
EDG
See Also
set_msg_sink(), with_msg_sink().
Get output type
Description
Get output type for printing text.
Usage
get_output_type(output_type = c("ansi", "html", "plain"), filename = NULL)
Arguments
output_type |
Character vector of output types. |
filename |
Optional Character: Filename for output. |
Details
Exported as internal function for use by other rtemis packages.
Value
Character with selected output type.
Author(s)
EDG
Examples
get_output_type()
Resolve the current logging verbosity
Description
Reads getOption("<package>.verbosity") first when package is supplied,
falling back to getOption("rtemis.verbosity"), and finally to 1L.
Levels: 0L silent, 1L info/warn/success/abort console echo, 2L
includes debug.
Usage
get_verbosity(package = NULL)
Arguments
package |
Character or NULL: Optional package-specific override. |
Value
Integer scalar verbosity level.
Author(s)
EDG
Examples
get_verbosity()
Gray text
Description
A fmt() convenience wrapper for making text gray.
Usage
gray(x, output_type = c("ansi", "html", "plain"))
Arguments
x |
Character: Text to format |
output_type |
Character: Output type ("ansi", "html", "plain") |
Details
This is an internal function so it does not mask grDevices::gray().
Can be useful in contexts where muted is not supported.
Value
Character: Formatted text with gray styling
Author(s)
EDG
Examples
message(gray("gray text"))
Highlight text
Description
A fmt() convenience wrapper for highlighting text.
Usage
highlight(x, pad = 0L, output_type = c("ansi", "html", "plain"))
Arguments
x |
Character: Text to highlight. |
pad |
Integer: Number of spaces to pad before text. |
output_type |
Character: Output type ("ansi", "html", "plain"). |
Value
Character: Formatted text with highlight.
Author(s)
EDG
Examples
message(highlight("This is highlighted!"))
Highlight big numbers
Description
Highlight big numbers
Usage
highlightbig(x, output_type = c("ansi", "html", "plain"))
Arguments
x |
Numeric: Input |
output_type |
Character: Output type ("ansi", "html", "plain"). |
Value
Character: Formatted number with thousands separators and highlighting.
Examples
message(highlightbig(1234567))
Informational log message
Description
Styled informational message, routed through msg() so it carries the
shared datetime + caller prefix. Fires when verbosity is at least 1L.
Usage
info(..., verbosity = NULL, package = NULL)
Arguments
... |
Message components, concatenated with no separator. |
verbosity |
Integer or NULL: Overrides |
package |
Character or NULL: Package name for verbosity override
lookup (e.g. |
Value
Invisible NULL.
Author(s)
EDG
Examples
info("Server started on port ", 8080L)
Integer scalar S7 property
Description
S7 property accepting a single non-NA integer value (must be integer type, e.g. 1L).
Usage
integer_scalar
Value
An S7 property object.
Author(s)
EDG
Make text italic
Description
A fmt() convenience wrapper for making text italic.
Usage
italic(
text,
reset_code = "\033[23m",
output_type = c("ansi", "html", "plain")
)
Arguments
text |
Character: Text to make italic. |
reset_code |
Character: ANSI reset code to use after formatting. |
output_type |
Character: Output type ("ansi", "html", "plain"). |
Value
Character: Formatted text with italic styling
Author(s)
EDG
Examples
message(italic("italic text"))
Format text for label printing
Description
Format text for label printing
Usage
labelify(
x,
underscores_to_spaces = TRUE,
dotsToSpaces = TRUE,
toLower = FALSE,
toTitleCase = TRUE,
capitalize_strings = c("id"),
stringsToSpaces = c("\\$", "`")
)
Arguments
x |
Character: Input |
underscores_to_spaces |
Logical: If TRUE, convert underscores to spaces. |
dotsToSpaces |
Logical: If TRUE, convert dots to spaces. |
toLower |
Logical: If TRUE, convert to lowercase (precedes |
toTitleCase |
Logical: If TRUE, convert to Title Case. Default = TRUE (This does not change
all-caps words, set |
capitalize_strings |
Character, vector: Always capitalize these strings, if present. Default = |
stringsToSpaces |
Character, vector: Replace these strings with spaces. Escape as needed for |
Value
Character vector.
Author(s)
EDG
Examples
x <- c("county_name", "total.cost$", "age", "weight.kg")
labelify(x)
Logical scalar S7 property
Description
S7 property accepting a single non-NA logical value.
Usage
logical_scalar
Value
An S7 property object.
Author(s)
EDG
Match Arguments Ignoring Case
Description
Match Arguments Ignoring Case
Usage
match_arg(x, choices)
Arguments
x |
Character: Argument to match. |
choices |
Character vector: Choices to match against. |
Value
Character: Matched argument.
Author(s)
EDG
Examples
match_arg("papaya", c("AppleExtreme", "SuperBanana", "PapayaMaster"))
Message with provenance
Description
Print message to output with a prefix including data and time, and calling function or full call stack
Usage
msg(
...,
caller = NULL,
call_depth = 1L,
caller_id = 1L,
newline_pre = FALSE,
newline = TRUE,
format_fn = plain,
sep = " ",
verbosity = 1L
)
msg0(
...,
caller = NULL,
call_depth = 1,
caller_id = 1,
newline_pre = FALSE,
newline = TRUE,
format_fn = plain,
sep = "",
verbosity = 1L
)
Arguments
... |
Message to print |
caller |
Character: Name of calling function |
call_depth |
Integer: Print the system call path of this depth. |
caller_id |
Integer: Which function in the call stack to print |
newline_pre |
Logical: If TRUE begin with a new line. |
newline |
Logical: If TRUE end with a new line. |
format_fn |
Function: Formatting function to use on the message text. |
sep |
Character: Use to separate objects in |
verbosity |
Integer: Verbosity level of the message. If 0L, does not print anything and returns NULL, invisibly. |
Details
If msg is called directly from the console, it will print [interactive>] in place of
the call stack.
msg0, similar to paste0, is msg(..., sep = "")
Value
If verbosity > 0L, returns a list with call, message, and date, invisibly, otherwise returns NULL invisibly.
Author(s)
EDG
Examples
msg("Hello")
msgdone
Description
msgdone
Usage
msgdone(caller = NULL, call_depth = 1, caller_id = 1, sep = " ")
Arguments
caller |
Character: Name of calling function |
call_depth |
Integer: Print the system call path of this depth. |
caller_id |
Integer: Which function in the call stack to print |
sep |
Character: Use to separate objects in |
Value
NULL invisibly
Author(s)
EDG
Examples
msgstart("Starting process...")
msgdone("Process complete")
msgstart
Description
msgstart
Usage
msgstart(..., newline_pre = FALSE, sep = "")
Arguments
... |
Message to print |
newline_pre |
Logical: If TRUE begin with a new line. |
sep |
Character: Use to separate objects in |
Value
NULL invisibly
Author(s)
EDG
Examples
msgstart("Starting process...")
msgdone("Process complete.")
Failure message
Description
Failure message
Usage
nay(..., sep = " ", end = "\n", pad = 0)
Arguments
... |
Character: Message components. |
sep |
Character: Separator between message components. |
end |
Character: End character. |
pad |
Integer: Number of spaces to pad the message with. |
Value
NULL invisibly; prints a failure message to the console.
Author(s)
EDG
Examples
nay("Operation failed")
Non-negative double scalar S7 property
Description
S7 property accepting a single finite double greater than or equal to zero, i.e. in [0, \infty).
Usage
nonneg_double_scalar
Value
An S7 property object.
Author(s)
EDG
Non-negative double vector S7 property
Description
S7 property accepting a non-empty double vector with all elements finite, greater than or equal to zero, and no NAs.
Usage
nonneg_double_vector
Value
An S7 property object.
Author(s)
EDG
Non-negative integer scalar S7 property
Description
S7 property accepting a single non-NA integer value greater than or equal to zero,
i.e. in [0, \infty) (e.g. 0L, 1L).
Usage
nonneg_integer_scalar
Value
An S7 property object.
Author(s)
EDG
Cat object
Description
Cat object
Usage
objcat(
x,
col = col_object,
pad = 0L,
prefix = NULL,
output_type = c("ansi", "html", "plain")
)
Arguments
x |
Character: Object description |
col |
Character: Color code for the object name |
pad |
Integer: Number of spaces to pad the message with. |
prefix |
Optional Character: Prefix to add before the object name. |
output_type |
Character: Output type ("ansi", "html", "plain"). |
Value
NULL: Prints the formatted object description to the console.
Author(s)
EDG
Examples
objcat("Supervised")
Create an optional S7 type
Description
Creates an S7 union type that allows for the specified type or NULL.
Usage
optional(type)
Arguments
type |
S7 base class or S7 class. |
Details
This should be used when the S7 class already includes all the necessary validation for the
non-NULL case. Otherwise, create a new S7 property with appropriate validator using
S7::new_property().
Value
An S7 union type that allows for the specified type or NULL.
Author(s)
EDG
Examples
# Create an optional character type
optional(S7::class_character)
Optional non-empty character scalar S7 property
Description
S7 property accepting NULL or a single non-NA, non-empty (after trimming whitespace) string.
Usage
optional_character_scalar
Value
An S7 property object.
Author(s)
EDG
Optional double scalar S7 property
Description
S7 property accepting NULL or a single non-NA double value.
Usage
optional_double_scalar
Value
An S7 property object.
Author(s)
EDG
Optional integer scalar S7 property
Description
S7 property accepting NULL or a single non-NA integer value (must be integer type, e.g. 1L).
Usage
optional_integer_scalar
Value
An S7 property object.
Author(s)
EDG
Optional logical scalar S7 property
Description
S7 property accepting NULL or a single non-NA logical value.
Usage
optional_logical_scalar
Value
An S7 property object.
Author(s)
EDG
Optional non-negative double scalar S7 property
Description
S7 property accepting NULL or a single finite double greater than or equal to zero.
Usage
optional_nonneg_double_scalar
Value
An S7 property object.
Author(s)
EDG
Optional non-negative double vector S7 property
Description
S7 property accepting NULL or a non-empty double vector with all elements finite,
greater than or equal to zero, and no NAs.
Usage
optional_nonneg_double_vector
Value
An S7 property object.
Author(s)
EDG
Optional non-negative integer scalar S7 property
Description
S7 property accepting NULL or a single non-NA integer value greater than or equal to zero.
Usage
optional_nonneg_integer_scalar
Value
An S7 property object.
Author(s)
EDG
Optional positive double scalar S7 property
Description
S7 property accepting NULL or a single finite double strictly greater than zero.
Usage
optional_pos_double_scalar
Value
An S7 property object.
Author(s)
EDG
Optional positive double vector S7 property
Description
S7 property accepting NULL or a non-empty double vector with all elements finite,
strictly greater than zero, and no NAs.
Usage
optional_pos_double_vector
Value
An S7 property object.
Author(s)
EDG
Optional positive integer scalar S7 property
Description
S7 property accepting NULL or a single non-NA integer value strictly greater than zero.
Usage
optional_pos_integer_scalar
Value
An S7 property object.
Author(s)
EDG
Optional probability scalar S7 property
Description
S7 property accepting NULL or a single finite double in [0, 1].
Usage
optional_prob_scalar
Value
An S7 property object.
Author(s)
EDG
Optional probability vector S7 property
Description
S7 property accepting NULL or a non-empty double vector with all elements in [0, 1]
and no NAs.
Usage
optional_prob_vector
Value
An S7 property object.
Author(s)
EDG
Optional open-unit-interval scalar S7 property
Description
S7 property accepting NULL or a single finite double strictly in (0, 1).
Usage
optional_unit_open_scalar
Value
An S7 property object.
Author(s)
EDG
Optional open-unit-interval vector S7 property
Description
S7 property accepting NULL or a non-empty double vector with all elements strictly in
(0, 1) and no NAs.
Usage
optional_unit_open_vector
Value
An S7 property object.
Author(s)
EDG
Oxford comma
Description
Oxford comma
Usage
oxfordcomma(..., format_fn = identity)
Arguments
... |
Character vector: Items to be combined. |
format_fn |
Function: Any function to be applied to each item. |
Value
Character: Formatted string with oxford comma.
Author(s)
EDG
Examples
oxfordcomma("a", "b", "c")
Left-pad a string to a target width
Description
Left-pad a string to a target width
Usage
pad_string(x, target = 17, char = " ")
Arguments
x |
Character: String to pad. |
target |
Integer: Target total width. |
char |
Character: Padding character. |
Value
Character: x left-padded with char to width target.
Author(s)
EDG
Examples
pad_string("hi", target = 6L)
Force plain text when using message()
Description
Force plain text when using message()
Usage
plain(x)
Arguments
x |
Character: Text to be output to console. |
Value
Character: Text with ANSI escape codes removed.
Author(s)
EDG
Examples
message(plain("hello"))
Positive double scalar S7 property
Description
S7 property accepting a single finite double strictly greater than zero, i.e. in (0, \infty).
Usage
pos_double_scalar
Value
An S7 property object.
Author(s)
EDG
Positive double vector S7 property
Description
S7 property accepting a non-empty double vector with all elements finite, strictly greater than zero, and no NAs.
Usage
pos_double_vector
Value
An S7 property object.
Author(s)
EDG
Positive integer scalar S7 property
Description
S7 property accepting a single non-NA integer value strictly greater than zero (e.g. 1L).
Usage
pos_integer_scalar
Value
An S7 property object.
Author(s)
EDG
Print data frame
Description
Pretty print a data frame
Usage
printdf(
x,
pad = 0,
spacing = 1,
ddSci_dp = NULL,
transpose = FALSE,
justify = "right",
colnames = TRUE,
rownames = TRUE,
column_fmt = highlight,
row_fmt = gray,
newline_pre = FALSE,
newline = FALSE
)
Arguments
x |
data frame |
pad |
Integer: Pad output with this many spaces. |
spacing |
Integer: Number of spaces between columns. |
ddSci_dp |
Integer: Number of decimal places to print using ddSci. Default = NULL for no formatting. |
transpose |
Logical: If TRUE, transpose |
justify |
Character: "right", "left". |
colnames |
Logical: If TRUE, print column names. |
rownames |
Logical: If TRUE, print row names. |
column_fmt |
Formatting fn for printing column names. |
row_fmt |
Formatting fn for printing row names. |
newline_pre |
Logical: If TRUE, print a new line before printing data frame. |
newline |
Logical: If TRUE, print a new line after printing data frame. |
Details
By design, numbers will not be justified, but using ddSci_dp will convert to characters, which will be justified. This is intentional for internal use.
Value
NULL invisibly
Author(s)
EDG
Examples
printdf(iris[1:6, ])
Pretty print list
Description
Pretty print a list (or data frame) recursively
Usage
printls(
x,
prefix = "",
pad = 2L,
item_format = bold,
maxlength = 4L,
center_title = TRUE,
title = NULL,
title_newline = TRUE,
newline_pre = FALSE,
format_fn_rhs = ddSci,
print_class = TRUE,
abbrev_class_n = 3L,
print_df = FALSE,
print_S4 = FALSE,
limit = 12L
)
Arguments
x |
list or object that will be converted to a list. |
prefix |
Character: Optional prefix for names. |
pad |
Integer: Pad output with this many spaces. |
item_format |
Formatting function for list item names. |
maxlength |
Integer: Maximum length of items to show using |
center_title |
Logical: If TRUE, autopad title for centering, if present. |
title |
Character: Optional title to print before list. |
title_newline |
Logical: If TRUE, print title on new line. |
newline_pre |
Logical: If TRUE, print newline before list. |
format_fn_rhs |
Formatting function for right-hand side values. |
print_class |
Logical: If TRUE, print abbreviated class of object. |
abbrev_class_n |
Integer: Number of characters to abbreviate class names to. |
print_df |
Logical: If TRUE, print data frame contents, otherwise print n rows and columns. |
print_S4 |
Logical: If TRUE, print S4 object contents, otherwise print class name. |
limit |
Integer: Maximum number of items to show. Use -1 for unlimited. |
Details
Data frames in R began life as lists
Value
NULL invisibly
Author(s)
EDG
Examples
printls(list(a = 1:10, b = "Hello", c = list(d = 1, e = 2)), title = "A List")
Probability scalar S7 property
Description
S7 property accepting a single finite double in [0, 1].
Usage
prob_scalar
Value
An S7 property object.
Author(s)
EDG
Probability vector S7 property
Description
S7 property accepting a non-empty double vector with all elements in [0, 1] and no NAs.
Usage
prob_vector
Value
An S7 property object.
Author(s)
EDG
Red
Description
Red
Usage
red(..., bold = FALSE)
Arguments
... |
Character: Text to colorize. |
bold |
Logical: If TRUE, make text bold. |
Value
Character: Red-colored text.
Author(s)
EDG
Examples
message(red("error"))
String representation
Description
String representation
Usage
repr(x, ...)
Arguments
x |
Object to represent as a string. |
... |
Additional arguments passed to methods. |
Value
Character string representation of the object.
Author(s)
EDG
Examples
S7::method(repr, S7::class_character) <- function(x, ...) {
paste0("<chr> \"", x, "\"")
}
cat(repr("hello"))
Show S7 class name
Description
Show S7 class name
Usage
repr_S7name(x, col = col_object, pad = 0L, prefix = NULL, output_type = NULL)
Arguments
x |
Character: S7 class name. |
col |
Color: Color code for the object name. |
pad |
Integer: Number of spaces to pad the message with. |
prefix |
Character: Prefix to add to the object name. |
output_type |
Character: Output type ("ansi", "html", "plain"). |
Value
Character: Formatted string that can be printed with cat().
Author(s)
EDG
Examples
repr_S7name("Supervised") |> cat()
Show list as formatted string
Description
Works exactly like printls, but instead of printing to console with cat, it outputs a single string, formatted using mformat, so that cat(repr_ls(x)) looks identical to printls(x) for any list x
Usage
repr_ls(
x,
prefix = "",
pad = 2L,
item_format = bold,
maxlength = 4L,
center_title = TRUE,
title = NULL,
title_newline = TRUE,
newline_pre = FALSE,
format_fn_rhs = ddSci,
print_class = TRUE,
abbrev_class_n = 3L,
print_df = FALSE,
print_S4 = FALSE,
limit = 12L,
output_type = c("ansi", "html", "plain")
)
Arguments
x |
list or object that will be converted to a list. |
prefix |
Character: Optional prefix for names. |
pad |
Integer: Pad output with this many spaces. |
item_format |
Formatting function for items. |
maxlength |
Integer: Maximum length of items to show using |
center_title |
Logical: If TRUE, autopad title for centering, if present. |
title |
Character: Title to print before list. |
title_newline |
Logical: If TRUE, print title on new line. |
newline_pre |
Logical: If TRUE, print newline before list. |
format_fn_rhs |
Formatting function for right-hand side of items. |
print_class |
Logical: If TRUE, print abbreviated class of object. |
abbrev_class_n |
Integer: Number of characters to abbreviate class names to. |
print_df |
Logical: If TRUE, print data frame contents, otherwise print n rows and columns. |
print_S4 |
Logical: If TRUE, print S4 object contents, otherwise print class name. |
limit |
Integer: Maximum number of items to show. |
output_type |
Character: Output type for mformat ("ansi", "html", "plain"). |
Details
Exported as internal function for use by other rtemis packages.
Value
Character: Formatted string that can be printed with cat()
Author(s)
EDG
Examples
x <- list(
a = 1:10,
b = "Hello",
c = list(
d = 1,
e = 2
)
)
cat(repr_ls(x, title = "A List"))
rtemis Colors
Description
A named vector of colors used in the rtemis ecosystem, provided as hex strings.
Usage
rtemis_colors
Value
Named character vector of hex color codes.
Author(s)
EDG
Examples
rtemis_colors[["teal"]]
Set the rtemis message sink
Description
When set, msg(), msg0(), msgstart(), and msgdone() forward their
structured output through sink instead of writing to the R console. Used
by rtemis.server to capture training-time messages and forward them over a
WebSocket connection. Pass NULL to restore default console output.
Usage
set_msg_sink(sink)
Arguments
sink |
Function or |
Details
The sink function is called once per message with a single argument: a list with fields
-
text: character. The formatted message body (no datetime prefix). -
caller: character orNA. Calling function as identified byformat_caller(). -
ts: character. Formatted timestamp ("%Y-%m-%d %H:%M:%S"). -
level: character. One of"info"(msg/msg0),"start"(msgstart), or"done"(msgdone).
Producers may include additional fields in the list, which sinks should
ignore when not understood. In particular, rtemis's training observability
(see its specs/observability.md) emits execution-graph node events through
the sink with these extra fields:
-
node_id: character. Unique id of the execution-graph node. -
parent_id: character orNA. Parent node id (for nesting). -
kind: character. Node kind (e.g."tune","grid_cell","train_alg"). -
status: character."start","done","error", or"aborted". -
current,total: integer orNULL. Progress counters.
These are additive; sinks that only read the base fields keep working.
When a sink is set, the console output path is skipped for affected
calls. Errors thrown by the sink propagate to the caller of msg().
Value
Previous sink (function or NULL), invisibly.
Author(s)
EDG
See Also
get_msg_sink(), with_msg_sink().
Examples
captured <- list()
set_msg_sink(function(m) captured[[length(captured) + 1L]] <<- m)
# msg("hello world") # would append to `captured`
set_msg_sink(NULL) # restore console output
Show data.frame
Description
Create a pretty text representation of a data.frame.
Usage
show_df(
x,
pad = 0L,
spacing = 1L,
ddSci_dp = NULL,
transpose = FALSE,
justify = "right",
incl_colnames = TRUE,
incl_rownames = TRUE,
colnames_formatter = highlight,
rownames_formatter = gray,
output_type = c("ansi", "html", "plain")
)
Arguments
x |
data frame |
pad |
Integer: Pad output with this many spaces. |
spacing |
Integer: Number of spaces between columns. |
ddSci_dp |
Integer: Number of decimal places to print using ddSci. Default = NULL for no formatting |
transpose |
Logical: If TRUE, transpose |
justify |
Character: "right", "left". |
incl_colnames |
Logical: If TRUE, include column names. |
incl_rownames |
Logical: If TRUE, include row names. |
colnames_formatter |
Format function for printing column names. |
rownames_formatter |
Format function for printing row names. |
output_type |
Character: Output type ("ansi", "html", "plain"). |
Value
Character: Formatted string representation of the data.frame.
Author(s)
EDG
Examples
show_df(iris[1:3, ]) |> cat()
Show table
Description
Show table
Usage
show_table(
x,
spacing = 2L,
pad = 2L,
formatter = highlight,
output_type = c("ansi", "html", "plain")
)
Arguments
x |
table. |
spacing |
Integer: Number of spaces between columns. |
pad |
Integer: Pad output with this many spaces. |
formatter |
Function: Formatting function applied to table values. |
output_type |
Character: Output type ("ansi", "html", "plain"). |
Value
Character: formatted string.
Author(s)
EDG
Examples
tbl <- table(
Predicted = c("a", "b", "a", "b", "a"),
Reference = c("a", "a", "b", "b", "a")
)
cat(show_table(tbl))
Strip ANSI escape sequences from a string
Description
Removes the SGR / CSI escapes commonly produced by fmt() (and by any
other tool that writes coloured terminal output). Safe to call on plain
input - returns it unchanged.
Usage
strip_ansi(x)
Arguments
x |
Character: Input. |
Value
Character: x with ANSI escapes removed.
Author(s)
EDG
Examples
strip_ansi(fmt("hi", col = "red"))
Success log message
Description
Styled success message. Fires when verbosity is at least 1L.
Usage
success(..., verbosity = NULL, package = NULL)
Arguments
... |
Message components, concatenated with no separator. |
verbosity |
Integer or NULL: Overrides |
package |
Character or NULL: Package name for verbosity override. |
Value
Invisible NULL.
Author(s)
EDG
Examples
success("Job ", "abc123", " complete")
Check class of object
Description
Check class of object
Usage
test_inherits(x, cl)
Arguments
x |
Object to check |
cl |
Character: class to check against |
Value
Logical
Author(s)
EDG
Examples
test_inherits("papaya", "character") # TRUE
test_inherits(c(1, 2.5, 3.2), "integer")
test_inherits(iris, "list") # FALSE, compare to is_check(iris, is.list)
Make text thin/light
Description
A fmt() convenience wrapper for making text thin/light.
Usage
thin(text, output_type = c("ansi", "html", "plain"))
Arguments
text |
Character: Text to make thin |
output_type |
Character: Output type ("ansi", "html", "plain") |
Value
Character: Formatted text with thin/light styling
Author(s)
EDG
Examples
message(thin("thin text"))
Open-unit-interval scalar S7 property
Description
S7 property accepting a single finite double strictly in (0, 1).
Usage
unit_open_scalar
Value
An S7 property object.
Author(s)
EDG
Open-unit-interval vector S7 property
Description
S7 property accepting a non-empty double vector with all elements strictly in (0, 1)
and no NAs.
Usage
unit_open_vector
Value
An S7 property object.
Author(s)
EDG
Warning log message
Description
Styled non-fatal message. By default emits a soft styled message via
msg(); with use_warning = TRUE, calls warning() so callers can
catch via tryCatch(..., warning = handler).
Usage
warn(..., use_warning = FALSE, verbosity = NULL, package = NULL)
Arguments
... |
Message components, concatenated with no separator. |
use_warning |
Logical: If TRUE, signal an R |
verbosity |
Integer or NULL: Overrides |
package |
Character or NULL: Package name for verbosity override. |
Value
Invisible NULL.
Author(s)
EDG
Examples
warn("Disk usage at ", 92L, "%")
Run code with a temporary message sink
Description
Sets sink for the duration of code, restoring the previous sink on exit
(including on error). Useful in tests and for short-lived capture.
Usage
with_msg_sink(sink, code)
Arguments
sink |
Sink function or |
code |
Code to run. |
Value
The value returned by code.
Author(s)
EDG
See Also
set_msg_sink(), get_msg_sink().
Examples
captured <- list()
with_msg_sink(
function(m) captured[[length(captured) + 1L]] <<- m,
{
# any msg() / msg0() / msgstart() / msgdone() calls in here are captured
}
)
Success message
Description
Success message
Usage
yay(..., sep = " ", end = "\n", pad = 0)
Arguments
... |
Character: Message components. |
sep |
Character: Separator between message components. |
end |
Character: End character. |
pad |
Integer: Number of spaces to pad the message with. |
Value
NULL invisibly; prints a success message to the console.
Author(s)
EDG
Examples
yay("Operation complete")