% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/ttl.R
\name{extract_gazepoint_ttl_events}
\alias{extract_gazepoint_ttl_events}
\title{Extract Gazepoint TTL marker events}
\usage{
extract_gazepoint_ttl_events(
  data,
  ttl_columns = NULL,
  group_columns = NULL,
  validity_column = "TTLV",
  require_validity = TRUE,
  mode = c("changes", "nonzero"),
  include_initial = TRUE
)
}
\arguments{
\item{data}{A data frame or a path to a Gazepoint CSV export.}

\item{ttl_columns}{TTL marker columns. If \code{NULL}, the function uses all
available columns from \code{TTL0} to \code{TTL6}.}

\item{group_columns}{Optional grouping columns within which TTL changes are
detected, such as \code{source_participant}, \code{USER}, or \code{MEDIA_ID}.}

\item{validity_column}{Optional TTL validity column. Defaults to \code{"TTLV"}.}

\item{require_validity}{Logical. Should rows be retained only when
\code{validity_column} is present and greater than zero? Defaults to \code{TRUE}.}

\item{mode}{Event extraction mode. \code{"changes"} returns rows where TTL values
change. \code{"nonzero"} returns all rows with nonzero TTL values.}

\item{include_initial}{Should the first valid, non-missing TTL value within
each group be treated as an event when \code{mode = "changes"}?}
}
\value{
A data frame of TTL events.
}
\description{
Extracts TTL marker events from Gazepoint Biometrics exports. The function
can return either rows where TTL marker values change or all nonzero TTL
rows. By default, rows are retained only when the TTL validity column is
present and greater than zero. This avoids treating invalid placeholder TTL
values as experimental events.
}
