R/tab.R

In myominnoo/stats2: Tools of statistical analysis and data management

#' @title Frequency distribution
#' @description
#' \code{tab} generates Frequency distribution of a variable.
#' @param x a factor object
#' @param data a data frame object (Optional)
#' @param na.rm A logical value to specify missing values, <NA> in the table
#' @param rnd specify rounding of numbers. See \code{\link{round}}.
#' @details
#' Exploring data before jumping into complex analysis is always a necessity.
#' The first step of an analysis is always to summarize and display data.
#'
#' \code{tab}
#' produce one-way table of frequencies.
#'
#' \strong{References:}
#' \enumerate{
#'   \item Essential Medical Statistics, Betty R. Kirkwood & Jonathan A.C. Sterne,
#'   Second Edition. Chapter 3
#'   \item An Introduction to MEdical Statistics, Martin Bland, Thrid Edition,
#'   Chapter 4
#' }
#'
#' @seealso \code{\link{xtab}}
#' @keywords frequency distribution, one-way table
#' @author Myo Minn Oo (Email: \email{dr.myominnoo@@gmail.com} |
#' Website: \url{https://myominnoo.github.io/})
#' @examples
#' str(infert)
#' tab(infert$education)
#' tab(education, data = infert)
#' tab(spontaneous, data = infert)

#' @export
tab <- function(x, data = NULL, na.rm = FALSE, rnd = 1)
{
  if (!is.null(data)) {
    arguments <- as.list(match.call())
    x <- eval(substitute(x), data)
    x.name <- arguments$x
  } else {
    x.name <- deparse(substitute(x))
  }
  na.rm <- ifelse(na.rm, "no", "ifany")

  t <- table(x, useNA = na.rm)
  t.cnt <- c(t, Total = sum(t))
  t.cum <- c(cumsum(t), sum(t))
  f <- cbind(Freq. = t.cnt,
             Percent. = round(t.cnt / sum(t) * 100, rnd),
             Cum. = round(t.cum / sum(t) * 100, rnd))
  names(attributes(f)$dimnames) <- c(x.name, "")

  cat(paste0("\nFrequency distribution: ", x.name, "\n"))
  return(f)
}