R/average_fre_z.R

In josh-mc/fabricated: Tools to Audit Survey Data Quality

#' Simulation based Z-scores for average frequence
#'
#' The 'average_fre_z()' function uses 'average_fre()' to calculate the average
#' frequency for a data set and 'shuffle()' to calculate average frequency for
#' shuffles (simulations) of the same data set. The mean and sd for the
#' simulated data is then used to calculate Z-scores.
#'
#' @param data A data frame
#' @param variable A numeric variable that includes the first decimal place.
#' @param group A second variable used to group the primary variable such that
#'     average frequency Z-scores are calculated separately for each group.
#' @param decimal_place The number of decimal places used for the calculation.
#'     The default is set to "1" meaning decimals in the second (hundreds place)
#'     and below are discarded.
#' @param reps The number of shuffles (simulations) to perform. The default is set to 1,000.
#'
#' @return A tibble
#' @export
#'
#' @examples
#' average_fre_z(bodyweight, obs, group, reps = 100)
#'
#' @importFrom magrittr %>%
#' @importFrom rlang .data

average_fre_z <- function(data, variable,
                          group = NULL,
                          decimal_place = 1,
                          reps = 1000)  {

  actual <- average_fre(data, {{ variable }}, {{ group }}, {{ decimal_place }})

  simulated <- shuffle(data, {{ variable }}, {{ group }}, {{ decimal_place }}, {{ reps }}) %>%
    dplyr::group_by({{ group }}) %>%
    dplyr::summarise(mean = mean(.data$af), sd = stats::sd(.data$af))

  #deparsing and subsituting the "group" variable and saving it with a new name
  #so that I can use it in the "is.null()" function below.

  var <- deparse(substitute(group))

  if(is.null(data[[var]]))  {

    dplyr::bind_cols(simulated, actual) %>%
      dplyr::mutate(z_score = (.data$af - .data$mean) / .data$sd)

  }

  else  {

    #actual <- actual %>%
    #  dplyr::rename(add = {{ group }})

    #simulated <- simulated %>%
    #  dplyr::rename(add = {{ group }})

    dplyr::left_join(simulated, actual, by = NULL) %>%
      dplyr::mutate(z_score = (.data$af - .data$mean) / .data$sd)

  }
}