% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/cross_tab.R
\name{cross_tab}
\alias{cross_tab}
\title{Cross-tabulation}
\usage{
cross_tab(
  data,
  x,
  y = NULL,
  by = NULL,
  weights = NULL,
  rescale = FALSE,
  percent = c("none", "column", "row"),
  include_stats = TRUE,
  assoc_measure = c("auto", "cramer_v", "phi", "gamma", "tau_b", "tau_c", "somers_d",
    "lambda", "none"),
  assoc_ci = FALSE,
  correct = FALSE,
  simulate_p = FALSE,
  simulate_B = 2000,
  digits = NULL,
  styled = TRUE,
  show_n = TRUE
)
}
\arguments{
\item{data}{A data frame. Alternatively, a vector when using the
vector-based interface.}

\item{x}{Row variable (unquoted).}

\item{y}{Column variable (unquoted). Mandatory; for one-way tables, use \code{\link[=freq]{freq()}}.}

\item{by}{Optional grouping variable or expression. Can be a single variable
or a combination of multiple variables (e.g. \code{interaction(vs, am)}).}

\item{weights}{Optional numeric weights.}

\item{rescale}{Logical. If \code{FALSE} (the default), weights are used as-is.
If \code{TRUE}, rescales weights so total weighted N matches raw N.}

\item{percent}{One of \code{"none"} (the default), \code{"row"}, \code{"column"}.
Unique abbreviations are accepted (e.g. \code{"n"}, \code{"r"}, \code{"c"}).}

\item{include_stats}{Logical. If \code{TRUE} (the default), computes Chi-squared
and an association measure (see \code{assoc_measure}).}

\item{assoc_measure}{Character. Which association measure to report.
\code{"auto"} (default) selects Kendall's Tau-b when both variables are
ordered factors and Cramer's V otherwise. Other choices:
\code{"cramer_v"}, \code{"phi"}, \code{"gamma"}, \code{"tau_b"}, \code{"tau_c"},
\code{"somers_d"}, \code{"lambda"}, \code{"none"}.}

\item{assoc_ci}{Logical. If \code{TRUE}, includes the 95 percent confidence
interval of the association measure in the note. Defaults to \code{FALSE}.}

\item{correct}{Logical. If \code{FALSE} (the default), no continuity correction is
applied. If \code{TRUE}, applies Yates correction (only for 2x2 tables).}

\item{simulate_p}{Logical. If \code{FALSE} (the default), uses asymptotic p-values.
If \code{TRUE}, uses Monte Carlo simulation.}

\item{simulate_B}{Integer. Number of replicates for Monte Carlo simulation.
Defaults to \code{2000}.}

\item{digits}{Number of decimals. Defaults to \code{1} for percentages, \code{0} for counts.}

\item{styled}{Logical. If \code{TRUE} (the default), returns a \code{spicy_cross_table} object
(for formatted printing). If \code{FALSE}, returns a plain \code{data.frame}.}

\item{show_n}{Logical. If \code{TRUE} (the default), adds marginal N totals when
\code{percent != "none"}.}
}
\value{
A \code{data.frame}, list of data.frames, or \code{spicy_cross_table} object.
When \code{by} is used, returns a \code{spicy_cross_table_list}.
}
\description{
Computes a two-way cross-tabulation with optional weights, grouping
(including combinations of multiple variables), percentage displays,
and inferential statistics.

\code{cross_tab()} produces weighted or unweighted contingency tables with
row or column percentages, optional grouping via \code{by}, and associated
Chi-squared tests with an association measure and diagnostic information.

Both \code{x} and \code{y} variables are required. For one-way frequency tables,
use \code{\link[=freq]{freq()}} instead.
}
\section{Global Options}{


The function recognizes the following global options that modify its default behavior:
\itemize{
\item \strong{\code{options(spicy.percent = "column")}}
Sets the default percentage mode for all calls to \code{cross_tab()}.
Valid values are \code{"none"}, \code{"row"}, and \code{"column"}.
Equivalent to setting \code{percent = "column"} (or another choice) in each call.
\item \strong{\code{options(spicy.simulate_p = TRUE)}}
Enables Monte Carlo simulation for all Chi-squared tests by default.
Equivalent to setting \code{simulate_p = TRUE} in every call.
\item \strong{\code{options(spicy.rescale = TRUE)}}
Automatically rescales weights so that total weighted N equals the raw N.
Equivalent to setting \code{rescale = TRUE} in each call.
}

These options are convenient for users who wish to enforce consistent behavior
across multiple calls to \code{cross_tab()} and other spicy table functions.
They can be disabled or reset by setting them to \code{NULL}:
\code{options(spicy.percent = NULL, spicy.simulate_p = NULL, spicy.rescale = NULL)}.

Example:

\if{html}{\out{<div class="sourceCode r">}}\preformatted{options(spicy.simulate_p = TRUE, spicy.rescale = TRUE)
cross_tab(sochealth, smoking, education, weights = weight)
}\if{html}{\out{</div>}}
}

\examples{
# Basic crosstab
cross_tab(sochealth, smoking, education)

# Column percentages
cross_tab(sochealth, smoking, education, percent = "column")

# Weighted (rescaled)
cross_tab(sochealth, smoking, education, weights = weight, rescale = TRUE)

# Grouped by sex
cross_tab(sochealth, smoking, education, by = sex)

# Grouped by combination of variables
cross_tab(sochealth, smoking, education, by = interaction(sex, age_group))

# Ordinal variables: auto-selects Kendall's Tau-b
cross_tab(sochealth, education, self_rated_health)

# 2x2 table with Yates correction
cross_tab(sochealth, smoking, physical_activity, correct = TRUE)

}
