descript: Compute univariate descriptive statistics

In SimDesign: Structure for Organizing Monte Carlo Simulation Designs

Compute univariate descriptive statistics

Description

Function returns univariate data summaries for each variable supplied. For presentation purposes, discrete and continuous variables are treated separately, the former of which reflects count/proportion information while the ladder are supplied to a (customizable) list of univariate summary functions. As such, quantitative/continuous variable information is kept distinct in the output, while discrete variables (e.g., factors and character vectors) are returned by using the discrete argument. When applicable a "VARIABLE" column will be included in the output to indicate which variable is being summarised on the respective row.

Usage

descript(
  df,
  funs = get_descriptFuns(),
  margin = NULL,
  by_group = FALSE,
  discrete = FALSE,
  collapse = FALSE,
  drop.miss = TRUE
)

get_descriptFuns()

Arguments

df	typically a data.frame or tibble-like structure containing the variables of interest, though vector objects can be supplied as well. Note that factor and character vectors will be treated as discrete observations, and by default are omitted from the computation of the quantitative descriptive statistics specified in funs. However, setting discrete = TRUE will provide count-type information for these discrete variables, in which case arguments to funs are ignored
funs	functions to apply when discrete = FALSE. Can be modified by the user to include or exclude further functions, however each supplied function must return a scalar. Use get_discreteFuns() to return the full list of functions, which may then be augmented or subsetted based on the user's requirements. Default descriptive statistic returned are: n number of non-missing observations miss number of missing observations (dropped by default if no missing present) mean mean trim trimmed mean (10%) median median sd standard deviation IQR interquartile range skew skewness (from e1701) kurt kurtosis (from e1071) min minimum max maximum Note that by default the na.rm behavior is set to TRUE in each function call
margin	matched argument passed to prop.table for marginal proportion output (1 = row, 2 = column, etc)
by_group	logical; when group_by() were used to define the conditioning levels, should the output from by() be organized by these group levels or by variable names? Only applicable when more than one variable is being described
discrete	logical; include summary statistics for discrete variables only? If TRUE then only count and proportion information for the discrete variables will be returned, and by_group will automatically be set to TRUE. For greater flexibility in creating cross-tabulated count/proportion information see xtabs
collapse	logical; should the result be returned as a list output structured using by or as a tibble? Default is FALSE
drop.miss	logical; if no missing values in the dataset should the element 'miss' be removed from the fun list?

Details

The purpose of this function is to provide a more pipe-friendly API for selecting and subsetting variables using the dplyr syntax, where conditional statistics are evaluated internally using the by function (when multiple variables are to be summarised). As a special case, if only a single variable is being summarised then the canonical output from dplyr::summarise will be returned.

Conditioning: As the function is intended to support pipe-friendly code specifications, conditioning/group subset specifications are declared using group_by and subsequently passed to descript.

Finally, should more verbs be required for data manipulation the dplyr package should be attached or indexed so that any missing verbs can be used directly.

See Also

summarise, group_by, select, xtabs

Examples

data(mtcars)

if(FALSE){
  # run the following to see behavior with NA values in dataset
  mtcars[sample(1:nrow(mtcars), 3), 'cyl'] <- NA
  mtcars[sample(1:nrow(mtcars), 5), 'mpg'] <- NA
}

fmtcars <- within(mtcars, {
	cyl <- factor(cyl)
	am <- factor(am, labels=c('automatic', 'manual'))
	vs <- factor(vs)
})

# with and without factor variables
mtcars |> descript()
fmtcars |> descript()               # factors/discrete vars omitted
fmtcars |> descript(discrete=TRUE)  # discrete variables only

# usual pipe chaining
fmtcars |> select(mpg, wt) |> descript()
fmtcars |> subset(mpg > 20) |> select(mpg, wt) |> descript()

# conditioning with group_by(), printing across each variable
fmtcars |> group_by(cyl) |> descript()
fmtcars |> group_by(cyl, am) |> descript()
fmtcars |> group_by(cyl, am) |> select(mpg, wt) |> descript()

# same, but formatting output by group instead of VARIABLE
fmtcars |> group_by(cyl) |> descript(by_group=TRUE)

# discrete variables also work with group_by()
fmtcars |> descript(discrete=TRUE)
fmtcars |> group_by(cyl) |> descript(discrete=TRUE)
fmtcars |> group_by(am) |> descript(discrete=TRUE)
fmtcars |> group_by(cyl, am) |> descript(discrete=TRUE)

# express proportions as row (1) or column (2) marginals (or higher)
fmtcars |> group_by(cyl) |> descript(discrete=TRUE, margin = 1)
fmtcars |> group_by(cyl) |> descript(discrete=TRUE, margin = 2)

# with single variables, typical dplyr::summarise() output returned
fmtcars |> select(mpg) |> descript()
fmtcars |> group_by(cyl) |> select(mpg) |> descript()
fmtcars |> group_by(cyl, am) |> select(mpg) |> descript()

# if you want a tibble from the list of information instead
fmtcars |> group_by(cyl) |> descript(collapse=TRUE)
fmtcars |> group_by(cyl) |> descript(collapse=TRUE) |> arrange(VARIABLE)
fmtcars |> group_by(am, cyl) |> select(mpg, wt) |> descript(collapse=TRUE)
fmtcars |> group_by(am, cyl) |> select(mpg, wt) |>
  descript(collapse=TRUE) |> arrange(VARIABLE)

# post-extraction (if you don't mind doing the extra computations
#   and extracting afterword)
fmtcars |> descript() |> select(VARIABLE, n, mean)
fmtcars |> select(mpg) |> descript() |> select(VARIABLE, n, mean)
fmtcars |> group_by(cyl) |> select(mpg) |> descript() |>
  select(VARIABLE, n, mean)
fmtcars |> group_by(cyl, am) |> descript() |> select(VARIABLE, n, mean)
fmtcars |> group_by(cyl) |> descript(collapse=TRUE) |>
  select(cyl, VARIABLE, n, mean)

# only compute a subset of summary statistics
funs <- get_descriptFuns()
sfuns <- funs[c('n', 'mean', 'sd')] # subset
fmtcars |> descript(funs=sfuns) # only n, miss, mean, and sd

# add a new functions (20% trimmed mean, and 25/75th quantile for IQR)
funs2 <- c(sfuns,
           trim_20 = \(x) mean(x, trim=.2, na.rm=TRUE),
           P_25= \(x) quantile(x, .25, na.rm=TRUE),
           P_75= \(x) quantile(x, .75, na.rm=TRUE))
fmtcars |> descript(funs=funs2)

# function works on vectors as well
IQ <- rnorm(100, mean=100, sd=15) |> round()
descript(IQ)

SimDesign documentation built on Oct. 6, 2026, 9:07 a.m.