% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/visualization.R
\name{plot_qc_metric_circular}
\alias{plot_qc_metric_circular}
\title{Circular plot of a per-plate QC metric}
\usage{
plot_qc_metric_circular(
  data,
  metric = "z_prime",
  sector_col = "experimentID",
  x_col = "plateNumber",
  label_col = "plateID",
  threshold = 0.5,
  transform = TRUE,
  colors = c(Bad = "#D55E00", Normal = "#0072B2"),
  bar_lwd = 4,
  x_margin = 0.8,
  show_labels = TRUE,
  center_label = NULL
)
}
\arguments{
\item{data}{A data frame with one row per plate, such as \link{screen_plate_qc}.}

\item{metric}{Name of the metric column, as a string. Default \code{"z_prime"}.}

\item{sector_col}{Name of the column that defines the sectors (experiments),
as a string. Default \code{"experimentID"}.}

\item{x_col}{Name of the numeric within-sector position column (plate order),
as a string. Default \code{"plateNumber"}.}

\item{label_col}{Name of the column holding the plate identifier printed on
the outside of each bar, as a string. Default \code{"plateID"}; if the column is
absent the values of \code{x_col} are used instead.}

\item{threshold}{Numeric pass/fail cut-off. Plates whose metric is below
\code{threshold} are drawn in \code{bad_color}. Default \code{0.5}.}

\item{transform}{Logical; if \code{TRUE} (default) strongly negative metric values
(\verb{< -1}) are compressed with \code{-log10(-x)} for display, matching the
pipeline's Z'-factor plot.}

\item{colors}{Named character vector with entries \code{"Bad"} and \code{"Normal"}
giving the bar colours.}

\item{bar_lwd}{Line width of each plate bar. Default \code{4}.}

\item{x_margin}{Numeric angular padding (in \code{x_col} units) added to each side
of every sector so the first and last plate bars do not touch the sector
edges. Default \code{0.8}.}

\item{show_labels}{Logical; if \code{TRUE} (default) the plate identifier from
\code{label_col} is printed radially just outside each bar.}

\item{center_label}{Text drawn in the centre of the ring. Defaults to
\code{metric}.}
}
\value{
Invisibly \code{NULL}. Called for the side effect of drawing to the active
graphics device.
}
\description{
Draws a circular (\pkg{circlize}) scatter of a QC metric with one sector per
experiment and one point per plate, coloured by whether the plate passes a
threshold. This reproduces the whole-screen Z'-factor overview used in the
pipeline, where many plates across several experiments are compared on a
single ring.
}
\details{
Requires the suggested package \pkg{circlize}. Each experiment is a
sector and each plate a thin vertical bar drawn at its own \code{plateNumber}
position, rising from a zero baseline to the metric value, so the bars never
overlap. An angular \code{x_margin} keeps the first and last bars clear of the
sector edges, the plate identifier is printed radially just outside each
bar, and a short Y-axis on the first sector plus a dashed reference line at
\code{threshold} in every sector give the scale. The design scales to large
campaigns of roughly ten plates per experiment.
}
\examples{
if (requireNamespace("circlize", quietly = TRUE)) {
  plot_qc_metric_circular(screen_plate_qc, metric = "z_prime")
}

}
\seealso{
\code{\link[=plot_qc_metric_trend]{plot_qc_metric_trend()}}, \code{\link[=plot_qc_circular_heatmap]{plot_qc_circular_heatmap()}}
}
