% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/mosaic_analysis.R
\name{mosaic_analysis}
\alias{mosaic_analysis}
\title{Two-variable mosaic analysis (chi-square test + flat mosaic)}
\usage{
mosaic_analysis(
  data,
  var1,
  var2,
  min_count = 10L,
  test = c("chisq", "fisher"),
  percentage_base = c("total", "row", "column"),
  tile_label = c("count", "percent", "residual", "category", "none"),
  title = "",
  ...
)
}
\arguments{
\item{data}{A data.frame containing the two variables.}

\item{var1}{Character. Name of the first variable (mosaic columns).}

\item{var2}{Character. Name of the second variable (stacked within columns).}

\item{min_count}{Integer. Minimum marginal count for a category to be kept.
Categories of either variable below this are dropped before testing.
Default 10.}

\item{test}{Character. \code{"chisq"} (default) Pearson chi-square, or
\code{"fisher"} Fisher's exact test (simulated p-value). Cramer's V and
the residual fill are always derived from the chi-square statistic.}

\item{percentage_base}{Character. Base for the \code{"percent"} tile label
and the \code{pct} column: \code{"total"} (default), \code{"row"}
(within \code{var1}), or \code{"column"} (within \code{var2}).}

\item{tile_label}{Character. What to print inside each tile: \code{"count"}
(default), \code{"percent"}, \code{"residual"}, \code{"category"}
(\code{var2} level), or \code{"none"}.}

\item{title}{Character. Plot title. Default \code{""}.}

\item{...}{Further flat-mosaic styling arguments passed to the renderer
(e.g. \code{col_label_side}, \code{row_label_side}, \code{legend_position},
\code{legend_size}, \code{label_size}, \code{palette}). Tile fill uses the
ColorBrewer RdBu ramp by default (override with \code{palette}). Column
labels auto-rotate to vertical when there are more than 6 columns; pass
\code{col_label_angle} to force an angle.}
}
\value{
An object of class \code{"mosaic_analysis"}: a list with
\describe{
\item{plot}{The flat mosaic \code{ggplot} object.}
\item{counts}{Tidy data.frame, one row per (var1, var2) cell, with
\code{observed}, \code{expected}, \code{residual} (standardized), and
\code{pct} (on \code{percentage_base}).}
\item{stats}{One-row data.frame: \code{test}, \code{statistic},
\code{df}, \code{p_value}, \code{cramers_v}, \code{effect_size},
\code{n}.}
\item{test}{The raw \code{htest} object.}
\item{cramers_v, effect_size}{Effect size value and label.}
\item{table}{The filtered contingency \code{table}.}
\item{removed}{List of dropped \code{var1} / \code{var2} categories.}
\item{n_original, n_filtered}{Row counts before/after filtering.}
}
}
\description{
Analyses the association between two categorical columns of a data.frame.
Builds the contingency table, drops sparse categories below
\code{min_count}, runs a Pearson chi-square test (or Fisher's exact test),
computes Cramer's V with a df-adjusted effect-size label, and draws a flat
ggplot2 mosaic whose tile area encodes counts and whose fill encodes the
standardized Pearson residual (Nestimate diverging palette). All tabular
output is a tidy one-row-per-cell \code{data.frame}.
}
\examples{
df <- data.frame(
  gender = sample(c("F", "M"), 200, replace = TRUE),
  level  = sample(c("Low", "Mid", "High"), 200, replace = TRUE)
)
res <- mosaic_analysis(df, "gender", "level", min_count = 5)
res$stats
res$counts
\donttest{
plot(res, tile_label = "percent")
}
}
\seealso{
\code{\link{mosaic_plot}} for the network/table mosaic (which also
accepts \code{style = "flat"}).
}
