R/ess.R

In nrkoehler/qscorer: Procedures for Scoring Health-related Questionnaires

#' @title {Scoring the Epworth Sleepiness Scale (ESS)}
#' @description \emph{
#' The ESS is a 8-item scale that is designed to measure daytime sleepiness.
#' On a 4-point scale (0-3), respondents are asked to rate their
#' usual chances of dozing off or falling asleep while engaged in eight different activities.
#' A total sum score ranging from 0 to 24 may be calculated.
#' }
#' @details
#' \itemize{
#' \item \code{Number of items:} {8}
#' \item \code{Item range:} {0 to 3}
#' \item \code{Reverse items:} {none}
#' \item \code{Score range:} {0 to 24}
#' \item \code{Cut-off-values:} {none}
#' \item \code{Minimal clinically important difference:} {none}
#' \item \code{Treatment of missing values:}
#' {If at least one item is missing, that ESS score must not be calculated.}
#' }
#' @references
#' Johns 1991 (\url{https://www.ncbi.nlm.nih.gov/pubmed/1798888?dopt=Abstract})
#'
#' Link to questionnaire (\url{http://epworthsleepinessscale.com/wp-content/uploads/2016/06/epworth-sleepiness-scale-sample-copy.jpg})
#' @return The function returns 3 variables:
#' \itemize{
#'  \item \code{nvalid.ess:} {Number of valid values (MAX=8)}
#'  \item \code{score.ess:} {ESS Score}
#'  \item \code{cutoff.ess:} {ESS as categorical variable}
#' }
#' @examples
#' \dontrun{
#' library(dplyr)
#' items.ess <- paste0("ESS_", seq(1, 8, 1))
#' scoring_ess(mydata, items = items.ess)
#' }
#' @param data a \code{\link{data.frame}} containing the ESS items
#' orderd from 1 to 8
#' @param items A character vector with the ESS item names ordered from 1 to 8,
#' or a numeric vector indicating the column numbers of the ESS items in \code{data}.
#' @param keep Logical, whether to keep the single items and  whether to return variables containing
#' the number of non-missing items on each scale for each respondent. The default is TRUE.
#' @param nvalid A numeric value indicating the number of non-missing items required for score
#' calculations. The default is 7.
#' @param digits Integer of length one: value to round to. No rounding by default.
#' @export
scoring_ess <- function(data, items = 1:8, keep = TRUE, nvalid = 7, digits = NULL) {
  library(dplyr, warn.conflicts = FALSE)
  if (min(data[, items], na.rm = T) < 0) {
    stop("Minimum possible value for ESS items is 0")
  } else if (max(data[, items], na.rm = T) > 3) {
    stop("Maximum possible value for ESS items is 3")
  }
  # check for number of specified items
  if (length(items) != 8) {
    stop("Number of items must be 8!")
  }
  items <- items
  data <- data %>%
    mutate(
      nvalid.ess = rowSums(!is.na(select(., items))),
      score.ess = rowSums(select(., items), na.rm = FALSE),
      cutoff.ess = case_when(
        score.ess %in% 0:5 ~ "Lower normal",
        score.ess %in% 6:10 ~ "Higher normal",
        score.ess %in% 11:12 ~ "Mild excessive",
        score.ess %in% 13:15 ~ "Moderate excessive",
        score.ess %in% 16:24 ~ "Severe excessive",
        TRUE ~ as.character(NA)
      ),
      cutoff.ess = factor(cutoff.ess, levels = c(
        "Lower normal", "Higher normal",
        "Mild excessive", "Moderate excessive",
        "Severe excessive"
      ))
    )
  # Keep single items and nvalid variables
  if (keep == FALSE) {
    data <- data %>% select(-items, -nvalid.ess)
  } else {
    data <- data
  }
  # Rounding
  if (is.numeric(digits) == TRUE) {
    data <- data %>% mutate_at(vars(score.ess), list(~ round(., digits)))
  } else {
    data <- data
  }
  data
}
NULL