xms: Extra-Marital Sex: Attitudes and Behaviors

#==============================================================================#
#                                  x2Test                                      #
#==============================================================================#
#' x2Test
#'
#' \code{x2Test} Conducts a chi-square test of independency on a contingency table
#' and renders a data frame containing the results and a statement describing
#' the results
#'
#' @param data Data to be analyzed with response variable as first variable.
#' @param y Character string indicating the name of the response variable
#' @param x Character string indicating the name of the explanatory variable
#' @param conf Level of confidence between 0 and 1
#' @param alpha The probability of a type 1 error between 0 and 1
#'
#' @author John James, \email{jjames@@datasciencesalon.org}
#' @family xmar functions
#' @export
#'
x2Test <- function(freqTbl, y, x, conf = 0.95, alpha = 0.05) {

  x2 <- chisq.test(freqTbl)

  # Extract Chisq Data
  criticalVal <- qchisq(alpha, x2$parameter, lower.tail = F)

  # Create Table
  table <- data.frame(Response = y,
                      Explanatory = x,
                      `d.f.` = x2$parameter,
                      N = sum(freqTbl),
                      `Critical Value` = qchisq(alpha, x2$parameter, lower.tail = F),
                      `X-Squared` = x2$statistic,
                      `p-value` = ifelse(x2$p.value < 0.05, "p < 0.05", round(x2$p.value, 3)),
                      Decision = ifelse(x2$p.value >= alpha,"Fail to Reject", "Reject"),
                      row.names = NULL)

  # Format Statements
  stmt <- list()
  stmt$type <- paste0("A chi-square test of independence was performed to ",
                      "challenge the null hypothesis that no association exists ",
                      "between ", tolower(y), ", and the explanatory ",
                      "variable, ", tolower(x), ". ")

  if (x2$p.value < (alpha)) {
    stmt$conclude <- paste0("Therefore, the null hypothesis was rejected in ",
                            "favor of the alternative hypothesis which states ",
                            "with ", conf * 100, "% confidence, that the response ",
                            "variable, ", tolower(y), ", and explanatory ",
                            "variable, ", tolower(x), ", are not independent. ")
  } else {
    stmt$conclude <- paste0("Therefore, the null hypothesis that no association ",
                            "exists between response variable ", tolower(y),
                            " and explanatory variable ", tolower(x),
                            " was not rejected. ")
  }

  stmt$detail <- paste0("the critical value indicated by the shaded region ",
                        "was ", round(criticalVal, 2), ". The sum of ",
                        "the squared differences (indicated by the red dot) ",
                        "between observed counts and the expected counts was ",
                        round(x2$statistic,0), ". With ",
                        x2$parameter, " degrees of freedom and N = ", table$N,
                        ", the probability of encountering a difference ",
                        "this extreme (p-value) was approximately ",
                        round(x2$p.value, 3), ". ")


  test <- list(
    sig = list(
      conf = conf,
      alpha = alpha
    ),
    htest = x2,
    result = table,
    stmt = stmt
  )
  return(test)
}