% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/module1_preqc.R
\name{read_plate_layout}
\alias{read_plate_layout}
\title{Read a user-defined plate-map layout file}
\usage{
read_plate_layout(
  file,
  plate_id = NULL,
  nc_labels = c("NC", "DMSO", "vehicle", "negative_ctrl", "neg_ctrl"),
  pc_labels = c("PC", "kill_ctrl", "positive_ctrl", "pos_ctrl"),
  blank_labels = c("Blank", "edgewell", "empty", "blank", "na", ""),
  concentration_file = NULL,
  sheet = 1,
  sep = "\\t"
)
}
\arguments{
\item{file}{Path to the plate-map grid (\code{.csv}, \code{.txt}/\code{.tsv} or
\code{.xlsx}/\code{.xls}).}

\item{plate_id}{Optional plate identifier attached to every well of the
layout, so the same map can be matched to a specific plate.}

\item{nc_labels, pc_labels, blank_labels}{Character vectors of the cell labels
that mark negative controls, positive controls and blank/empty wells. All
other non-empty labels become compound identifiers.}

\item{concentration_file}{Optional path to a second grid (same layout) giving
the concentration of each well.}

\item{sheet, sep}{Worksheet (Excel) and field separator (\code{.txt}/\code{.tsv}) passed
to the reader.}
}
\value{
An \code{hts_layout} data frame with one row per well and the columns
\code{plate_id}, \code{well}, \code{row}, \code{col}, \code{well_type} (\code{"NC"}, \code{"PC"}, \code{"Blank"} or
\code{"compound"}), \code{compound_id} and \code{concentration}.
}
\description{
Reads a plate map that \strong{you author yourself} in Excel or CSV to declare, for
every well, whether it holds a negative control, a positive control, a blank
(empty/edge) well or a test compound. Nothing about the layout is fixed by the
package: you are free to place the controls, blanks and compounds in whichever
wells your assay uses, and \code{\link[=apply_plate_layout]{apply_plate_layout()}} then stamps those roles onto
the measured readings.
}
\details{
The expected file is a \strong{grid} that mirrors the physical plate: the first
column holds the row letters (\code{A}, \code{B}, ...), the remaining column headers are
the plate column numbers (\code{1}, \code{2}, ... \code{24}), and each cell contains the
label for that well. Labels are matched case-insensitively against
\code{nc_labels}, \code{pc_labels} and \code{blank_labels}; any other non-empty label is
treated as a compound identifier. An optional second grid of the same shape
supplies per-well concentrations.
}
\examples{
f <- system.file("extdata", "plate_layout_example.csv", package = "diffHTS")
layout <- read_plate_layout(f, plate_id = "P01")
table(layout$well_type)

}
\seealso{
\code{\link[=apply_plate_layout]{apply_plate_layout()}}, \code{\link[=read_hts_plate]{read_hts_plate()}}, \code{\link[=check_control_label]{check_control_label()}}
}
