add_sig {quest}

Add Significance Symbols to a (Atomic) Vector, Matrix, or Array

Description

add_sig adds symbols for various p-values cutoffs of statistical significance. The function inputs a numeric vector, matrix, or array of effect sizes (e.g., correlation matrix) and a numeric vector, matrix, or array of p-values that correspond to the effect size (i.e., each row and column match) and then returns a character vector, matrix, or array of effect sizes with appended significance symbols. One of the primary applications of this function is use within corp corp_by, and corp_ml for correlation matrices.

Usage

add_sig(
  x,
  p,
  digits = 3,
  p.10 = "",
  p.05 = "*",
  p.01 = "**",
  p.001 = "***",
  lead.zero = FALSE,
  trail.zero = TRUE,
  plus = FALSE
)

Arguments

x

double numeric vector of effect sizes for which statistical significance is available.

p

double matrix of p-values for the effect sizes in x that are matched by element index for vectors, by row and column index with matrices, by row, column, and layer index for 3D arrays, etc. For example, the p-value in the first row and second column of p is associated with the effect size in the first row and second column of x. If x and p do not have the same dimensions, an error is returned.

digits

integer vector of length 1 specifying the number of decimals to round to.

p.10

character vector of length 1 specifying which symbol to append to the end of any effect size significant at the p < .10 level.

p.05

character vector of length 1 specifying which symbol to append to the end of any effect size significant at the p < .05 level.

p.01

character vector of length 1 specifying which symbol to append to the end of any effect size significant at the p < .01 level.

p.001

character vector of length 1 specifying which symbol to append to the end of any effect size significant at the p < .001 level.

lead.zero

logical vector of length 1 specifying whether to retain a zero in front of the decimal place if the effect size is within 1 or -1.

trail.zero

logical vector of length 1 specifying whether to retain zeros after the decimal place (due to rounding).

plus

logical vector of length 1 specifying whether to include a plus sign in front of positive effect sizes (minus signs are always in front of negative effect sizes).

Details

There are several functions out there that do similar things. Here is one posted to R-bloggers that does it for correlation matrices using the corr function from the Hmisc package: https://www.r-bloggers.com/2020/07/create-a-publication-ready-correlation-matrix-with-significance-levels-in-r/.

Value

character vector, matrix, or array with the same dimensions as x and p containing the effect sizes with their significance symbols appended to the end of each value.

Examples

corr_test <- psych::corr.test(mtcars[1:5])
r <- corr_test[["r"]]
p <- corr_test[["p"]]
add_sig(x = r, p = p)
add_sig(x = r, p = p, digits = 2)
add_sig(x = r, p = p, lead.zero = TRUE, trail.zero = FALSE)
add_sig(x = r, p = p, plus = TRUE)
noquote(add_sig(x = r, p = p)) # no quotes for character elements