% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/arg_symmetric.R
\name{arg_symmetric}
\alias{arg_symmetric}
\alias{arg_cov}
\alias{arg_cor}
\alias{arg_distance}
\title{Check Symmetric Matrix Argument}
\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{
\item{x}{the argument to be checked}

\item{tol}{\code{numeric}; the tolerance value used to assess symmetry and any numerical bounds. Passed to \code{\link[=isSymmetric]{isSymmetric()}}.}

\item{\dots}{other arguments passed to \code{\link[=isSymmetric]{isSymmetric()}} (and eventually to \code{\link[=all.equal]{all.equal()}}).}

\item{.arg}{the name of the argument supplied to \code{x} to appear in error messages. The default is to extract the argument's name using \code{\link[rlang:caller_arg]{rlang::caller_arg()}}. Ignored if \code{.msg} is supplied.}

\item{.msg}{an optional alternative message to display if an error is thrown instead of the default message.}

\item{.call}{the execution environment of a currently running function, e.g. \code{.call = rlang::current_env()}. The corresponding function call is retrieved and mentioned in error messages as the source of the error. Passed to \code{\link[=err]{err()}}. Set to \code{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.}
}
\value{
Returns \code{NULL} invisibly if an error is not thrown.
}
\description{
\code{arg_symmetric()} checks whether an argument is a square, symmetric, numeric matrix. \code{arg_cov()} checks whether an argument is like a covariance matrix (i.e., square and symmetric with non-negative diagonal entries). \code{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). \code{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).
}
\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. \code{arg_cov()} will throw an error if any values on its diagonal are less than \code{-tol}. \code{arg_cor()} will throw an error if any of its values are greater than \code{1 + tol} in absolute value or if the diagonal entries are not between \code{-1 - tol} and \code{1 + tol}. \code{arg_distance()} will thrown an error if any of its values are less than \code{-tol} or if the diagonal entries are not between \code{-tol} and \code{tol}. The tolerance is just slightly greater than 0 to allow for numeric imprecision.

No checks on semi-definiteness or rank are performed.
}
\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
}
\seealso{
\code{\link[=arg_numeric]{arg_numeric()}}, \code{\link[=arg_matrix]{arg_matrix()}}, \code{\link[=arg_between]{arg_between()}}, \code{\link[=isSymmetric]{isSymmetric()}}
}
