% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/panoramic-visualization.R
\name{plot_representative_samples}
\alias{plot_representative_samples}
\title{Plot Representative Samples for Significant Differential Hits}
\usage{
plot_representative_samples(
  se_stats,
  se_meta,
  spe_list,
  top_hits = NULL,
  sig_col = c("fdr_diff", "p_diff"),
  alpha = 0.05,
  top_n = 10L,
  group_col = "group",
  cell_type_col = "cell_type",
  sample_col = "sample",
  out_prefix = NULL
)
}
\arguments{
\item{se_stats}{A \code{SummarizedExperiment} from
\code{panoramic_spatialstats()} containing sample-level \code{yi}.}

\item{se_meta}{A \code{SummarizedExperiment} from
\code{panoramic_meta_mv()} containing contrast columns.}

\item{spe_list}{Named list of \code{SpatialExperiment} objects.}

\item{top_hits}{Optional data.frame of selected features. If \code{NULL},
features are selected from \code{se_meta} using \code{sig_col},
\code{alpha}, and \code{top_n}.}

\item{sig_col}{One of \code{"fdr_diff"} or \code{"p_diff"} used when
selecting \code{top_hits = NULL}.}

\item{alpha}{Numeric threshold for feature selection when
\code{top_hits = NULL}.}

\item{top_n}{Integer number of selected hits when \code{top_hits = NULL}.}

\item{group_col}{Character group column in \code{colData(se_stats)}.}

\item{cell_type_col}{Character cell-type column in \code{colData(spe)}.}

\item{sample_col}{Character sample-id column in \code{colData(se_stats)}.}

\item{out_prefix}{Optional output prefix. If provided, each panel is saved as
PNG/PDF and the returned index includes file paths.}
}
\value{
A list with \code{plots} (named list of ggplot objects) and
\code{index} (data.frame summarizing selected hits and samples).
}
\description{
Select representative samples per group for significant differential
colocalization features, then build side-by-side spatial panels
highlighting source and target cell types.
}
\details{
This helper currently supports exactly two groups in \code{group_col}.
}
\examples{
sample_ids <- paste0("sample_", seq_len(4L))
spe_list <- stats::setNames(
  lapply(sample_ids, function(sid) {
    panoramic_simulate_spe(
      n_cells = 40,
      sample_id = sid,
      cell_types = c("A", "B"),
      scenario = "random",
      seed = 1
    )
  }),
  sample_ids
)

yi <- matrix(c(0.10, 0.15, 0.25, 0.30), nrow = 1)
vi <- matrix(rep(0.05, 4), nrow = 1)
colnames(yi) <- colnames(vi) <- sample_ids
se_stats <- SummarizedExperiment::SummarizedExperiment(
  assays = list(yi = yi, vi = vi),
  rowData = S4Vectors::DataFrame(ct1 = "A", ct2 = "B", radius_um = 10),
  colData = S4Vectors::DataFrame(
    sample = sample_ids,
    group = c("control", "control", "case", "case")
  )
)

se_meta <- SummarizedExperiment::SummarizedExperiment(
  assays = list(dummy = matrix(0, nrow = 1, ncol = 1)),
  rowData = S4Vectors::DataFrame(
    ct1 = "A",
    ct2 = "B",
    radius_um = 10,
    beta_diff = 0.25,
    se_diff = 0.10,
    z_diff = 2.5,
    p_diff = 0.012,
    fdr_diff = 0.02,
    control_mu_hat = 0.125,
    case_mu_hat = 0.275
  )
)

out <- plot_representative_samples(
  se_stats = se_stats,
  se_meta = se_meta,
  spe_list = spe_list,
  sig_col = "p_diff",
  alpha = 0.05,
  top_n = 1
)
names(out)
}
