% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/tab-tap.R
\name{tab_tap}
\alias{tab_tap}
\title{Record a Tabulation Snapshot in a Pipeline}
\usage{
tab_tap(
  .data,
  ...,
  .trail,
  .label = NULL,
  .wt = NULL,
  .sort = c("value_asc", "value_desc", "freq_desc", "freq_asc"),
  .cutoff = NULL,
  .na = c("include", "exclude", "only"),
  .display = c("count", "row_pct", "col_pct", "total_pct"),
  .numeric_summary = TRUE,
  .cols_include = NULL,
  .cols_exclude = NULL
)
}
\arguments{
\item{.data}{A data.frame or tibble.}

\item{...}{Additional arguments (currently unused).}

\item{.trail}{An \code{\link[=audit_trail]{audit_trail()}} object.}

\item{.label}{Character label for this snapshot.}

\item{.wt}{Optional unquoted column to use as frequency weights.
When supplied, frequencies are weighted sums instead of row counts.}

\item{.sort}{How to order the rows (and columns in two-way tables).
\code{"value_asc"} (default) sorts alphabetically (or by factor levels),
\code{"value_desc"} sorts in reverse, \code{"freq_desc"} sorts by frequency
descending, \code{"freq_asc"} sorts by frequency ascending.}

\item{.cutoff}{Controls how many values to display.
An integer >= 1 keeps the top-N values by frequency.
A number in (0, 1) keeps values that cumulatively account for that
proportion of the total. Remaining values are grouped under \code{"(Other)"}.
For two-way tables, the cutoff applies to the row variable only.}

\item{.na}{How to handle \code{NA} values. \code{"include"} (default) treats \code{NA} as a
category, \code{"exclude"} drops \code{NA} rows before tabulation, \code{"only"} shows
only \code{NA} rows.}

\item{.display}{Cell contents for two-way crosstabulations. One of
\code{"count"} (default), \code{"row_pct"}, \code{"col_pct"}, or \code{"total_pct"}.
Ignored for one-way tables.}

\item{.numeric_summary}{Logical. If \code{FALSE}, skip numeric summary
computation in the snapshot (default \code{TRUE}).}

\item{.cols_include}{Character vector of column names to include in the
snapshot schema, or \code{NULL} (the default) to include all columns. Mutually
exclusive with \code{.cols_exclude}.}

\item{.cols_exclude}{Character vector of column names to exclude from the
snapshot schema, or \code{NULL} (the default). Mutually exclusive with
\code{.cols_include}.}
}
\value{
\code{.data}, unchanged, returned invisibly.
}
\description{
Transparent pipe pass-through that runs \code{\link[=tab]{tab()}} on the data and stores the
result as a custom diagnostic annotation in the audit trail snapshot.
Returns \code{.data} unchanged.
}
\examples{
trail <- audit_trail("example")
result <- mtcars |>
  tab_tap(cyl, .trail = trail, .label = "by_cyl") |>
  dplyr::filter(mpg > 20) |>
  tab_tap(cyl, .trail = trail, .label = "by_cyl_filtered")
print(trail)

}
\seealso{
Other audit trail:
\code{\link[=audit_diff]{audit_diff()}},
\code{\link[=audit_report]{audit_report()}},
\code{\link[=audit_tap]{audit_tap()}},
\code{\link[=print.audit_snap]{print.audit_snap()}}
}
\concept{audit trail}
