% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/characterize.R
\name{characterize_clusters}
\alias{characterize_clusters}
\title{Characterise clusters with external (biological / clinical) variables}
\usage{
characterize_clusters(labels, metadata, continuous = NULL, categorical = NULL)
}
\arguments{
\item{labels}{Cluster label of each object (vector; \code{NA} allowed).}

\item{metadata}{A data frame of external variables, one row per object, in the
same order as \code{labels}.}

\item{continuous, categorical}{Optional character vectors naming the columns to
treat as continuous / categorical. If \code{NULL}, numeric columns are taken
as continuous and the rest as categorical.}
}
\value{
A list with \code{continuous} (per-cluster summary, long format),
\code{continuous_tests} (one row per variable: \code{KW_p}, \code{eta2},
\code{gradient} -- the clusters ordered by mean -- and a monotone-trend
\code{trend_rho}/\code{trend_p}), \code{categorical} (counts and column
percentages) and \code{categorical_tests} (\code{p}, \code{cramers_v}).
}
\description{
For a clustering, summarise how each external variable differs across the
clusters. Continuous variables get \eqn{n}, mean, SD, median, IQR and range
\emph{per cluster}, an overall Kruskal-Wallis test, a rank \eqn{\eta^2} effect
size, and \strong{gradient detection} (are the cluster means monotonically
ordered?). Categorical variables get per-cluster counts and column
percentages, a chi-squared / Fisher test and Cramer's V. The emphasis is on
effect sizes and descriptive summaries rather than p-values alone.
}
\examples{
data(mosaic_toy)
fit <- M_ABCpp(mosaic_toy$List, numsim = 40, NC = 3)
cl  <- mosaic_labels(fit, 3)
meta <- data.frame(score = rnorm(length(cl)), grp = sample(c("A", "B"), length(cl), TRUE))
ch  <- characterize_clusters(cl, meta)
ch$continuous_tests
}
\seealso{
\code{\link{plot_cluster_profile}}, \code{\link{cluster_biology_panel}}
}
