% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/plot_state_frequencies.R
\name{mosaic_plot}
\alias{mosaic_plot}
\alias{mosaic_plot.default}
\alias{mosaic_plot.netobject}
\alias{mosaic_plot.htna}
\alias{mosaic_plot.mcml}
\alias{mosaic_plot.netobject_group}
\alias{mosaic_plot.table}
\alias{mosaic_plot.matrix}
\title{Mosaic Plot of a Network's Transition or Co-occurrence Counts}
\usage{
mosaic_plot(x, ...)

\method{mosaic_plot}{default}(x, ...)

\method{mosaic_plot}{netobject}(
  x,
  xlab = NULL,
  ylab = NULL,
  range = NULL,
  top_angle = NULL,
  left_angle = NULL,
  residuals = c("permutation", "asymptotic"),
  n_perm = 500L,
  seed = NULL,
  values = FALSE,
  style = c("classic", "flat"),
  ...
)

\method{mosaic_plot}{htna}(
  x,
  xlab = NULL,
  ylab = NULL,
  range = NULL,
  top_angle = NULL,
  left_angle = NULL,
  residuals = c("permutation", "asymptotic"),
  n_perm = 500L,
  seed = NULL,
  values = FALSE,
  style = c("classic", "flat"),
  ...
)

\method{mosaic_plot}{mcml}(
  x,
  level = c("macro", "clusters"),
  xlab = NULL,
  ylab = NULL,
  range = NULL,
  top_angle = NULL,
  left_angle = NULL,
  residuals = c("permutation", "asymptotic"),
  n_perm = 500L,
  seed = NULL,
  ncol = 2L,
  values = FALSE,
  style = c("classic", "flat"),
  ...
)

\method{mosaic_plot}{netobject_group}(
  x,
  xlab = NULL,
  ylab = NULL,
  range = NULL,
  top_angle = NULL,
  left_angle = NULL,
  residuals = c("permutation", "asymptotic"),
  n_perm = 500L,
  seed = NULL,
  ncol = 2L,
  values = FALSE,
  style = c("classic", "flat"),
  ...
)

\method{mosaic_plot}{table}(
  x,
  xlab = "Row",
  ylab = "Column",
  range = NULL,
  top_angle = NULL,
  left_angle = NULL,
  residuals = c("permutation", "asymptotic"),
  n_perm = 500L,
  seed = NULL,
  values = FALSE,
  style = c("classic", "flat"),
  ...
)

\method{mosaic_plot}{matrix}(x, ...)
}
\arguments{
\item{x}{One of the four data-bearing Nestimate classes:
\code{netobject} (single mosaic of \code{$weights}),
\code{netobject_group} (one panel per group),
\code{mcml} (between-cluster mosaic by default; per-cluster panels with
\code{level = "within"}), or
\code{htna} (single mosaic of \code{$weights}; htna inherits netobject
so the geometry matches). Also accepts a contingency \code{table} or
plain numeric \code{matrix} for ad-hoc plotting.}

\item{...}{Flat styling overrides forwarded to the flat renderer when
\code{style = "flat"} (otherwise ignored).}

\item{xlab, ylab}{Axis labels. \code{NULL} (default) draws no axis title.
Pass any string to add one.}

\item{range}{Numeric of length 2 giving the lower and upper colour-scale
limits for the standardized residual. \code{NULL} (default) auto-fits
the limits to the symmetric range \code{c(-M, M)} where
\code{M = max(|stdres|)}, so no signal is squished. Pass an explicit
range (e.g. \code{c(-4, 4)} for tna-style display, \code{c(-6, 6)} for
moderate clipping) to clamp the colour scale.}

\item{top_angle, left_angle}{Rotation in degrees for the top (x) and left
(y) tick labels. \code{NULL} (default) uses the auto rule
\code{90 if n_levels > 3 else 0} on each axis. Pass any numeric to
override (e.g. \code{top_angle = 45, left_angle = 0}).}

\item{residuals}{One of \code{"permutation"} (default) or
\code{"asymptotic"}. \code{"permutation"} computes empirical-null
z-scores by shuffling one variable's labels against the other for
\code{n_perm} draws and reporting
\code{(O - mean_perm) / sd_perm} per cell. Robust on sparse tables.
\code{"asymptotic"} returns \code{stats::chisq.test()$stdres} (the
closed-form \code{(O - E) / sqrt(E*(1 - p_row)*(1 - p_col))} that vcd
and tna use).}

\item{n_perm}{Number of permutations when \code{residuals = "permutation"}.
Default 500; use \code{>= 1000} for stable tail estimates.}

\item{seed}{Optional integer seed for the permutation RNG. Use for
reproducible plots; ignored when \code{residuals = "asymptotic"}.}

\item{values}{Logical. When \code{TRUE}, overlay each cell's standardized
residual as a numeric label (one decimal). Text colour switches to
white on saturated cells (|stdres| > 1.5) and dark grey otherwise.
Default \code{FALSE} -- the colour bar legend already conveys the
sign and magnitude.}

\item{style}{Character. \code{"classic"} (default) draws the
black-bordered \code{theme_minimal} mosaic with axis labels;
\code{"flat"} draws the flat \code{theme_void} mosaic with white
gutters, a soft background and a colour-bar legend. With
\code{style = "flat"}, \code{values = TRUE} prints the standardized
residual inside each tile, and extra flat styling arguments
(\code{tile_label}, \code{col_label_side}, \code{row_label_side},
\code{legend_position}, \code{legend_size}, \code{label_size}, ...;
see \code{\link{mosaic_analysis}}) may be passed via \code{...}.
Not supported for multi-panel \code{mcml} (level = "clusters"),
which falls back to the classic faceted style.}

\item{level}{For \code{mcml} only. \code{"macro"} (default) draws a
single mosaic of \code{x$macro$weights} (the cluster-by-cluster
aggregate); \code{"clusters"} draws one mosaic per cluster from
\code{x$clusters[[k]]$weights}, faceted into one combined ggplot.}

\item{ncol}{For \code{netobject_group}: number of columns in the small-
multiples layout. Default 2.}
}
\value{
A \code{ggplot} object (or a \code{gtable} from
\code{gridExtra::arrangeGrob} for \code{netobject_group} when
\pkg{gridExtra} is available).
}
\description{
Draws a Hartigan-Friendly mosaic (marimekko geometry, chi-square
standardized-residual fill) for an integer-weighted network. Equivalent in
algorithm and appearance to \code{tna::plot_mosaic()}; named differently to
avoid an export clash when both packages are attached.
}
\details{
Column widths are proportional to row marginals of the weight matrix
(incoming totals when the matrix is transposed, as for transitions). Within
each column, segment heights are proportional to that row's conditional
distribution. Cell fill is the standardized residual from
\code{stats::chisq.test()}, with a diverging palette clipped to \eqn{\pm 4}.
Mosaics need integer counts: when \code{$weights} is already integer
(\code{method = "frequency"} / \code{"co_occurrence"}) it is used directly;
for a single \code{netobject} / \code{htna} otherwise (relative, glasso,
cor, ...) order-1 transition counts are recounted from the raw \code{$data}
sequences. The function errors only when neither integer weights nor
\code{$data} are available.
}
\examples{
\dontrun{
  net <- build_network(group_regulation, method = "frequency")
  mosaic_plot(net)
}
}
\seealso{
\code{\link{plot_mosaic}} for the lower-level data.frame primitive.
}
