% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/within-unit-standardization.R
\name{standardize_gazepoint_biometrics_within_unit}
\alias{standardize_gazepoint_biometrics_within_unit}
\alias{standardise_gazepoint_biometrics_within_unit}
\title{Standardize biometric signals within participant or other analysis units}
\usage{
standardize_gazepoint_biometrics_within_unit(
  data,
  signal_cols = NULL,
  unit_cols = NULL,
  reference_col = NULL,
  reference_value = TRUE,
  suffix = "_z_within",
  center = TRUE,
  scale = TRUE,
  min_valid = 2,
  zero_sd_action = c("NA", "zero"),
  overwrite = FALSE
)

standardise_gazepoint_biometrics_within_unit(
  data,
  signal_cols = NULL,
  unit_cols = NULL,
  reference_col = NULL,
  reference_value = TRUE,
  suffix = "_z_within",
  center = TRUE,
  scale = TRUE,
  min_valid = 2,
  zero_sd_action = c("NA", "zero"),
  overwrite = FALSE
)
}
\arguments{
\item{data}{A data frame containing Gazepoint biometric data.}

\item{signal_cols}{Character vector of biometric signal columns to
standardize. If \code{NULL}, common numeric biometric columns are detected.}

\item{unit_cols}{Character vector defining the unit within which means and
standard deviations are computed. If \code{NULL}, common participant/session
columns are detected. If no columns are detected, the whole data frame is
treated as one unit.}

\item{reference_col}{Optional logical or categorical column identifying rows
used to estimate the reference mean and standard deviation. For example,
this can be a baseline-window flag. The resulting parameters are then
applied to all rows in the same unit.}

\item{reference_value}{Value in \code{reference_col} that marks reference rows.
Defaults to \code{TRUE}.}

\item{suffix}{Suffix for standardized output columns.}

\item{center}{Logical. If \code{TRUE}, subtract the within-unit reference mean.}

\item{scale}{Logical. If \code{TRUE}, divide by the within-unit reference
standard deviation.}

\item{min_valid}{Minimum number of finite reference observations required
per unit and signal.}

\item{zero_sd_action}{What to do when the within-unit standard deviation is
zero or unavailable. \code{"NA"} returns \code{NA}; \code{"zero"} returns zero for finite
centered values.}

\item{overwrite}{Logical. If \code{FALSE}, existing output columns are protected.}
}
\value{
A data frame with added standardized columns. Attributes include
\code{standardization_summary}, \code{standardization_parameters}, and \code{settings}.
}
\description{
Adds within-unit standardized biometric columns, usually within participant
or participant-by-session/stimulus groups. This is useful when the analysis
focuses on relative within-person signal change rather than absolute
between-person level differences.
}
\details{
The helper is intentionally conservative. It does not run automatically in
the main workflow and does not infer emotion, valence, stress, trust,
preference, cognition, or diagnosis. Within-unit z-scoring removes
between-unit level and scale differences and should therefore be reported
explicitly.
}
