R/standard-scores.R

In jmbarbone/qpm: Quantitative Psychological Methods

#' Standardized scores
#'
#' Formula and base for supporting standardized scoring.
#'
#' @details
#' A general function to creating standardized scores is provides in `standard_score()`.
#' Two special cases, `z_score()` and `t_score()` are provided using this template.
#'
#' @param x A numeric vector
#' @param .center A function for centering
#' @param .spread A function for spread
#' @param st_mult A multiplier to adjust the center
#' @param st_add A constant to add to the result
#' @param ... Additional arguments passed down to functions
#' @param method Sample or population (partial matches acceptable)
#' @param standardized Logical, if true uses `sterr` rather than `stdev` as `.spread`
#' @export
#'
#' @examples
#' standard_score(c(1:10, NA), mean, sd, na.rm = TRUE)

standard_score <- function(x, .center, .spread, st_mult = 1, st_add = 0, na.rm = FALSE, ...) {
  v <- if(na.rm) na_drop(x) else x
  st_mult * (x - .center(v, ...)) / .spread(v, ...) + st_add
}

#' @rdname standard_score
#' @export
z_score <- function(x, method = c("sample", "population"), na.rm = FALSE, standardized = FALSE, ...) {
  standard_score(x,
                 mean,
                 if(standardized) sterr else stdev,
                 na.rm = na.rm,
                 method = method,
                 ...)
}

#' @rdname standard_score
#' @export
t_score <- function(x, method = c("sample", "population"), na.rm = FALSE, standardized = FALSE, ...) {
  z_score(x,
          method = method,
          na.rm = na.rm,
          standardized = standardized,
          st_add = 50,
          st_mult = 10)
}