% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/module4_primary.R
\name{select_sigma_hits}
\alias{select_sigma_hits}
\title{Select primary-screen hits by distance from the library distribution}
\usage{
select_sigma_hits(
  data,
  value = "inhibition",
  method = c("robust", "sd"),
  n_sigma = 3,
  direction = c("greater", "less", "two.sided"),
  compound_col = "compound_id"
)
}
\arguments{
\item{data}{An \code{hts_norm} object or long data frame.}

\item{value}{Name of the activity column. Default \code{"inhibition"}.}

\item{method}{How to estimate the distribution centre and spread:
\code{"robust"} (default) uses the median and MAD (scaled by 1.4826 to match the
SD of a normal); \code{"sd"} uses the plain mean and standard deviation.}

\item{n_sigma}{Number of sigma a compound must clear to be called a hit.
Default \code{3}.}

\item{direction}{Tail to test: \code{"greater"} (default, high activity),
\code{"less"} (low activity) or \code{"two.sided"} (either tail, scored on \code{abs(z)}).}

\item{compound_col}{Name of the compound column. Default \code{"compound_id"}.}
}
\value{
A data frame with one row per compound: \code{compound_id}, \code{activity},
\code{sigma} (signed z-score), \code{sigma_level} (0-3, how many sigma it clears in
the tested direction), \code{band} (an ordered-factor label) and \code{is_hit}
(\code{sigma_level >= n_sigma}). The distribution \code{center}, \code{scale}, \code{method},
\code{n_sigma} and \code{direction} are stored as attributes.
}
\description{
Treats the per-compound activity of the whole library as an approximately
normal "inactive" distribution and flags compounds sitting far out in the
tail. Each compound receives a z-score (how many standard deviations it lies
from the library centre) and is binned by whether it clears 1, 2 or 3 sigma.
By default the centre and spread are estimated \emph{robustly} (median and MAD),
the HTS-standard choice: a handful of genuine hits would otherwise inflate a
plain mean/SD and mask themselves (with too wide an SD nothing reaches 3
sigma).
}
\examples{
norm <- norm_by_control(baseline_subtract(read_hts_plate(hts_primary_raw)))
hits <- select_sigma_hits(norm, n_sigma = 3)
sum(hits$is_hit)

}
\seealso{
\code{\link[=summarize_sigma_hits]{summarize_sigma_hits()}}, \code{\link[=plot_sigma_hits]{plot_sigma_hits()}}, \code{\link[=select_primary_hit]{select_primary_hit()}}
}
