miss-x-summary.R

#' Summarise the missingness in each variable
#'
#' Provide a summary for each variable of the number, percent missings, and
#'   cumulative sum of missings of the order of the variables. By default,
#'   it orders by the most missings in each variable.
#'
#' @param data a data.frame
#' @param order a logical indicating whether to order the result by `n_miss`.
#'     Defaults to TRUE. If FALSE, order of variables is the order input.
#' @param add_cumsum logical indicating whether or not to add the cumulative
#'   sum of missings to the data. This can be useful when exploring patterns
#'   of nonresponse. These are calculated as the cumulative sum of the missings
#'   in the variables as they are first presented to the function.
#' @param digits how many digits to display in `pct_miss` column. Useful when
#'   you are working with small amounts of missing data.
#' @param ... extra arguments
#'
#' @note `n_miss_cumsum` is calculated as the cumulative sum of missings in the
#'     variables in the order that they are given in the data when entering
#'     the function
#'
#' @return a tibble of the percent of missing data in each variable
#'
#' @seealso  [pct_miss_case()] [prop_miss_case()] [pct_miss_var()] [prop_miss_var()] [pct_complete_case()] [prop_complete_case()] [pct_complete_var()] [prop_complete_var()] [miss_prop_summary()] [miss_case_summary()] [miss_case_table()] [miss_summary()] [miss_var_prop()] [miss_var_run()] [miss_var_span()] [miss_var_summary()] [miss_var_table()] [n_complete()] [n_complete_row()] [n_miss()] [n_miss_row()] [pct_complete()] [pct_miss()] [prop_complete()] [prop_complete_row()] [prop_miss()]
#'
#' @export
#'
#' @examples
#'
#' miss_var_summary(airquality)
#' miss_var_summary(oceanbuoys, order = TRUE)
#'
#' \dontrun{
#' # works with group_by from dplyr
#' library(dplyr)
#' airquality %>%
#'   group_by(Month) %>%
#'   miss_var_summary()
#' }
#' @export
miss_var_summary <- function(
  data,
  order = FALSE,
  add_cumsum = FALSE,
  digits,
  ...
) {
  test_if_null(data)

  test_if_dataframe(data)

  UseMethod("miss_var_summary")
}

#' @export
miss_var_summary.default <- function(
  data,
  order = TRUE,
  add_cumsum = FALSE,
  digits = NULL,
  ...
) {
  col_n_miss <- colSums(is.na(data))
  col_pct_miss <- as.numeric(colMeans(is.na(data)) * 100)

  res <- tibble::tibble(
    variable = names(col_n_miss),
    n_miss = as.integer(col_n_miss),
    pct_miss = tibble::num(
      x = col_pct_miss,
      # control how rounding is presented
      digits = digits
    )
  )

  if (add_cumsum) {
    res <- res %>% dplyr::mutate(n_miss_cumsum = cumsum(n_miss))
  }

  if (order) {
    return(dplyr::arrange(res, -n_miss))
  }

  return(res)
}

#' @export
miss_var_summary.grouped_df <- function(
  data,
  order = TRUE,
  add_cumsum = FALSE,
  digits = NULL,
  ...
) {
  group_by_fun(
    data,
    .fun = miss_var_summary,
    order = order,
    add_cumsum = add_cumsum,
    digits = digits
  )
}

#' Summarise the missingness in each case
#'
#' Provide a summary for each case in the data of the number, percent missings,
#'     and cumulative sum of missings of the order of the variables. By default,
#'     it orders by the most missings in each variable.
#'
#' @param data a data.frame
#' @param order a logical indicating whether or not to order the result by
#'     n_miss. Defaults to TRUE. If FALSE, order of cases is the order input.
#' @param ... extra arguments
#' @param add_cumsum logical indicating whether or not to add the cumulative
#'   sum of missings to the data. This can be useful when exploring patterns
#'   of nonresponse. These are calculated as the cumulative sum of the missings
#'   in the variables as they are first presented to the function.
#'
#' @return a tibble of the percent of missing data in each case.
#'
#' @seealso  [pct_miss_case()] [prop_miss_case()] [pct_miss_var()] [prop_miss_var()] [pct_complete_case()] [prop_complete_case()] [pct_complete_var()] [prop_complete_var()] [miss_prop_summary()] [miss_case_summary()] [miss_case_table()] [miss_summary()] [miss_var_prop()] [miss_var_run()] [miss_var_span()] [miss_var_summary()] [miss_var_table()] [n_complete()] [n_complete_row()] [n_miss()] [n_miss_row()] [pct_complete()] [pct_miss()] [prop_complete()] [prop_complete_row()] [prop_miss()]
#'
#' @export
#'
#' @examples
#'
#' miss_case_summary(airquality)
#'
#' \dontrun{
#' # works with group_by from dplyr
#' library(dplyr)
#' airquality %>%
#'   group_by(Month) %>%
#'   miss_case_summary()
#'}
#'
miss_case_summary <- function(data, order = TRUE, add_cumsum = FALSE, ...) {
  test_if_null(data)

  test_if_dataframe(data)

  UseMethod("miss_case_summary")
}

#' @export
miss_case_summary.default <- function(
  data,
  order = TRUE,
  add_cumsum = FALSE,
  ...
) {
  res <- data

  res[["pct_miss"]] <- rowMeans(is.na(res)) * 100
  res[["n_miss"]] <- as.integer(rowSums(is.na(res)))
  res[["case"]] <- seq_len(nrow(res))

  if (add_cumsum) {
    res[["n_miss_cumsum"]] <- cumsum(res[["n_miss"]])
    res <- dplyr::as_tibble(res)
    res <- dplyr::select(res, case, n_miss, pct_miss, n_miss_cumsum)
  }

  if (!add_cumsum) {
    res <- dplyr::as_tibble(res)

    res <- dplyr::select(res, case, n_miss, pct_miss)
  }

  if (order) {
    return(dplyr::arrange(res, -n_miss))
  }

  if (!order) {
    return(res)
  }
}

#' @export
miss_case_summary.grouped_df <- function(
  data,
  order = TRUE,
  add_cumsum = FALSE,
  ...
) {
  group_by_fun(
    data,
    .fun = miss_case_summary,
    order = order,
    add_cumsum = add_cumsum
  )
}

#' Collate summary measures from naniar into one tibble
#'
#' `miss_summary` performs all of the missing data helper summaries and puts
#'   them into lists within a tibble
#'
#' @param data a dataframe
#' @param order whether or not to order the result by n_miss
#'
#' @return a tibble of missing data summaries
#'
#' @seealso  [pct_miss_case()] [prop_miss_case()] [pct_miss_var()] [prop_miss_var()] [pct_complete_case()] [prop_complete_case()] [pct_complete_var()] [prop_complete_var()] [miss_prop_summary()] [miss_case_summary()] [miss_case_table()] [miss_summary()] [miss_var_prop()] [miss_var_run()] [miss_var_span()] [miss_var_summary()] [miss_var_table()] [n_complete()] [n_complete_row()] [n_miss()] [n_miss_row()] [pct_complete()] [pct_miss()] [prop_complete()] [prop_complete_row()] [prop_miss()]
#'
#' @export
#'
#' @examples
#'
#' s_miss <- miss_summary(airquality)
#' s_miss$miss_df_prop
#' s_miss$miss_case_table
#' s_miss$miss_var_summary
#' # etc, etc, etc.
#'
#' \dontrun{
#' library(dplyr)
#' s_miss_group <- group_by(airquality, Month) %>% miss_summary()
#' s_miss_group$miss_df_prop
#' s_miss_group$miss_case_table
#' # etc, etc, etc.
#' }
#'
miss_summary <- function(data, order = TRUE) {
  test_if_null(data)

  test_if_dataframe(data)

  return(
    tibble::tibble(
      miss_df_prop = prop_miss(data),
      miss_var_prop = prop_miss_var(data),
      miss_case_prop = prop_miss_case(data),
      miss_case_table = list(miss_case_table(data)),
      miss_var_table = list(miss_var_table(data)),
      miss_var_summary = list(miss_var_summary(data, order)),
      miss_case_summary = list(miss_case_summary(data, order))
    )
  )
}