% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/cluster.R
\name{plot.dpmixgpd_cluster_bundle}
\alias{plot.dpmixgpd_cluster_bundle}
\alias{plot.dpmixgpd_cluster_fit}
\alias{plot.dpmixgpd_cluster_labels}
\alias{plot.dpmixgpd_cluster_psm}
\title{Plot a cluster bundle}
\usage{
\method{plot}{dpmixgpd_cluster_bundle}(x, plotly = getOption("CausalMixGPD.plotly", FALSE), ...)

\method{plot}{dpmixgpd_cluster_fit}(
  x,
  which = c("psm", "k", "sizes", "summary"),
  burnin = NULL,
  thin = NULL,
  psm_max_n = 2000L,
  top_n = 5L,
  order_by = c("size", "label"),
  plotly = getOption("CausalMixGPD.plotly", FALSE),
  ...
)

\method{plot}{dpmixgpd_cluster_labels}(
  x,
  type = c("sizes", "certainty", "summary"),
  top_n = 5L,
  order_by = c("size", "label"),
  plotly = getOption("CausalMixGPD.plotly", FALSE),
  ...
)

\method{plot}{dpmixgpd_cluster_psm}(
  x,
  psm_max_n = x$psm_max_n \%||\% 2000L,
  order_by = c("label", "hclust", "input"),
  plotly = getOption("CausalMixGPD.plotly", FALSE),
  ...
)
}
\arguments{
\item{x}{Cluster PSM object.}

\item{plotly}{Logical; if \code{TRUE}, convert the \code{ggplot2} output to a \code{plotly} /
\code{htmlwidget} representation via \code{.wrap_plotly()}. Defaults to
\code{getOption("CausalMixGPD.plotly", FALSE)}.}

\item{...}{Unused.}

\item{which}{Plot type:
\itemize{
\item \code{"psm"}: posterior similarity matrix heatmap
\item \code{"k"}: posterior number of occupied clusters
\item \code{"sizes"}: bar chart of representative cluster sizes
\item \code{"summary"}: cluster-specific response summaries
}}

\item{burnin}{Number of initial posterior draws to discard.}

\item{thin}{Keep every \code{thin}-th posterior draw.}

\item{psm_max_n}{Maximum allowed matrix size for plotting.}

\item{top_n}{Number of populated representative clusters to display for
\code{type = "sizes"} or \code{type = "summary"}. Use \code{NULL} to
display all populated clusters.}

\item{order_by}{Ordering rule for rows and columns:
\itemize{
\item \code{"label"}: order by representative cluster labels when available
\item \code{"hclust"}: order by hierarchical clustering of \code{1 - PSM}
\item \code{"input"}: preserve input order
}}

\item{type}{Plot type:
\itemize{
\item \code{"sizes"}: bar chart of representative cluster sizes
\item \code{"certainty"}: assignment certainty distribution
\item \code{"summary"}: cluster-specific response boxplots
}}
}
\value{
A \code{ggplot2} object or a \code{plotly}/\code{htmlwidget} object when \code{plotly = TRUE}.

A \code{ggplot2} object or a \code{plotly}/\code{htmlwidget} object when \code{plotly = TRUE}.

A \code{ggplot2} object or a \code{plotly}/\code{htmlwidget} object when \code{plotly = TRUE}.

A \code{ggplot2} object or a \code{plotly}/\code{htmlwidget} object when \code{plotly = TRUE}.
}
\description{
Produce a compact graphical summary of the cluster bundle metadata.

Visualize either the posterior similarity matrix, the posterior number of occupied clusters, the
size distribution of the representative clusters, or cluster-specific response summaries.

Visualize representative cluster sizes, assignment certainty, or cluster-specific response
summaries. For \code{type = "summary"}, the response view is shown as boxplots ordered by
cluster size or label. When \code{x} comes from \code{predict(..., newdata = ...)}, only clusters
represented in the new sample are displayed.

Heatmap of pairwise posterior co-clustering probabilities.
}
\details{
The bundle plot is a metadata display rather than an inferential graphic. It
mirrors the structural fields reported by \code{print()} and \code{summary()} in a
single panel so the pre-MCMC clustering specification can be reviewed in a
figure-oriented workflow or notebook.

Because the object has not been sampled yet, no representative partition or
posterior uncertainty is shown here. Use \code{\link[=plot.dpmixgpd_cluster_fit]{plot.dpmixgpd_cluster_fit()}},
\code{\link[=plot.dpmixgpd_cluster_labels]{plot.dpmixgpd_cluster_labels()}}, or \code{\link[=plot.dpmixgpd_cluster_psm]{plot.dpmixgpd_cluster_psm()}} after
fitting when you need substantive clustering output.

This plot method exposes the main posterior diagnostics for clustering. The
\code{which = "k"} view tracks the number of occupied clusters across retained
draws, \code{which = "psm"} visualizes pairwise co-clustering probabilities,
\code{which = "sizes"} displays the size profile of the representative partition,
and \code{which = "summary"} shows response summaries conditional on the selected
representative labels.

The representative partition is obtained from
\code{\link[=predict.dpmixgpd_cluster_fit]{predict.dpmixgpd_cluster_fit()}} using Dahl's least-squares rule. As a
result, the \code{sizes} and \code{summary} views describe that representative
clustering rather than the full posterior distribution over partitions.

This method visualizes the representative partition stored in a
\code{dpmixgpd_cluster_labels} object. The \code{sizes} view emphasizes the empirical
distribution of the selected clusters, the \code{certainty} view summarizes the
assignment scores \eqn{\max_k p_{ik}}, and the \code{summary} view compares the
attached response data across representative clusters.

For new-data prediction, the plots are always interpreted relative to the
representative training clusters. That is why only clusters observed in the
predicted sample are shown even though the training partition may contain
additional occupied groups.

The heatmap visualizes the matrix
\deqn{
\mathrm{PSM}_{ij} \approx \frac{1}{S} \sum_{s=1}^S I(z_i^{(s)} = z_j^{(s)}),
}
so larger values indicate pairs of observations that are stably allocated to
the same cluster over the retained posterior draws.

Because the PSM is an \eqn{n \times n} object, plotting and even storing it
becomes expensive for large \code{n}. The \code{psm_max_n} argument is therefore a
deliberate guard against accidental quadratic memory use.
}
\seealso{
\code{\link[=summary.dpmixgpd_cluster_bundle]{summary.dpmixgpd_cluster_bundle()}}, \code{\link[=dpmix.cluster]{dpmix.cluster()}}, \code{\link[=dpmgpd.cluster]{dpmgpd.cluster()}}.

\code{\link[=predict.dpmixgpd_cluster_fit]{predict.dpmixgpd_cluster_fit()}}, \code{\link[=summary.dpmixgpd_cluster_fit]{summary.dpmixgpd_cluster_fit()}},
\code{\link[=plot.dpmixgpd_cluster_psm]{plot.dpmixgpd_cluster_psm()}}, \code{\link[=plot.dpmixgpd_cluster_labels]{plot.dpmixgpd_cluster_labels()}}.

\code{\link[=summary.dpmixgpd_cluster_labels]{summary.dpmixgpd_cluster_labels()}}, \code{\link[=predict.dpmixgpd_cluster_fit]{predict.dpmixgpd_cluster_fit()}}.

\code{\link[=predict.dpmixgpd_cluster_fit]{predict.dpmixgpd_cluster_fit()}}, \code{\link[=summary.dpmixgpd_cluster_psm]{summary.dpmixgpd_cluster_psm()}},
\code{\link[=plot.dpmixgpd_cluster_fit]{plot.dpmixgpd_cluster_fit()}}.

Other cluster workflow: 
\code{\link{cluster_profiles}()},
\code{\link{dpmgpd.cluster}()},
\code{\link{dpmix.cluster}()},
\code{\link{predict.dpmixgpd_cluster_fit}()},
\code{\link{print.dpmixgpd_cluster_bundle}()},
\code{\link{print.dpmixgpd_cluster_fit}()},
\code{\link{print.dpmixgpd_cluster_labels}()},
\code{\link{print.dpmixgpd_cluster_psm}()},
\code{\link{summary.dpmixgpd_cluster_bundle}()},
\code{\link{summary.dpmixgpd_cluster_fit}()},
\code{\link{summary.dpmixgpd_cluster_labels}()},
\code{\link{summary.dpmixgpd_cluster_psm}()}

Other cluster workflow: 
\code{\link{cluster_profiles}()},
\code{\link{dpmgpd.cluster}()},
\code{\link{dpmix.cluster}()},
\code{\link{predict.dpmixgpd_cluster_fit}()},
\code{\link{print.dpmixgpd_cluster_bundle}()},
\code{\link{print.dpmixgpd_cluster_fit}()},
\code{\link{print.dpmixgpd_cluster_labels}()},
\code{\link{print.dpmixgpd_cluster_psm}()},
\code{\link{summary.dpmixgpd_cluster_bundle}()},
\code{\link{summary.dpmixgpd_cluster_fit}()},
\code{\link{summary.dpmixgpd_cluster_labels}()},
\code{\link{summary.dpmixgpd_cluster_psm}()}

Other cluster workflow: 
\code{\link{cluster_profiles}()},
\code{\link{dpmgpd.cluster}()},
\code{\link{dpmix.cluster}()},
\code{\link{predict.dpmixgpd_cluster_fit}()},
\code{\link{print.dpmixgpd_cluster_bundle}()},
\code{\link{print.dpmixgpd_cluster_fit}()},
\code{\link{print.dpmixgpd_cluster_labels}()},
\code{\link{print.dpmixgpd_cluster_psm}()},
\code{\link{summary.dpmixgpd_cluster_bundle}()},
\code{\link{summary.dpmixgpd_cluster_fit}()},
\code{\link{summary.dpmixgpd_cluster_labels}()},
\code{\link{summary.dpmixgpd_cluster_psm}()}

Other cluster workflow: 
\code{\link{cluster_profiles}()},
\code{\link{dpmgpd.cluster}()},
\code{\link{dpmix.cluster}()},
\code{\link{predict.dpmixgpd_cluster_fit}()},
\code{\link{print.dpmixgpd_cluster_bundle}()},
\code{\link{print.dpmixgpd_cluster_fit}()},
\code{\link{print.dpmixgpd_cluster_labels}()},
\code{\link{print.dpmixgpd_cluster_psm}()},
\code{\link{summary.dpmixgpd_cluster_bundle}()},
\code{\link{summary.dpmixgpd_cluster_fit}()},
\code{\link{summary.dpmixgpd_cluster_labels}()},
\code{\link{summary.dpmixgpd_cluster_psm}()}
}
\concept{cluster workflow}
