% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/validity-dropouts.R
\name{flag_gazepoint_biometric_dropouts}
\alias{flag_gazepoint_biometric_dropouts}
\title{Flag biometric dropouts and flatline periods}
\usage{
flag_gazepoint_biometric_dropouts(
  data,
  signal_cols = NULL,
  group_cols = NULL,
  time_col = NULL,
  min_missing_run = 5L,
  min_flatline_run = 10L,
  constant_tolerance = 0,
  prefix = "biometric_dropout"
)
}
\arguments{
\item{data}{A data frame.}

\item{signal_cols}{Optional character vector of biometric signal columns. If
\code{NULL}, common Gazepoint biometric signal columns are detected.}

\item{group_cols}{Optional grouping columns. Runs are computed separately
within each group.}

\item{time_col}{Optional time column used to order rows within each group
before run detection. If \code{NULL}, the current row order is used.}

\item{min_missing_run}{Minimum consecutive missing/non-finite samples required
to flag a missing dropout.}

\item{min_flatline_run}{Minimum consecutive unchanged finite samples required
to flag a flatline dropout.}

\item{constant_tolerance}{Numeric tolerance used when detecting unchanged
values for flatline runs.}

\item{prefix}{Prefix for generated dropout columns.}
}
\value{
The input data frame with added logical dropout columns. The attributes
\code{dropout_summary} and \code{dropout_settings} contain structured summaries.
}
\description{
Flags missing-value runs and sustained flatline runs in Gazepoint biometric
signal columns. Missing dropouts are defined as consecutive missing or
non-finite numeric samples. Flatline dropouts are defined as consecutive
finite numeric samples that remain unchanged within a tolerance.
}
\details{
The function adds row-level flags and stores a dropout summary in the returned
data frame attributes. It does not remove rows.
}
\examples{
df <- data.frame(
  CNT = 1:8,
  GSR = c(1, NA, NA, NA, 2, 2, 2, 3),
  HR = c(70, 71, 72, 73, 74, 75, 76, 77)
)
flag_gazepoint_biometric_dropouts(df, min_missing_run = 3, min_flatline_run = 3)

}
