% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/data_summary.R
\name{data_summary}
\alias{data_summary}
\alias{data_summary.data.frame}
\title{Summarize data}
\usage{
data_summary(x, ...)

\method{data_summary}{data.frame}(x, ..., by = NULL, remove_na = FALSE, suffix = NULL)
}
\arguments{
\item{x}{A (grouped) data frame.}

\item{...}{One or more named expressions that define the new variable name
and the function to compute the summary statistic. Example:
\code{mean_sepal_width = mean(Sepal.Width)}. The expression can also be provided
as a character string, e.g. \code{"mean_sepal_width = mean(Sepal.Width)"}. The
summary function \code{n()} can be used to count the number of observations.}

\item{by}{Optional character string, indicating the names of one or more
variables in the data frame. If supplied, the data will be split by these
variables and summary statistics will be computed for each group.}

\item{remove_na}{Logical. If \code{TRUE}, missing values are omitted from the
grouping variable. If \code{FALSE} (default), missing values are included as a
level in the grouping variable.}

\item{suffix}{Optional, suffixes to be added to the new variable names,
especially useful when a function returns several values (e.g. \code{quantile()}).
Can be:
\itemize{
\item a character vector: all expressions in \code{...} must return the same number
of values as elements in \code{suffix}.
\item a list of named character vectors: the names of elements in \code{suffix} must
match the names of the expressions. It is also allowed to specify suffixes
for selected expressions only.
}

The new column names are a combination of the left-hand side (i.e.,
the name) of the expression and the related suffixes. If \code{suffix = NULL} (the
default), and a summary expression returns multiple values, either the names
of the returned values (if any) or automatically numbered suffixes such as
\verb{_1}, \verb{_2}, etc. are used. See 'Examples'.}
}
\value{
A data frame with the requested summary statistics.
}
\description{
This function can be used to compute summary statistics for a
data frame or a matrix.
}
\examples{
data(iris)
data_summary(iris, MW = mean(Sepal.Width), SD = sd(Sepal.Width))
data_summary(
  iris,
  MW = mean(Sepal.Width),
  SD = sd(Sepal.Width),
  by = "Species"
)

# same as
d <- data_group(iris, "Species")
data_summary(d, MW = mean(Sepal.Width), SD = sd(Sepal.Width))

# multiple groups
data(mtcars)
data_summary(mtcars, MW = mean(mpg), SD = sd(mpg), by = c("am", "gear"))

# expressions can also be supplied as character strings
data_summary(mtcars, "MW = mean(mpg)", "SD = sd(mpg)", by = c("am", "gear"))

# count observations within groups
data_summary(mtcars, observations = n(), by = c("am", "gear"))

# first and last observations of "mpg" within groups
data_summary(
  mtcars,
  first = mpg[1],
  last = mpg[length(mpg)],
  by = c("am", "gear")
)

# allow more than one-column-summaries for expressions
d <- data.frame(
  x = rnorm(100, 1, 1),
  y = rnorm(100, 2, 2),
  groups = rep(1:4, each = 25)
)

# since we have multiple columns for one expression, the names of the
# returned summary results are used as suffix by default
data_summary(
  d,
  quant_x = quantile(x, c(0.25, 0.75)),
  mean_x = mean(x),
  quant_y = quantile(y, c(0.25, 0.5, 0.75))
)

# if a summary function, like `fivenum()`, returns no named vector, suffixes
# are automatically numbered
data_summary(
  d,
  quant_x = quantile(x, c(0.25, 0.75)),
  mean_x = mean(x),
  fivenum_y = fivenum(y)
)

# specify column suffix for expressions, matching by names
data_summary(
  d,
  quant_x = quantile(x, c(0.25, 0.75)),
  mean_x = mean(x),
  quant_y = quantile(y, c(0.25, 0.5, 0.75)),
  suffix = list(quant_y = c("_Q1", "_Q2", "_Q3"))
)

# name multiple expression suffixes, grouped by variable
data_summary(
  d,
  quant_x = quantile(x, c(0.25, 0.75)),
  mean_x = mean(x),
  quant_y = quantile(y, c(0.25, 0.5, 0.75)),
  suffix = list(quant_x = c("Q1", "Q3"), quant_y = c("_Q1", "_Q2", "_Q3")),
  by = "groups"
)

}
