% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/lcmsPlot-class.R
\name{lp_peak_density}
\alias{lp_peak_density}
\title{Plot the peak density for one or more m/z features}
\usage{
lp_peak_density(
  features = NULL,
  bw = 30,
  min_fraction = NULL,
  min_samples = 1L,
  sample_groups = NULL,
  max_features = 50L,
  rt_unit = "second"
)
}
\arguments{
\item{features}{A \code{matrix} or \code{data.frame} with columns \code{mzmin} and \code{mzmax}
(required) and \code{rtmin}, \code{rtmax} (optional). Each row defines one m/z bin.
When omitted, the features are taken from \code{lp_chromatogram} if it has
already been called on the same object.}

\item{bw}{A \code{numeric} value specifying the kernel density bandwidth in
seconds. Passed to \code{\link[stats:density]{stats::density()}}. Defaults to \code{30}.}

\item{min_fraction}{A \code{numeric} value in \verb{[0, 1]}. When supplied, simulates
the \code{PeakDensityParam} grouping algorithm and draws semi-transparent
rectangles for feature groups where at least this fraction of samples (per
group) contain a peak. Defaults to \code{NULL} (no simulation).}

\item{min_samples}{An \code{integer} specifying the minimum absolute number of
samples per group required to define a feature group. Only used when
\code{min_fraction} is set. Defaults to \code{1L}.}

\item{sample_groups}{A vector of length equal to the number of samples
assigning each sample to a group (as in \code{PeakDensityParam}). Defaults to
\code{NULL}, which treats all samples as a single group.}

\item{max_features}{An \code{integer} specifying the maximum number of feature
group rectangles to draw per m/z bin. Defaults to \code{50L}.}

\item{rt_unit}{A \code{character} value indicating the unit for the RT axis;
one of \code{"second"} (default) or \code{"minute"}.}
}
\value{
This function returns another function that takes an \code{lcmsPlot}
object and produces a modified version containing the generated peak density
data in its \code{data} slot. It is designed to be used with the \code{+} operator,
which serves as a layering mechanism.
}
\description{
The \code{lp_peak_density} function produces a peak density plot.
For each supplied feature (m/z bin):
\itemize{
\item The x axis shows retention time.
\item The y axis shows sample indices (1 to n), positioned within the density
range.
\item Detected peaks are plotted as coloured points at each sample's position.
\item The kernel density estimate of peak apex RTs is drawn as a line.
\item When \code{min_fraction} is supplied, the density-descent grouping algorithm
is simulated and feature groups that pass the threshold are highlighted
with semi-transparent rectangles.
}
}
\examples{
data_obj <- get_XCMSnExp_object_example(
  indices = 1:3,
  should_group_peaks = TRUE)
p <- lcmsPlot(data_obj, sample_id_column = "sample_name") +
  lp_peak_density(
    features = rbind(c(mzmin = 334.9, mzmax = 335.1,
                       rtmin = 2700,  rtmax = 2900)),
    bw = 30,
    min_fraction = 0.5)
p
}
