% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/sync-drift-diagnostics.R
\name{estimate_gazepoint_signal_lag}
\alias{estimate_gazepoint_signal_lag}
\title{Estimate lag between two Gazepoint biometric signals}
\usage{
estimate_gazepoint_signal_lag(
  data,
  signal_x_col,
  signal_y_col,
  time_col = NULL,
  group_cols = NULL,
  max_lag = 1000,
  lag_step = NULL,
  method = c("pearson", "spearman"),
  min_complete_pairs = 20,
  use_first_difference = FALSE
)
}
\arguments{
\item{data}{A Gazepoint biometric data frame.}

\item{signal_x_col}{Name of the first signal column.}

\item{signal_y_col}{Name of the second signal column.}

\item{time_col}{Optional time or counter column. If \code{NULL}, a common
Gazepoint time/counter column is detected.}

\item{group_cols}{Optional grouping columns, such as participant, stimulus,
trial, or source file.}

\item{max_lag}{Maximum absolute lag to evaluate, in the same units as
\code{time_col}.}

\item{lag_step}{Step size between candidate lags, in the same units as
\code{time_col}. If \code{NULL}, the median positive time step is used.}

\item{method}{Correlation method passed to \code{\link[stats:cor]{stats::cor()}}.}

\item{min_complete_pairs}{Minimum complete aligned observations required for
a candidate lag.}

\item{use_first_difference}{If \code{TRUE}, correlations are estimated on first
differences rather than raw signal levels.}
}
\value{
A list with \code{overview}, \code{lag_by_group}, \code{lag_profile}, and \code{settings}.
}
\description{
Estimates the time shift that maximizes the association between two recorded
biometric signals within each group. This is a conservative synchronization
diagnostic for inspecting whether two recorded traces show similar temporal
structure at different shifts. It should not be interpreted as causal timing
or true physiological latency unless the design includes appropriate event
markers and independently justified signal-processing assumptions.
}
