% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/ttl-alignment.R
\name{align_gazepoint_biometrics_to_ttl}
\alias{align_gazepoint_biometrics_to_ttl}
\title{Align Gazepoint biometric samples to TTL events}
\usage{
align_gazepoint_biometrics_to_ttl(
  data,
  ttl_cols = NULL,
  event_col = NULL,
  ttl_valid_col = NULL,
  time_col = NULL,
  sample_col = NULL,
  group_cols = NULL,
  participant_col = NULL,
  stimulus_col = NULL,
  trial_col = NULL,
  event_value = NULL,
  valid_values = c(TRUE, 1, "1"),
  event_edge = c("rising", "change", "active"),
  pre_window_ms = 1000,
  post_window_ms = 5000,
  pre_window_samples = NULL,
  post_window_samples = NULL,
  collapse_nearby_ms = 0,
  require_valid_ttl = TRUE
)
}
\arguments{
\item{data}{A data frame containing biometric samples.}

\item{ttl_cols}{Optional TTL marker columns. If \code{NULL}, the function first
looks for \code{ttl_marker}, then raw \code{TTL0}-\code{TTL6} columns.}

\item{event_col}{Optional single user-specified event column. If supplied, it
is used instead of automatic TTL-column detection.}

\item{ttl_valid_col}{Optional TTL validity column. If \code{NULL}, the function
looks for \code{ttl_validity_flag} or \code{TTLV}.}

\item{time_col}{Optional time column. If \code{NULL}, common time-column names are
detected automatically when present.}

\item{sample_col}{Optional sample/counter column. If \code{NULL}, \code{CNT}/\code{cnt} is
used when present; otherwise row order is used.}

\item{group_cols}{Optional grouping columns. If \code{NULL}, the function uses
available participant/stimulus/trial-like columns when present.}

\item{participant_col, stimulus_col, trial_col}{Optional explicit grouping
columns to add to \code{group_cols}.}

\item{event_value}{Optional value(s) that define an active event. If \code{NULL},
non-zero numeric/logical values and non-empty character values are treated
as active.}

\item{valid_values}{Values treated as valid in the TTL validity column.}

\item{event_edge}{Event-detection rule. \code{"rising"} keeps inactive-to-active
transitions, \code{"change"} keeps changes among active event values, and
\code{"active"} keeps every active sample.}

\item{pre_window_ms, post_window_ms}{Event window in milliseconds when a usable
time column is available.}

\item{pre_window_samples, post_window_samples}{Event window in samples when no
usable time column is available. If omitted, only the event sample is kept.}

\item{collapse_nearby_ms}{Optional minimum distance between retained events
within a group, in milliseconds.}

\item{require_valid_ttl}{If \code{TRUE}, a detected TTL validity column must be
active for a row to count as an event.}
}
\value{
A list with \code{overview}, \code{events}, \code{aligned_data}, and \code{settings}.
}
\description{
Aligns biometric rows to TTL/event markers and returns event-relative time and
sample indices. The helper is conservative: TTL events are detected from
rising edges by default, validity flags are used when available, and no
physiological interpretation is added.
}
