#' Example two-condition dose-response screen
#'
#' A small, simulated high-throughput drug-screening dataset in long (tidy)
#' format, mimicking a two-condition experiment in which each drug is tested
#' across a concentration series under a baseline (`"Gy0"`) and a treatment
#' (`"Gy2"`) condition, alongside negative and positive control wells. It is
#' sized to run the package examples and vignette quickly.
#'
#' @format A data frame with one row per well and the following columns:
#' \describe{
#'   \item{plateID}{Plate identifier (character).}
#'   \item{drug_name}{Drug identifier, or a control label such as `"DMSO"`
#'     (negative) or `"kill_ctrl"` (positive).}
#'   \item{experiment_type}{Well role: `"sample"`, `"negative_ctrl"` or
#'     `"positive_cttl"`.}
#'   \item{condition}{Experimental condition, `"Gy0"` (baseline) or `"Gy2"`
#'     (treatment).}
#'   \item{concentration}{Drug concentration (micromolar).}
#'   \item{normalized_cell_count}{Viability normalised to the negative control
#'     (roughly 0-1).}
#' }
#'
#' @details The data are simulated (see `data-raw/make_datasets.R`) and do not
#'   correspond to any real compound or cell line.
#'
#' @seealso [screen_delta_auc]
#' @keywords datasets
"screen_doseresponse"

#' Example differential-AUC hit table
#'
#' A small, simulated table of differential (delta) AUC values with one row per
#' drug and one column per cell line, used to demonstrate hit selection and
#' heatmap/scatter visualisation across several cancer cell lines and a normal
#' (`MRC5`) cell line.
#'
#' @format A data frame with one row per drug and the following columns:
#' \describe{
#'   \item{drug_name}{Drug identifier (character).}
#'   \item{A549}{Delta AUC in the A549 lung cancer cell line (numeric).}
#'   \item{H1299}{Delta AUC in the H1299 lung cancer cell line (numeric).}
#'   \item{H1975}{Delta AUC in the H1975 lung cancer cell line (numeric).}
#'   \item{H2030}{Delta AUC in the H2030 lung cancer cell line (numeric).}
#'   \item{MRC5}{Delta AUC in the MRC5 normal lung fibroblast cell line
#'     (numeric).}
#' }
#'
#' @details The data are simulated (see `data-raw/make_datasets.R`) and do not
#'   correspond to any real compound. Negative values indicate treatment-induced
#'   sensitisation.
#'
#' @seealso [screen_doseresponse]
#' @keywords datasets
"screen_delta_auc"

#' Example per-plate quality-control summary
#'
#' A small, simulated per-plate quality-control (QC) table spanning several
#' experiments (cell lines), each with a few plates. Every plate carries its
#' negative- and positive-control replicate readouts together with the QC
#' metrics derived from them, so the table can drive the control scatter, the
#' circular control heatmap and the circular Z'-factor plot. A couple of plates
#' are deliberately noisy so that passing and failing plates are both present.
#'
#' @format A data frame with one row per plate and the following columns:
#' \describe{
#'   \item{plateID}{Plate identifier such as `"EXP76_01"` (character).}
#'   \item{experimentID}{Experiment identifier (character), the plate prefix.}
#'   \item{cell_line}{Cell line assayed on the experiment (character).}
#'   \item{plateNumber}{Plate order within the experiment (integer).}
#'   \item{z_factor}{Assay Z-factor from sample and negative-control wells.}
#'   \item{z_prime}{Z-prime factor from negative- and positive-control wells.}
#'   \item{sb_value}{Signal-to-background ratio.}
#'   \item{sn_value}{Signal-to-noise value.}
#'   \item{ssmd_value}{Strictly standardised mean difference.}
#'   \item{cv_negative_ctrl}{Coefficient of variation of the negative controls
#'     (percent).}
#'   \item{neg_ctrl_1, neg_ctrl_2, neg_ctrl_3, neg_ctrl_4, neg_ctrl_5,
#'     neg_ctrl_6}{Negative-control well readouts.}
#'   \item{pos_ctrl_1, pos_ctrl_2, pos_ctrl_3, pos_ctrl_4, pos_ctrl_5,
#'     pos_ctrl_6}{Positive-control well readouts.}
#' }
#'
#' @details The data are simulated (see `data-raw/make_datasets.R`) and do not
#'   correspond to any real compound or cell line.
#'
#' @seealso [plot_control_scatter()], [plot_qc_metric_circular()],
#'   [plot_qc_circular_heatmap()]
#' @keywords datasets
"screen_plate_qc"

#' Example 96-well plate layout with well positions
#'
#' A small, simulated 96-well plate (8 rows by 12 columns) assayed under two
#' conditions (`"Gy0"` and `"Gy2"`), in long (one row per well) format. The
#' layout follows good HTS practice: the outer ring (row A, row H, columns 1 and
#' 12) is an empty evaporation buffer, the two flanking columns (2 and 11) carry
#' the positive (kill) and negative (DMSO) controls in a rotationally balanced
#' diagonal pattern, and the interior block (rows B-G, columns 3-10) holds an
#' 8-point dose series of one drug per row. It is used to demonstrate the
#' plate-layout heatmap [plot_plate_heatmap()].
#'
#' @format A data frame with one row per well and the following columns:
#' \describe{
#'   \item{plateID}{Plate identifier such as `"EXP99_Gy0"` (character).}
#'   \item{condition}{Experimental condition, `"Gy0"` or `"Gy2"`.}
#'   \item{well}{Well identifier such as `"A1"` (character).}
#'   \item{plate_rows}{Plate row letter, `"A"`-`"H"` (character).}
#'   \item{plate_columns}{Plate column number, `1`-`12` (integer).}
#'   \item{drug_name}{Drug identifier, or a control label (`"DMSO"`,
#'     `"kill_ctrl"`), or `NA` for empty buffer wells.}
#'   \item{experiment_type}{Well role: `"sample"`, `"negative_ctrl"`,
#'     `"positive_ctrl"` or `"empty"` (evaporation-buffer ring).}
#'   \item{concentration}{Drug concentration (micromolar), `NA` for controls
#'     and empty wells.}
#'   \item{normalized_cell_count}{Viability normalised to the negative control;
#'     empty buffer wells hold no live cells and read near the kill control.}
#' }
#'
#' @details The data are simulated (see `data-raw/make_datasets.R`) and do not
#'   correspond to any real compound or cell line.
#'
#' @seealso [plot_plate_heatmap()]
#' @keywords datasets
"screen_plate_layout"

#' Example single-concentration primary screen (raw signals)
#'
#' A small, simulated primary high-throughput screen in 96-well plate format
#' with raw readout signals, used to demonstrate the pre-QC, normalisation,
#' replicate and primary-hit modules. The layout follows good HTS practice: the
#' outer ring of wells (row A, row H and columns 1 and 12) is a compound-free
#' evaporation buffer stored as `"Blank"` wells, the two inset columns 2 and 11
#' carry the controls in a rotationally balanced *diagonal* pattern (positive
#' controls top-left/bottom-right, negative controls top-right/bottom-left), and
#' the 48 compounds fill the interior block (rows B-G, columns 3-10). Plates
#' `"P01"` and `"P02"` are good replicates (Z-prime around 0.8) while `"P03"` is
#' a failed plate.
#'
#' @format A data frame with one row per well and the following columns:
#' \describe{
#'   \item{plate_id}{Plate identifier, `"P01"`, `"P02"` or `"P03"` (character).}
#'   \item{well}{Well identifier such as `"A1"` (character).}
#'   \item{row}{Plate row letter, `"A"`-`"H"` (character).}
#'   \item{col}{Plate column number, `1`-`12` (integer).}
#'   \item{well_type}{Well role: `"NC"` (negative), `"PC"` (positive),
#'     `"Blank"` or `"compound"` (character).}
#'   \item{compound_id}{Compound identifier such as `"CPD001"`, `NA` for
#'     control and blank wells (character).}
#'   \item{concentration}{Compound concentration (micromolar), `NA` for
#'     controls (numeric).}
#'   \item{signal}{Raw instrument signal (numeric).}
#' }
#'
#' @details The data are simulated (see `data-raw/make_datasets.R`) and do not
#'   correspond to any real compound or cell line.
"hts_primary_raw"

#' Example single 384-well screening plate (realistic layout)
#'
#' A single simulated 384-well plate (`"EXP87P01"`) whose layout mirrors a real
#' cell-based high-throughput screen (see `EXP87/`). The two outermost rings of
#' wells (rows A, B, O, P and columns 1, 2, 23, 24) are kept free of compound to
#' avoid edge-evaporation artefacts. They still hold medium but no live cells,
#' so the instrument reads them at the same low, "dead" level as the kill
#' control; they are stored as `"edgewell"` wells (not omitted). The controls
#' sit inset from the true plate edge in the two innermost flanking columns
#' (3 and 22), arranged in a rotationally balanced *diagonal* pattern: column 3
#' holds the positive (kill) control in its top half (rows C-H) and the negative
#' (DMSO) control in its bottom half (rows I-N), while column 22 mirrors it
#' (negative top, positive bottom). This diagonal split averages out
#' spatial/edge signal gradients. Columns 4-21 across the interior rows C-N hold
#' the test compounds. Used to demonstrate plate-layout heatmaps with control
#' circling on a 384-well plate.
#'
#' @format A data frame with one row per well (all 384) and the following
#'   columns:
#' \describe{
#'   \item{plate_id}{Plate identifier, `"EXP87P01"` (character).}
#'   \item{well}{Well address such as `"C03"` (character).}
#'   \item{row}{Plate row letter, `"A"`-`"P"` (character).}
#'   \item{col}{Plate column number, `1`-`24` (integer).}
#'   \item{well_type}{Well role: `"PC"` (positive control), `"NC"` (negative
#'     control), `"compound"` or `"edgewell"` (empty buffer) (character).}
#'   \item{compound_id}{Compound identifier for test wells, `NA` for controls
#'     and edge wells (character).}
#'   \item{concentration}{Compound concentration (micromolar); `NA` for
#'     controls and edge wells (numeric).}
#'   \item{signal}{Raw luminescence read-out (numeric).}
#' }
#'
#' @details The data are simulated (see `data-raw/make_datasets.R`) and do not
#'   correspond to any real compound. All 384 wells are stored; the empty edge
#'   wells carry only a low background/no-cell reading.
"hts_plate_384"

#' Example gradient dose-response secondary screen
#'
#' A small, simulated dose-response confirmation screen: ten compounds tested
#' across a concentration gradient in three cell lines with two replicates each.
#' Used to demonstrate the dose-response fitting, AUC and clustering modules.
#'
#' @format A data frame with one row per measurement and the following columns:
#' \describe{
#'   \item{compound_id}{Compound identifier such as `"CPD001"` (character).}
#'   \item{cell_line}{Cell line, `"A549"`, `"H1299"` or `"MRC5"` (character).}
#'   \item{concentration}{Compound concentration (micromolar) (numeric).}
#'   \item{replicate}{Technical replicate index, `1` or `2` (integer).}
#'   \item{viability}{Percent viability relative to vehicle control (numeric).}
#' }
#'
#' @details The data are simulated (see `data-raw/make_datasets.R`); the cell
#'   line `"MRC5"` is made comparatively resistant.
"hts_dose_response"

#' Example compound metadata
#'
#' A small, simulated compound annotation table used to demonstrate hit
#' annotation. Keyed by `compound_id` to join onto screening results.
#'
#' @format A data frame with one row per compound and the following columns:
#' \describe{
#'   \item{compound_id}{Compound identifier such as `"CPD001"` (character).}
#'   \item{compound_name}{Human-readable compound name (character).}
#'   \item{target}{Nominal molecular target (character).}
#'   \item{moa}{Mechanism of action (character).}
#'   \item{library_source}{Source library the compound came from (character).}
#' }
#'
#' @details The data are simulated (see `data-raw/make_datasets.R`) and do not
#'   correspond to any real compound.
"hts_compound_meta"
