% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/visualization.R
\name{plot_plate_heatmap}
\alias{plot_plate_heatmap}
\title{Plate-layout heatmap of well readouts}
\usage{
plot_plate_heatmap(
  data,
  fill = "normalized_cell_count",
  well_col = NULL,
  row_col = "plate_rows",
  col_col = "plate_columns",
  label = NULL,
  control_col = NULL,
  nc_values = c("NC", "negative_ctrl"),
  pc_values = c("PC", "positive_ctrl"),
  circle_size = NULL,
  plate = NULL,
  plate_col = "plateID",
  plate_type = NULL,
  title = NULL,
  na_value = "grey90"
)
}
\arguments{
\item{data}{A long-format data frame with one row per well.}

\item{fill}{Name of the column mapped to tile colour, as a string. Default
\code{"normalized_cell_count"}. Numeric columns use a continuous viridis scale;
character/factor columns use a discrete viridis scale (useful for showing
the well-type layout).}

\item{well_col}{Optional name of a single well-identifier column such as
\code{"A1"} or \code{"B12"}. If supplied it is split into a row letter and column
number and \code{row_col}/\code{col_col} are ignored.}

\item{row_col, col_col}{Names of the row (letter) and column (number)
columns used when \code{well_col} is \code{NULL}. Defaults \code{"plate_rows"} and
\code{"plate_columns"}. Any non-digit characters in the column values (for
example an \code{"X"} prefix) are stripped.}

\item{label}{Optional name of a column whose values are printed inside each
tile (for example a drug name or a QC flag). Default \code{NULL}.}

\item{control_col}{Optional name of a column identifying each well's role
(for example \code{"well_type"} or \code{"experiment_type"}). When supplied, the
negative- and positive-control wells are circled on the plot so that they
can be told apart from the drug-treated wells at a glance. Default \code{NULL}
(no wells circled).}

\item{nc_values, pc_values}{Character vectors of the labels in \code{control_col}
that mark negative and positive controls. Defaults cover the package's
canonical labels (\code{"NC"}/\code{"PC"}) and the common long forms
(\code{"negative_ctrl"}/\code{"positive_ctrl"}).}

\item{circle_size}{Size of the control-marking circles. When \code{NULL}
(default) it is scaled to the plate so that 96- and 384-well plates are
both legible.}

\item{plate}{Optional plate identifier; if supplied \code{data} is filtered to
this plate. When \code{NULL} and several plates are present the plot is
facetted by \code{plate_col}.}

\item{plate_col}{Name of the plate identifier column, as a string. Default
\code{"plateID"}.}

\item{plate_type}{Plate format, either \code{96} or \code{384}, controlling the size
of the drawn grid. When \code{NULL} (default) it is inferred from the observed
rows and columns.}

\item{title}{Optional plot title.}

\item{na_value}{Colour used for wells with no data. Default \code{"grey90"}.}
}
\value{
A \link[ggplot2:ggplot]{ggplot2::ggplot} object: one tile per well, coloured by \code{fill},
with row A at the top and column 1 at the top-left, drawn with a fixed
aspect ratio. When \code{control_col} is supplied the negative- and
positive-control wells are outlined with coloured circles.
}
\description{
Draws a microplate as a grid of wells (rows lettered top-to-bottom, columns
numbered left-to-right) coloured by a per-well readout such as normalised
cell count, so that drug-treated wells and their positive/negative controls
can be inspected in their physical plate positions. Missing wells are shown
as empty cells, making layout errors and edge effects easy to spot. This
abstracts the per-plate \code{heatmap.2()} plate maps used in the screening
pipeline, but is built on \pkg{ggplot2} and needs no external heatmap
package.
}
\details{
Duplicate wells (for example replicates sharing a position) are
summarised by their mean for numeric \code{fill} and concatenated for
categorical \code{fill}/\code{label}.
}
\examples{
# A single 96-well plate coloured by normalised cell count.
plot_plate_heatmap(subset(screen_plate_layout, plateID == "EXP99_Gy0"))

# Show the well-type layout instead, both plates side by side.
plot_plate_heatmap(screen_plate_layout, fill = "experiment_type")

# Circle the negative and positive controls on a raw 96-well plate.
plot_plate_heatmap(
  subset(hts_primary_raw, plate_id == "P01"),
  fill = "signal", well_col = "well", plate_col = "plate_id",
  control_col = "well_type"
)

# A realistic 384-well plate (the outer 2-well ring is a compound-free buffer
# that reads at the low, no-cell level; controls sit on a diagonal in the two
# inset columns 3 and 22).
plot_plate_heatmap(hts_plate_384, fill = "signal", well_col = "well",
  control_col = "well_type", plate_col = "plate_id", plate_type = 384)

}
\seealso{
\code{\link[=plot_qc_boxplot]{plot_qc_boxplot()}}, \code{\link[=plot_control_scatter]{plot_control_scatter()}}
}
