% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/ard_tabulate_value.R
\name{ard_tabulate_value}
\alias{ard_tabulate_value}
\alias{ard_tabulate_value.data.frame}
\title{Tabulate Value ARD}
\usage{
ard_tabulate_value(data, ...)

\method{ard_tabulate_value}{data.frame}(
  data,
  variables,
  by = dplyr::group_vars(data),
  strata = NULL,
  value = maximum_variable_value(data[variables]),
  statistic = everything() ~ c("n", "N", "p"),
  denominator = NULL,
  fmt_fun = NULL,
  stat_label = everything() ~ default_stat_labels(),
  fmt_fn = deprecated(),
  ...
)
}
\arguments{
\item{data}{(\code{data.frame})\cr
a data frame}

\item{...}{Arguments passed to methods.}

\item{variables}{(\code{\link[dplyr:dplyr_tidy_select]{tidy-select}})\cr
columns to include in summaries. Default is \code{everything()}.}

\item{by, strata}{(\code{\link[dplyr:dplyr_tidy_select]{tidy-select}})\cr
columns to use for grouping or stratifying the table output.
Arguments are similar, but with an important distinction:

\code{by}: results are tabulated by \strong{all combinations} of the columns specified,
including unobserved combinations and unobserved factor levels.

\code{strata}: results are tabulated by \strong{all \emph{observed} combinations} of the
columns specified.

Arguments may be used in conjunction with one another.}

\item{value}{(named \code{list})\cr
named list of values to tabulate. Default is \code{maximum_variable_value(data)},
which returns the largest/last value after a sort.}

\item{statistic}{(\code{\link[=syntax]{formula-list-selector}})\cr
a named list, a list of formulas,
or a single formula where the list element one or more of  \code{c("n", "N", "p", "n_cum", "p_cum")}
(on the RHS of a formula).}

\item{denominator}{(\code{string}, \code{data.frame}, \code{integer})\cr
Specify this argument to change the denominator,
e.g. the \code{"N"} statistic. Default is \code{'column'}. See below for details.}

\item{fmt_fun}{(\code{\link[=syntax]{formula-list-selector}})\cr
a named list, a list of formulas,
or a single formula where the list element is a named list of functions
(or the RHS of a formula),
e.g. \verb{list(mpg = list(mean = \\(x) round(x, digits = 2) |> as.character()))}.}

\item{stat_label}{(\code{\link[=syntax]{formula-list-selector}})\cr
a named list, a list of formulas, or a single formula where
the list element is either a named list or a list of formulas defining the
statistic labels, e.g. \code{everything() ~ list(n = "n", p = "pct")} or
\code{everything() ~ list(n ~ "n", p ~ "pct")}.}

\item{fmt_fn}{\ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#deprecated}{\figure{lifecycle-deprecated.svg}{options: alt='[Deprecated]'}}}{\strong{[Deprecated]}}}
}
\value{
an ARD data frame of class 'card'
}
\description{
Tabulate an Analysis Results Data (ARD) for dichotomous or a specified value.
}
\section{Denominators}{

By default, the \code{ard_tabulate()} function returns the statistics \code{"n"}, \code{"N"}, and
\code{"p"}, where little \code{"n"} are the counts for the variable levels, and big \code{"N"} is
the number of non-missing observations. The calculation for the
proportion is  \code{p = n/N}.

However, it is sometimes necessary to provide a different \code{"N"} to use
as the denominator in this calculation. For example, in a calculation
of the rates of various observed adverse events, you may need to update the
denominator to the number of enrolled subjects.

In such cases, use the \code{denominator} argument to specify a new definition
of \code{"N"}, and subsequently \code{"p"}.
The argument expects one of the following inputs:
\itemize{
\item a string: one of \code{"column"}, \code{"row"}, or \code{"cell"}.
\itemize{
\item \code{"column"}, the default, returns percentages where the sum is equal to
one within the variable after the data frame has been subset with \code{by}/\code{strata}.
\item \code{"row"} gives 'row' percentages where \code{by}/\code{strata} columns are the 'top'
of a cross table, and the variables are the rows. This is well-defined
for a single \code{by} or \code{strata} variable, and care must be taken when there
are more to ensure the the results are as you expect.
\item \code{"cell"} gives percentages where the denominator is the number of non-missing
rows in the source data frame.
}
\item a data frame. Any columns in the data frame that overlap with the \code{by}/\code{strata}
columns will be used to calculate the new \code{"N"}.
\item an integer. This single integer will be used as the new \code{"N"}
\item a structured data frame. The data frame will include columns from \code{by}/\code{strata}.
The last column must be named \code{"...ard_N..."}. The integers in this column will
be used as the updated \code{"N"} in the calculations.
}

When the \code{p} statistic is returned, the proportion is returned---bounded by \verb{[0, 1]}.
The default function to format the statistic scales the proportion by 100
and the percentage is returned which matches the default statistic label of \code{'\%'}.
To get the formatted values, pass the ARD to \code{apply_fmt_fun()}.
}

\examples{
ard_tabulate_value(mtcars, by = vs, variables = c(cyl, am), value = list(cyl = 4))

mtcars |>
  dplyr::group_by(vs) |>
  ard_tabulate_value(
    variables = c(cyl, am),
    value = list(cyl = 4),
    statistic = ~"p"
  )
}
