% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/hrv-surrogate-nonlinearity.R
\name{test_gazepoint_hrv_nonlinearity}
\alias{test_gazepoint_hrv_nonlinearity}
\title{Test HRV nonlinearity using surrogate data}
\usage{
test_gazepoint_hrv_nonlinearity(
  dat,
  ibi_col = "IBI",
  group_cols = NULL,
  metric = c("sample_entropy", "approximate_entropy", "sd1_sd2_ratio"),
  n_surrogates = 99,
  surrogate_method = c("phase_randomized", "shuffle"),
  m = 2,
  r_multiplier = 0.2,
  statistic_fun = NULL,
  seed = NULL
)
}
\arguments{
\item{dat}{A data frame containing IBI/RR intervals.}

\item{ibi_col}{Numeric IBI/RR interval column.}

\item{group_cols}{Optional grouping columns.}

\item{metric}{Nonlinear statistic to test.}

\item{n_surrogates}{Number of surrogate series per group.}

\item{surrogate_method}{\code{"phase_randomized"} or \code{"shuffle"}.}

\item{m}{Embedding dimension for entropy metrics.}

\item{r_multiplier}{Tolerance multiplier for entropy metrics.}

\item{statistic_fun}{Optional custom statistic function accepting numeric x.}

\item{seed}{Optional random seed.}
}
\value{
A list with \code{overview}, \code{results}, \code{surrogate_statistics}, and
\code{settings}.
}
\description{
Tests whether a nonlinear HRV statistic differs from surrogate RR/IBI
sequences. This is a screening tool for evidence inconsistent with a simple
linear stochastic null process. It does not prove deterministic chaos or
diagnose any condition.
}
