arg_symmetric: Check Symmetric Matrix Argument

In arg: Clean and Simple Argument Checking

Check Symmetric Matrix Argument

Description

arg_symmetric() checks whether an argument is a square, symmetric, numeric matrix. arg_cov() checks whether an argument is like a covariance matrix (i.e., square and symmetric with non-negative diagonal entries). arg_cor() checks whether an argument is like a correlation matrix (i.e., square and symmetric with all values between -1 and 1 and ones on the diagonal). arg_distance() checks whether an argument is like a distance matrix (i.e., square and symmetric with non-negative entries and zeros on the diagonal).

Usage

arg_symmetric(
  x,
  tol = 100 * .Machine$double.eps,
  ...,
  .arg = rlang::caller_arg(x),
  .msg = NULL,
  .call
)

arg_cov(
  x,
  tol = 100 * .Machine$double.eps,
  ...,
  .arg = rlang::caller_arg(x),
  .msg = NULL,
  .call
)

arg_cor(
  x,
  tol = 100 * .Machine$double.eps,
  ...,
  .arg = rlang::caller_arg(x),
  .msg = NULL,
  .call
)

arg_distance(
  x,
  tol = 100 * .Machine$double.eps,
  ...,
  .arg = rlang::caller_arg(x),
  .msg = NULL,
  .call
)

Arguments

x	the argument to be checked
tol	numeric; the tolerance value used to assess symmetry and any numerical bounds. Passed to isSymmetric().
...	other arguments passed to isSymmetric() (and eventually to all.equal()).
.arg	the name of the argument supplied to x to appear in error messages. The default is to extract the argument's name using rlang::caller_arg(). Ignored if .msg is supplied.
.msg	an optional alternative message to display if an error is thrown instead of the default message.
.call	the execution environment of a currently running function, e.g. .call = rlang::current_env(). The corresponding function call is retrieved and mentioned in error messages as the source of the error. Passed to err(). Set to NULL to omit call information. The default is to search along the call stack for the first user-facing function in another package, if any.

Details

These functions check that an argument is a square, symmetric, numeric matrix. This can be useful when a function can accept a covariance matrix, correlation matrix, or distance matrix. arg_cov() will throw an error if any values on its diagonal are less than -tol. arg_cor() will throw an error if any of its values are greater than 1 + tol in absolute value or if the diagonal entries are not between -1 - tol and 1 + tol. arg_distance() will thrown an error if any of its values are less than -tol or if the diagonal entries are not between -tol and tol. The tolerance is just slightly greater than 0 to allow for numeric imprecision.

No checks on semi-definiteness or rank are performed.

Value

Returns NULL invisibly if an error is not thrown.

See Also

arg_numeric(), arg_matrix(), arg_between(), isSymmetric()

Examples

set.seed(1234)
mat <- matrix(rnorm(12), ncol = 3L) # Non square
sym_mat <- -crossprod(mat)          # Square, symmetric
cov_mat <- cov(mat)                 # Covariance
cor_mat <- cor(mat)                 # Correlation
dist_mat <- as.matrix(dist(mat))    # Distance

try(arg_symmetric(mat))     # Error: not square
try(arg_symmetric(sym_mat)) # No error

try(arg_cov(sym_mat)) # Error: diagonal must be non-negative
try(arg_cov(cov_mat)) # No error

try(arg_cor(cov_mat)) # Error: values must be in [-1, 1]
try(arg_cor(cor_mat)) # No error

try(arg_distance(cor_mat))  # Error: diagonal must be 0
try(arg_distance(dist_mat)) # No error

arg documentation built on April 9, 2026, 5:09 p.m.