# gp3tools 1.0.2

* Made one `fit_gazepoint_gca()` test robust to platform-specific mixed-model fallback behavior observed under CRAN no-long-double checks.

# gp3tools 1.0.1

* Prepared the package for CRAN-oriented release validation.
* Added citation metadata through `CITATION.cff` and `inst/CITATION`.
* Added GitHub Actions R-CMD-check workflow for Windows, macOS, Linux, and R-devel validation.
* Added a paper-only synthetic showcase source folder outside the R package build.
* Updated README citation and validation information.

# gp3tools 1.0.0.9000

## Development version

- Added a public synthetic-realistic Gazepoint export dataset under `inst/extdata/gazepoint_realistic_demo_exports/`.
- Added the reproducible generator script `data-raw/create_gazepoint_realistic_demo_exports.R`.
- The synthetic demo mimics Gazepoint Analysis all-gaze/fixation export structure without including real participant rows.

# gp3tools 1.0.0

## New features

* Added `run_gazepoint_workflow()` for one-command Gazepoint folder analysis.

* Added folder-level import with `read_gazepoint_folder()`.

* Added `check_gazepoint_file_pairs()` for checking whether Gazepoint all-gaze and fixation export files are correctly paired.

* Added `flag_tracking_quality()` for identifying recordings requiring review.

* Added diagnostic plotting functions:

  * `plot_tracking_quality()`
  * `plot_sampling_rate()`

* Added `save_gazepoint_plots()` for automatic diagnostic plot export.

* Added `create_gazepoint_report()` for lightweight HTML diagnostic reports.

* Integrated optional HTML report creation into `run_gazepoint_workflow()` with `create_report = TRUE`.

* Added standard CSV export helpers:

  * `export_gazepoint_tables()`
  * `write_gazepoint_outputs()`

* Added `summarise_gazepoint_workflow()` for creating a compact one-row summary of a completed workflow result object.

## Master-table tools

* Added `as_gazepoint_master()` for converting Gazepoint all-gaze exports into a standard sample-level master table with time, gaze coordinates, pupil values, validity flags, missingness flags, off-screen gaze flags, AOI state, event labels, and fixation-related fields.
* Added `create_gazepoint_master()` as the advanced Gazepoint master-table constructor for creating analysis-ready sample-level data with participant, media, timing, gaze, pupil, AOI, screen, event, response, and metadata fields.
* Added `audit_gazepoint_master()` for producing compact quality-audit tables from Gazepoint master tables, including overview, subject-level, media-level, AOI-state, pupil, and coordinate summaries.
* Added `validate_gazepoint_master()` as a formal validation gate before pupil preprocessing, AOI modelling, or advanced statistical analysis.
* Added `export_gazepoint_master_audit()` for exporting the master table, audit tables, and validation tables to CSV files.

## Pupil preprocessing tools

* Added `summarise_gazepoint_pupil()` as the first pupil-preprocessing gate for Gazepoint master tables. The function summarises pupil availability, missing-pupil percentages, valid-pupil percentages, pupil distributions, plausible-value checks, and IQR-based outlier counts by subject, media, subject-by-media, or overall.
* Added `flag_gazepoint_pupil()` for marking missing, non-finite, implausible, and IQR-outlying pupil samples in Gazepoint master tables. The function preserves the original master table, adds explicit pupil-quality flags, records the selected pupil/time columns and plausible-value thresholds, and creates `pupil_for_preprocessing`, where invalid pupil samples are set to `NA` before interpolation, filtering, or baseline correction.
* Added `create_gazepoint_preprocessing_registry()` for storing reusable preprocessing parameters, including blink/artifact padding, interpolation gap thresholds, smoothing window size, baseline windows, physiological pupil thresholds, speed-outlier thresholds, binocular-disagreement thresholds, baseline-quality thresholds, and overlap-risk settings.
* Added `flag_gazepoint_pupil_artifacts()` for conservative pupil artifact cleaning before interpolation. The function flags blink/trackloss contamination, missing pupil samples, non-finite and non-positive values, pupil-speed outliers, binocular left-right pupil disagreement, and temporal padding around bad samples. It also includes a scale-safety rule that suppresses millimetre-based physiological thresholds when they would remove nearly all non-missing samples, which protects Gazepoint raw-unit exports from being silently erased.
* Added `interpolate_gazepoint_pupil()` for linearly interpolating short internal gaps in pupil time series. The function automatically prefers `pupil_clean` when available, followed by `pupil_for_preprocessing`, preserves leading/trailing gaps, avoids long gaps, respects grouping by subject/media/trial, records interpolation status, gap size, gap duration, and produces `pupil_interpolated` for later filtering or baseline correction.
* Added `baseline_correct_gazepoint_pupil()` for flexible baseline correction of Gazepoint pupil data after flagging and interpolation. The function supports window-based baselines such as `c(-200, 0)` or `c(0, 200)`, as well as user-defined logical baseline/pre-stimulus flag columns. It produces absolute baseline-corrected values, percent change, ratio, z-scored baseline correction, baseline availability flags, baseline sample counts, and baseline-status labels.
* Added `smooth_gazepoint_pupil()` for sample-based rolling smoothing of Gazepoint pupil time series after interpolation and optional baseline correction. The function supports mean or median smoothing, centred/right/left-aligned windows, custom grouping by subject/media/trial or other columns, optional preservation of missing input rows, and records smoothing status, window size, input column, method, alignment, and minimum valid-points settings.
* Added `summarise_gazepoint_pupil_windows()` for aggregating processed Gazepoint pupil data into user-defined analysis windows. The function supports numeric window breakpoints and labelled custom window tables, flexible grouping by subject, media, trial, condition, AOI, or other columns, and produces analysis-ready summaries including valid/missing pupil counts, percentages, mean, median, SD, quantiles, min/max, AUC, time span, and window-validity status.

## Pupil preprocessing audit and sensitivity tools

* Added `audit_gazepoint_pupil_gaps()` for summarising pupil interpolation and missing-gap structure after `interpolate_gazepoint_pupil()`.
* Added `audit_gazepoint_pupil_baseline()` for checking baseline-correction quality after `baseline_correct_gazepoint_pupil()`.
* Added `audit_gazepoint_pupil_imbalance()` for checking whether preprocessing loss differs across conditions or other groups.
* Added `audit_gazepoint_pupil_drift()` for assessing tonic pupil/time-on-task drift.
* Added `audit_gazepoint_pupil_overlap_risk()` as an event-response overlap and deconvolution-readiness gate.

## Pupil feature summaries and plotting tools

* Added `summarise_gazepoint_pupil_trial_features()` for converting processed pupil time series into trial-level feature summaries.
* Added `plot_gazepoint_pupil_status()` for visualising observed, interpolated, missing, artifact, and other pupil-sample statuses over time or as grouped percentages.
* Added `plot_gazepoint_pupil_timecourse()` for plotting binned pupil time courses with mean lines and confidence bands.
* Added `plot_gazepoint_pupil_preprocessing()` for single-trial visual audit plots of pupil preprocessing stages.

## Pupil confirmatory window modelling tools

* Added `prepare_gazepoint_pupil_window_model_data()` for preparing pupil-window summaries or pupil trial-feature tables for confirmatory window-level modelling. The function standardises outcome, subject, condition, window, trial/media identifiers, valid-sample counts, total-sample counts, valid-sample proportions, weights, model-readiness status, and settings. It also supports common Gazepoint pupil-window aliases such as `media_id`, `MEDIA_ID`, `n_valid_pupil`, `n_valid_samples`, and `n_samples`.
* Added `fit_gazepoint_pupil_window_lmm()` for fitting confirmatory pupil-window linear mixed models with `lme4::lmer()`. The function supports condition, window, and condition-by-window fixed effects when available; automatic fallback for single-condition or single-window data; subject random intercepts; optional random window slopes; optional valid-sample weighting; singular-fit detection; fallback models; fixed-effect tables; model-comparison tables; fitted formulas; status labels; and settings.
* Added `fit_gazepoint_pupil_window_sensitivity()` for confirmatory pupil-window model-family sensitivity checks. The function compares unweighted LMMs, weighted LMMs, fixed-effects LMs, and weighted LMs without adding heavy robust-model dependencies, and returns fitted models, formulas, comparison tables, fixed-effect tables, model-status labels, error messages, and settings.

## AOI, fixation, and transition feature tools

* Added `summarise_gazepoint_aoi_entries()` for converting sample-level AOI states into ordered AOI-entry episodes.
* Added `prepare_gazepoint_aoi_sequences()` for creating transition-ready AOI sequences from sample-level data or AOI-entry tables.
* Added `summarise_gazepoint_aoi_transitions()` for trial-level AOI transition summaries.
* Added `compute_gazepoint_aoi_transition_matrix()` for producing AOI transition count matrices, probability matrices, grouped matrices, and long-form transition tables.
* Added `plot_gazepoint_aoi_transition_matrix()` for plotting AOI transition count or probability heatmaps.
* Added `summarise_gazepoint_aoi_trial_features()` for trial-level AOI feature extraction.
* Added `summarise_gazepoint_fixation_trials()` for trial-level fixation feature extraction from Gazepoint fixation exports.

## AOI-window modelling tools

* Added `summarise_gazepoint_aoi_windows()` for converting sample-level AOI states into predefined AOI time-window summaries. The function supports numeric window breakpoints, labelled window tables, target/distractor AOI definitions, valid/all/AOI-only denominators, condition fallback to `all_data`, chronological window ordering, and status labels for target-observed and target-not-observed windows.
* Added `audit_gazepoint_aoi_window_denominators()` for checking denominator adequacy before binomial or logistic mixed-effects modelling. The function reports zero, low, missing, imbalanced, and variable denominators by row, window, and condition, and returns overview, row-audit, window-summary, condition-window, imbalance, and flagged-row tables.
* Added `prepare_gazepoint_aoi_glmm_data()` for preparing AOI-window summaries as binomial success/failure data. The function supports valid, all-sample, AOI-only, and custom denominators; creates success, failure, denominator, proportion, weight, subject, condition, and window columns; and records row-level GLMM-readiness status.
* Added `fit_gazepoint_aoi_window_glmm()` for fitting confirmatory AOI-window binomial mixed-effects logistic regression models using `lme4::glmer()`. The function supports condition, window, and condition-by-window fixed effects, subject random intercepts, optional random window slopes, singular-fit detection, fallback models, model comparison tables, and explicit model-status reporting.
* Added `fit_gazepoint_aoi_model_sensitivity()` for AOI-window model-family sensitivity checks. The function compares the main binomial GLMM against empirical-logit LMM, weighted proportion LMM, and fixed-effects quasibinomial GLM specifications, returning model comparisons, formulas, fixed effects, status labels, and settings.

## Time-course modelling helpers

* Added `prepare_gazepoint_pupil_gamm_data()` for preparing binned pupil time-course data for `mgcv::bam()` models.
* Added `fit_gazepoint_pupil_gamm()` for fitting pupil time-course GAMMs with `mgcv::bam()`.
* Added `fit_gazepoint_pupil_pfe_gamm()` for gaze-position-adjusted pupil GAMM sensitivity analysis.
* Added `prepare_gazepoint_gca_data()` for Growth Curve Analysis preparation.
* Added `fit_gazepoint_gca()` for fitting GCA mixed models with `lme4::lmer()`.
* Added `plot_gazepoint_gca()` for plotting observed and fitted GCA trajectories.

## Cluster-based permutation testing tools

* Added `prepare_gazepoint_cluster_data()` for preparing sample-level or binned Gazepoint time-course data for cluster-based permutation testing. The function standardises subject, condition, time-bin, outcome, sample-count, trial-count, status, outcome-label, aggregation, bin-size, paired-design, and condition-status fields. It supports pupil time courses, AOI target-looking indicators, and other numeric or logical time-course outcomes.
* Added `run_gazepoint_cluster_permutation()` for paired within-subject cluster-based permutation testing of two-condition time-course divergence. The function uses sign-flip permutations, time-wise paired t-statistics, configurable cluster-forming thresholds, two-sided or directional tests, multiple cluster-statistic options, complete-subject filtering, permutation maximum-cluster distributions, cluster-level p-values, model-status labels, and explicit circularity warnings.
* Added `summarise_gazepoint_clusters()` for converting cluster-permutation results into compact reporting tables, including overview, all observed clusters, significant clusters, time-course summary, permutation-distribution summary, settings, and circularity warning tables.
* Added `plot_gazepoint_cluster_results()` for plotting cluster-permutation results. The function supports mean-difference, test-statistic, or two-panel plots; optional cluster shading; candidate-bin markers; threshold lines; zero-reference lines; custom titles and labels; and publication-ready `ggplot2` output.
* The cluster-based permutation branch is intended for time-course inference and explicitly warns against using the detected cluster to define a confirmatory window and then retesting that same window in a second confirmatory model.

## AOI time-course GAMM tools

* Added `prepare_gazepoint_aoi_gamm_data()` for preparing sample-level or binned AOI data for AOI time-course GAMM analysis. The function creates subject-by-condition-by-time-bin binomial success/failure summaries for target-AOI looking, supports AOI-column and logical/numeric indicator workflows, valid/all/AOI-only denominator definitions, condition fallback to `all_data`, custom time bins, denominator filtering, and model-readiness status fields.
* Added `fit_gazepoint_aoi_gamm()` for fitting binomial AOI target-looking GAMMs using `mgcv::bam()`. The function models target-AOI looking over time using success/failure counts, supports condition fixed effects when available, condition-specific smooths, subject random-effect smooths, optional subject-specific time smooths, automatic single-condition fallback, model diagnostics, formula reporting, parametric and smooth tables, and captured model warnings.
* Added `plot_gazepoint_aoi_gamm()` for plotting observed AOI target-looking proportions and fitted AOI-GAMM trajectories. The function supports single-condition and multi-condition plots, observed-only and fitted-only views, confidence ribbons, population-level predictions with subject random effects excluded by default, custom labels, and publication-ready `ggplot2` output.
* The AOI time-course GAMM branch is intended for modelling smooth target-looking trajectories over time and is separate from confirmatory AOI-window GLMMs and cluster-based permutation tests.

## Model diagnostics tools

* Added `check_gazepoint_model_convergence()` for compact convergence diagnostics across fitted models used in `gp3tools` workflows. The helper supports `lme4` mixed models, `mgcv` GAM/BAM objects, `glm` objects, and ordinary `lm` objects where applicable, and returns a tidy diagnostic table with convergence status, model class, diagnostic status, and message.
* Added `check_gazepoint_model_singularity()` for checking singular random-effects structures in `lme4` mixed models using `lme4::isSingular()`. The helper reports singular fits as structured diagnostic output rather than package failures, and returns `not_applicable` for model classes where singularity is not meaningful.
* Added `check_gazepoint_model_overdispersion()` for Pearson-residual overdispersion diagnostics in binomial, quasibinomial, Poisson, quasipoisson, and negative-binomial-like models. The helper returns dispersion ratios, Pearson chi-square values, residual degrees of freedom, threshold-based overdispersion flags, and diagnostic messages.
* Added `diagnose_gazepoint_glmm()` as a reusable diagnostics bundle for GLMM, LMM, and GLM workflows. The function combines convergence, singularity, overdispersion, and optional DHARMa simulation-based residual diagnostics into a structured `gp3_model_diagnostics` object with overview, convergence, singularity, overdispersion, DHARMa, and settings tables.
* Added `diagnose_gazepoint_gamm()` as a reusable diagnostics bundle for `mgcv::gam()` and `mgcv::bam()` workflows. The function combines convergence checks, `mgcv::k.check()` basis-dimension diagnostics, overdispersion checks when meaningful, and optional DHARMa diagnostics into a structured `gp3_model_diagnostics` object.
* Added optional DHARMa support for model diagnostics. `DHARMa` is listed in `Suggests`, not `Imports`, and diagnostics skip cleanly with `skipped_missing_package` when DHARMa is not installed.

## Manuscript-ready model table tools

* Added `summarise_gazepoint_fixed_effects()` for creating manuscript-ready fixed-effect summary tables from `lm`, `glm`, `lme4` mixed models, and `mgcv` GAM/BAM models. The function supports `gp3tools` fit objects containing a `$model` element, Wald confidence intervals, optional exponentiation for odds ratios or rate ratios, intercept filtering, significance stars, and structured diagnostic status fields.
* Added `tidy_gazepoint_model_summary()` for combining model metadata, fixed-effect summaries, and optional model diagnostics into a structured `gp3_model_summary` object. The returned object contains `overview`, `model_info`, `fixed_effects`, `diagnostics`, and `settings` components.
* Added `summarise_gazepoint_emmeans()` for estimated marginal means and pairwise contrasts using optional `emmeans`. The function returns structured `overview`, `emmeans`, `contrasts`, and `settings` tables and skips cleanly with `skipped_missing_package` if `emmeans` is not installed.
* Added `export_gazepoint_model_tables()` for exporting manuscript-ready model summaries, fixed effects, diagnostics, estimated marginal means, contrasts, settings, and export-index tables to CSV files.
* Added optional `emmeans` support in `Suggests` for estimated marginal means and pairwise contrasts without making it a required package dependency.

## Final analysis-decision audit tools

* Added `create_gazepoint_analysis_decision_audit()` for creating a final analysis-decision audit across completed Gazepoint analysis branches. The function records which branches were run, classifies each branch as confirmatory, sensitivity, exploratory, diagnostic, preprocessing, reporting, or unknown, summarises available diagnostics, flags interpretation cautions, and creates a final analysis-readiness table.
* The audit returns a structured `gp3_analysis_decision_audit` object with `overview`, `branch_audit`, `diagnostics_summary`, `interpretation_cautions`, `readiness`, and `settings` components.
* Added support for required confirmatory branches, optional clean-diagnostics requirements, missing-branch detection, fallback-model cautions, singular-fit cautions, exploratory-analysis cautions, and sensitivity-analysis cautions.
* The final analysis-decision audit is intended as the last reporting gate after confirmatory models, sensitivity analyses, exploratory time-course analyses, diagnostics, and manuscript-ready model tables have been created.

## Preprocessing multiverse / sensitivity-check tools

* Added `create_gazepoint_preprocessing_multiverse()` for defining preprocessing multiverse specifications across pupil and AOI workflows. The function creates structured pupil, AOI, and combined branch grids for alternative preprocessing decisions such as pupil interpolation gap thresholds, smoothing windows, baseline windows, artifact-padding settings, AOI denominator definitions, and minimum denominator thresholds.
* Added `run_gazepoint_pupil_multiverse()` for running pupil preprocessing branches from a preprocessing multiverse object. The runner applies branch-specific artifact flagging, interpolation, baseline correction, smoothing, and optional pupil-window summarisation, while recording completed and failed branches.
* Added `run_gazepoint_aoi_multiverse()` for running AOI preprocessing branches from a preprocessing multiverse object. The runner creates AOI-window summaries and branch-specific AOI GLMM preparation tables using alternative denominator and minimum-denominator decisions.
* Added `summarise_gazepoint_multiverse_results()` for combining pupil and AOI multiverse results into overview, branch-summary, failure-summary, and settings tables.
* Added `plot_gazepoint_multiverse_results()` for visualising multiverse branch status, retained rows, pupil preprocessing settings, and AOI denominator settings.
* The preprocessing multiverse branch is intended for transparent sensitivity analysis across reasonable preprocessing choices, not for selecting the most favourable result.

## General publication-level audit helpers

* Added `audit_gazepoint_event_sync()` for checking event-marker availability, expected event labels, duplicate timestamps, sparse units, and unusually large time gaps.
* Added `audit_gazepoint_design_balance()` for auditing observed subject-by-condition design balance before exclusions.
* Added `audit_gazepoint_exclusion_flow()` for summarising retained versus excluded analysis units, exclusion reasons, condition-level retention, and subject-level retention.
* Added `audit_gazepoint_gaze_signal_quality()` for auditing gaze-coordinate availability, validity columns, missing gaze, off-screen gaze, and optional pupil availability.
* Added `audit_gazepoint_condition_quality_imbalance()` for checking whether quality metrics differ across experimental conditions.
* Added `audit_gazepoint_post_exclusion_balance()` for checking whether retained analysis units remain balanced across subjects and conditions after exclusions.
* The general audit branch is intended as a publication-readiness layer before confirmatory modelling, sensitivity analysis, and final interpretation.

## AOI geometry and verification tools

* Added `audit_gazepoint_aoi_geometry()` for checking AOI size, area, coordinate validity, screen-bound status, and duplicate AOI geometry.
* Added `audit_gazepoint_aoi_overlap()` for identifying pairwise AOI overlap within each stimulus or media item.
* Added `audit_gazepoint_aoi_margin_sensitivity()` for auditing whether AOI assignments are sensitive to small boundary expansions or shrinkages.
* Added `audit_gazepoint_aoi_coding_matrix()` for validating observed AOI labels against geometry-derived AOI labels and producing coding/confusion matrices.
* Added `plot_gazepoint_aoi_verification()` for visual AOI verification with optional gaze-point overlays.
* The AOI geometry and verification layer supports publication-readiness checks before AOI-window modelling, transition analysis, and confirmatory AOI interpretation.

## Advanced sequence-model adapters

* Added advanced AOI/state sequence-model preparation helpers:

  * `create_gazepoint_markovchain_object()`
  * `prepare_gazepoint_semimarkov_data()`
  * `prepare_gazepoint_hmm_data()`

* Added `create_gazepoint_markovchain_object()` for creating dependency-free Markov-chain-style AOI/state objects with transition counts, transition probabilities, transition matrices, sequence-level transition data, state ordering, optional state exclusion, optional missing-state labelling, optional self-transition handling, and Laplace smoothing.

* Added `prepare_gazepoint_semimarkov_data()` for converting ordered AOI/state observations into semi-Markov-ready state-visit and transition tables with dwell durations, next-state labels, terminal-state handling, sequence summaries, state summaries, transition summaries, optional covariate carry-through, and optional repeated-state collapsing.

* Added `prepare_gazepoint_hmm_data()` for creating dependency-free HMM-ready AOI/state sequence structures with ordered observation data, initial-state probabilities, transition count/probability matrices, transition tables, observation summaries, emission-format data, optional numeric observation scaling, optional terminal-state transitions, optional covariate carry-through, and optional missing-state labelling.

## Package-adapter export layer

* Added dependency-free package-adapter helpers for exporting `gp3tools` master/sample tables to external R eye-tracking workflows:

  * `prepare_gazepoint_eyetrackingr_data()`
  * `prepare_gazepoint_pupillometryr_data()`
  * `prepare_gazepoint_gazer_data()`
  * `prepare_gazepoint_eyetools_data()`

* These helpers create clean, package-friendly tibbles without importing or depending on the external packages directly.

* Added eyetrackingR-style sample-level export with participant, trial, time, gaze coordinates, AOI labels, AOI indicator columns, trackloss status, and adapter metadata.

* Added pupillometryR-style sample-level export with participant, trial, time, pupil, event, baseline, pupil-validity, trackloss, and adapter metadata.

* Added gazer-style sample-level export with participant, trial, time, gaze coordinates, optional pupil, AOI labels, fixation IDs, validity flags, off-screen detection, trackloss status, and adapter metadata.

* Added eyetools-style sample-level export with participant, trial, time, primary and binocular gaze coordinates, pupil columns, AOI labels, fixation IDs, event labels, validity flags, off-screen detection, trackloss status, and adapter metadata.

## Advanced sensitivity, recalibration, and reporting helpers

* Added `estimate_gazepoint_divergence_point()` for estimating the earliest reliable divergence between two condition time courses using bootstrap confidence intervals. The helper supports participant-, trial-, and row-level bootstrap units, mean or median summaries, directional testing, consecutive-point onset rules, no-divergence handling, optional bootstrap-output retention, and onset-time uncertainty summaries.

* Added `run_gazepoint_model_leave_one_out()` for generic leave-one-unit model sensitivity analysis. The helper refits a user-supplied model while leaving out one participant, item, stimulus, trial, or other unit at a time. It supports custom effect extraction, effect-term filtering, fit/extraction error tracking, optional model retention, and effect-stability summaries including maximum absolute change, largest-change unit, percent change, and sign-flip detection.

* Added `transform_gazepoint_aoi_empirical_logit()` for transforming bounded AOI proportions into finite empirical logits. The helper supports numerator/denominator count input, proportion-only input with pseudo-denominators, correction constants for 0/1 proportions, custom output columns, overwrite protection, row-level transformation statuses, and overview/status/settings attributes.

* Added `prepare_gazepoint_fixation_aligned_data()` for fixation-, saccade-, and AOI-contingent alignment. The helper aligns observations to first target entry, first fixation to target, first saccade to AOI, first fixation, or custom event markers, and returns aligned data, event tables, trial summaries, baseline/analysis-window flags, pre/post-event phases, target-preexisting flags, and already-on-target-at-start indicators.

* Added `plot_gazepoint_model_predictions()` for plotting observed summaries together with model-implied prediction trajectories. The helper supports model objects for which `predict()` works, including `lm`, `glm`, mixed-model, GAMM, and GCA-style workflows, and stores observed summaries, prediction summaries, overview metadata, and settings as plot attributes.

* Added `compare_gazepoint_nested_models()` for comparing ordered nested models. The helper returns model-level AIC, BIC, log-likelihood, degrees of freedom, likelihood-ratio tests, model rankings, sequential or against-first comparisons, extraction/comparison statuses, and fallback support for simple custom list-like model wrappers.

* Added `flag_gazepoint_pupil_hampel()` as an optional Hampel-filter pupil artifact helper. The function applies a rolling Hampel filter to pupil data, supports grouping and time ordering, configurable window size, threshold multiplier, minimum valid samples, MAD scaling, optional corrected pupil output, custom output columns, overwrite protection, row-level statuses, and overview/status/settings attributes.

* Added `recalibrate_gazepoint_gaze()` for offline gaze recalibration and drift correction using known target or check-target coordinates. The helper estimates group-level horizontal and vertical gaze shifts, applies median or mean drift correction, supports calibration-row filters, maximum-shift blocking, grouped correction summaries, row-level statuses, before/after target-error columns, custom output columns, and overview/status/settings attributes.

* Added `recommend_gazepoint_exclusions()` for creating explicit trial-level and participant-level exclusion recommendations. The helper uses validity flags, gaze-coordinate missingness, pupil missingness, artifact flags, sample-count thresholds, missingness thresholds, and artifact-rate thresholds to return transparent participant recommendations, trial recommendations, a combined exclusion table, overview metadata, and settings. The helper recommends exclusions only; it does not remove data.

## Improvements

* Added a complete standalone model-diagnostics branch for convergence checks, singular-fit checks, overdispersion diagnostics, optional DHARMa residual diagnostics, and GAM/BAM basis-dimension checks.
* Added reusable model-diagnostics wrappers for GLMM/LMM/GLM models and GAM/BAM models, returning compact overview tables and component diagnostic tables that can later be integrated into existing modelling helpers.
* Added a complete manuscript-ready model-table branch for publication outputs, including fixed-effect summaries, model metadata, diagnostics summaries, estimated marginal means, pairwise contrasts, and CSV export helpers.
* Expanded the time-course and modelling layer to cover pupil GAMMs, gaze-position/PFE pupil sensitivity GAMMs, GCA mixed models, cluster-based permutation tests, AOI target-looking GAMMs, standalone GLMM/GAMM diagnostics, and manuscript-ready model tables.
* Added a complete AOI, fixation, and transition feature-extraction layer for Gazepoint workflows, covering AOI-entry episodes, AOI sequences, transition summaries, transition matrices, transition heatmaps, AOI trial features, and fixation trial features.
* Added a complete AOI-window modelling branch for confirmatory target/distractor AOI analyses using predefined time windows, denominator audits, binomial GLMM preparation, mixed-effects logistic regression, and model-family sensitivity checks.
* Added a complete confirmatory pupil-window modelling branch for predefined pupil windows, including model-data preparation, trial/window-level LMM fitting, optional valid-sample weighting, fixed-effects LM sensitivity checks, fallback handling for single-condition or single-window data, singular-fit reporting, model-comparison tables, and fixed-effect summaries.
* Added a complete cluster-based permutation testing branch for time-course divergence analysis, including cluster-data preparation, paired sign-flip permutation testing, cluster-level summaries, and publication-ready cluster-result plotting.
* Improved AOI-state handling by consistently distinguishing AOI, non-AOI/background, and missing AOI states across entry, sequence, transition, matrix, plotting, trial-feature, AOI-window modelling, and cluster-preparation functions.
* Improved support for target-versus-distractor AOI analysis, including target/distractor dwell, TTFF, revisits, fixation counts, fixation duration, transition direction, windowed target proportions, denominator checking, status labels when target or distractor AOIs are not observed, and AOI target-looking time-course preparation for cluster testing.
* Improved fixation-trial summarisation for Gazepoint fixation exports by automatically detecting common fixation columns such as `FPOGS`, `FPOGD`, `FPOGX`, `FPOGY`, `FPOGID`, `FPOGV`, `AOI`, `MEDIA_ID`, and informative participant identifiers such as `USER_FILE`.
* Added a modelling layer for pupil time-course analysis, including GAMM preparation, main pupil GAMMs, gaze-position/PFE sensitivity GAMMs, GCA preparation, GCA mixed models, GCA visualisation, and cluster-based time-course inference.
* Improved support for datasets without usable condition labels by using a consistent `all_data` fallback in pupil time-course preparation, GAMM modelling, GCA preparation, GCA plotting, AOI-window summaries, AOI GLMM preparation, AOI-window mixed modelling, pupil-window model-data preparation, pupil-window mixed modelling, and cluster-data preparation.
* Improved modelling diagnostics by returning explicit status fields, fallback indicators, model-comparison tables, fitted formulas, fixed-effect tables, error messages, model settings, permutation distributions, cluster-level p-values, and circularity warnings.
* Added tests for AOI entries, AOI sequences, AOI transition summaries, AOI transition matrices, AOI transition heatmaps, AOI trial features, fixation trial features, AOI-window summaries, AOI denominator audits, AOI GLMM preparation, AOI-window GLMM fitting, AOI model-family sensitivity, pupil GAMM preparation, pupil GAMM fitting, PFE-adjusted pupil GAMMs, GCA data preparation, GCA mixed-model fitting, GCA plotting, pupil-window model-data preparation, pupil-window LMM fitting, pupil-window model-family sensitivity, cluster-data preparation, cluster-based permutation testing, cluster-result summarisation, cluster-result plotting, AOI-GAMM data preparation, AOI-GAMM fitting, AOI-GAMM plotting, model convergence checks, singularity checks, overdispersion checks, GLMM diagnostics, GAMM diagnostics, fixed-effect summaries, tidy model summaries, estimated marginal means, and model-table exports.
* Added a complete final analysis-decision audit branch for recording completed analysis branches, distinguishing confirmatory, sensitivity, exploratory, diagnostic, preprocessing, and reporting outputs, summarising diagnostics, flagging interpretation cautions, and producing a final analysis-readiness decision table.
* Expanded the reporting layer to cover manuscript-ready fixed-effect tables, estimated marginal means, pairwise contrasts, model-table CSV exports, and final analysis-decision/readiness audits.
* Added tests for final analysis-decision auditing, including missing required confirmatory branches, confirmatory models without diagnostics, diagnostic warnings, clean-diagnostics requirements, fallback models, singular fits, invalid branch-role inputs, and named results-list workflows.
* Added a complete preprocessing multiverse branch for defining, running, summarising, and plotting pupil and AOI preprocessing sensitivity checks across alternative preprocessing decisions.
* Expanded the sensitivity layer beyond model-family sensitivity checks by supporting preprocessing-decision multiverses for pupil interpolation, smoothing, baseline windows, artifact padding, AOI denominator definitions, and minimum denominator thresholds.
* Added tests for preprocessing multiverse specification, pupil multiverse runners, AOI multiverse runners, multiverse summaries, and multiverse plots.
* Added a complete general publication-level audit branch for checking event synchronisation, design balance, exclusion flow, gaze-signal quality, condition-level quality imbalance, and post-exclusion retained-sample balance.
* Added a complete AOI geometry and verification branch for checking AOI geometry validity, AOI overlap, margin sensitivity, observed-versus-derived AOI coding consistency, and visual AOI verification.
* Added `check_gazepoint_real_data_readiness()`, an explicit final readiness gate for real-data analysis. The helper returns structured `overview`, `gate_decision`, `checks`, `detected_columns`, `data_summary`, `condition_summary`, and `settings` outputs, with pass/warn/fail readiness status.
* Added `run_gazepoint_eyetools_fixation_detection()`, an optional external-detector wrapper for `eyetools`. The wrapper prepares Gazepoint data using the expected `pID`, `trial`, `time`, `x`, and `y` schema, supports dispersion, VTI fixation, and VTI saccade branches, and records clean skipped, complete, partial-complete, and error statuses.
* Added `create_gazepoint_reporting_checklist()`, an auto-generated reporting checklist for manuscript/report preparation. It summarises reporting readiness across data structure, readiness gates, import/workflow checks, sampling/tracking quality, AOI reporting, pupil reporting, model diagnostics, sensitivity analyses, reproducibility, and optional advanced methods.
* Added `compute_gazepoint_time_varying_transition_matrix()`, a dedicated helper for transition-count and transition-probability matrices by time window and grouping variables.
* Added `fit_gazepoint_transition_count_nb_sensitivity()`, an optional negative-binomial transition-count sensitivity model using `glmmTMB` when available.
* Added `run_gazepoint_gazer_crosscheck()`, an optional external gazeR preprocessing cross-check wrapper.
* Added `audit_gazepoint_stimulus_luminance()`, `audit_gazepoint_pupil_reliability()`, and `interpolate_gazepoint_pupil_pchip()` for pupil-analysis robustness and reporting support.
* Added advanced validation tests for bootstrapped divergence-point analysis, leave-one-unit model sensitivity, fixation/saccade-contingent alignment, AOI empirical-logit transformation, model-prediction plotting, nested model comparison, Hampel pupil artifact detection, offline gaze recalibration, and explicit trial/participant exclusion recommendations.
* Resolved R CMD check notes caused by `.env` pronoun use in internal helper functions by replacing dplyr pronoun-based assignment with explicit local data-frame assignment.

## Current validation status

Recent focused validations completed successfully for the following advanced helpers:

```r
devtools::test(filter = "estimate_gazepoint_divergence_point")
# [ FAIL 0 | WARN 0 | SKIP 0 | PASS 95 ]

devtools::test(filter = "run_gazepoint_model_leave_one_out")
# [ FAIL 0 | WARN 0 | SKIP 0 | PASS 98 ]

devtools::test(filter = "prepare_gazepoint_fixation_aligned_data")
# [ FAIL 0 | WARN 0 | SKIP 0 | PASS 117 ]

devtools::test(filter = "transform_gazepoint_aoi_empirical_logit")
# [ FAIL 0 | WARN 0 | SKIP 0 | PASS 89 ]

devtools::test(filter = "plot_gazepoint_model_predictions")
# [ FAIL 0 | WARN 0 | SKIP 0 | PASS 83 ]

devtools::test(filter = "compare_gazepoint_nested_models")
# [ FAIL 0 | WARN 0 | SKIP 0 | PASS 95 ]

devtools::test(filter = "flag_gazepoint_pupil_hampel")
# [ FAIL 0 | WARN 0 | SKIP 0 | PASS 77 ]

devtools::test(filter = "recalibrate_gazepoint_gaze")
# [ FAIL 0 | WARN 0 | SKIP 0 | PASS 109 ]

devtools::test(filter = "recommend_gazepoint_exclusions")
# [ FAIL 0 | WARN 0 | SKIP 0 | PASS 89 ]
```

The current full-package validation status after the README, vignette, and example-data branches is:

```r
devtools::test()
# [ FAIL 0 | WARN 0 | SKIP 0 | PASS 6788 ]

devtools::check()
# 0 errors | 0 warnings | 0 notes
```

During full tests, `boundary (singular) fit: see help('isSingular')` messages may appear in mixed-model diagnostic contexts. These are expected diagnostic messages from singular-fit test fixtures and are not package failures when the final test summary reports `FAIL 0 | WARN 0`.

On some Windows systems, a Quarto/TMPDIR message may appear after `devtools::check()`. This is harmless when the final `R CMD check results` report:

```r
0 errors | 0 warnings | 0 notes
```

### Example datasets for runnable documentation

* Added lightweight built-in example datasets so README examples, vignettes, tests, and user workflows can run without private Gazepoint files:

  * `gazepoint_example_master`
  * `gazepoint_example_fixations`
  * `gazepoint_example_aoi_geometry`
  * `gazepoint_example_aoi_windows`
  * `gazepoint_example_pupil_windows`
* Added `data-raw/create_gazepoint_example_data.R` to regenerate the example datasets reproducibly.
* Added dataset documentation in `R/data.R`.
* Added focused tests for the example datasets and their compatibility with core master-table, pupil-window, AOI-window, and AOI-geometry workflows.
* Excluded `data-raw/` from the built package via `.Rbuildignore` to avoid R CMD check top-level file notes.
* Current validation after the example-data branch:

  * `devtools::test()` reports `FAIL 0 | WARN 0 | SKIP 0 | PASS 6788`.
  * `devtools::check()` reports `0 errors | 0 warnings | 0 notes`.


## Notes

* This version is intended as the first stable internal prototype for Gazepoint GP3 export workflows.
* The current final analysis-decision audit set is complete for recording completed branches, classifying analyses as confirmatory, sensitivity, exploratory, diagnostic, preprocessing, or reporting, summarising diagnostics, flagging interpretation cautions, and producing final readiness decisions.
* The current pupil preprocessing sensitivity/audit set is complete for interpolation gaps, baseline quality, preprocessing imbalance, drift, event-response overlap risk, split-half pupil reliability, PCHIP interpolation sensitivity, stimulus-luminance auditing, and optional Hampel-filter pupil artifact sensitivity.
* The current pupil feature and visual-diagnostics set is complete for trial-level feature extraction, preprocessing-status plots, condition/time-course plots, single-trial preprocessing audit plots, and model-implied prediction plots.
* The current pupil confirmatory window modelling set is complete for model-data preparation, confirmatory pupil-window LMM fitting, optional valid-sample weighting, fixed-effects LM sensitivity checks, fallback handling, singular-fit reporting, model-comparison tables, nested model comparisons, fixed-effect summaries, and leave-one-unit model sensitivity.
* The current AOI, fixation, and transition feature set is complete for AOI entries, AOI sequences, AOI transition summaries, AOI transition matrices, time-varying transition matrices, transition heatmaps, AOI trial-level features, fixation trial-level features, and fixation/saccade-contingent alignment.
* The current AOI-window modelling set is complete for window summaries, denominator audits, binomial GLMM preparation, AOI-window mixed-effects logistic regression, empirical-logit AOI transformation, AOI-window model-family sensitivity checks, and nested model-comparison support.
* The current cluster-based permutation testing set is complete for time-course cluster-data preparation, paired sign-flip cluster permutation testing, cluster-level result summaries, publication-ready cluster-result plotting, bootstrapped divergence-point estimation, and explicit circularity warnings about exploratory window selection.
* The current modelling helper set is complete for binned pupil-GAMM preparation, main pupil GAMMs, gaze-position/PFE sensitivity GAMMs, GCA data preparation, GCA mixed-model fitting, observed-versus-fitted GCA plots, general model-prediction plots, AOI-window GLMM modelling, AOI-window model-family sensitivity, confirmatory pupil-window LMMs, pupil-window model-family sensitivity, AOI time-course GAMMs, cluster-based time-course inference, standalone model diagnostics, nested model comparison, fixed-effect summaries, estimated marginal means, manuscript-ready model-table exports, and leave-one-unit sensitivity checks.
* The current AOI time-course GAMM set is complete for target-AOI time-course preparation, binomial GAMM fitting, single-condition fallback, condition-specific smooths, subject random-effect smooths, model diagnostics, and observed-versus-fitted AOI trajectory plots.
* The current standalone model-diagnostics set is complete for convergence checks, singular-fit checks, overdispersion checks, GLMM/LMM/GLM diagnostic bundles, GAM/BAM diagnostic bundles, optional DHARMa residual diagnostics, GAM basis-dimension checks, nested model comparison, and model-implied prediction visualisation.
* The current manuscript-ready model-table set is complete for fixed-effect summaries, tidy model-summary objects, estimated marginal means, pairwise contrasts, optional `emmeans` support, CSV export of model tables, model-implied prediction visualisation, and nested model-comparison reporting.
* The current AOI geometry and verification set is complete for AOI geometry validity checks, AOI overlap audits, AOI-margin sensitivity checks, observed-versus-derived AOI coding validation, and visual AOI verification plots.
* The current external cross-check and adapter set is complete for dependency-free exports to eyetrackingR-style, pupillometryR-style, gazer-style, and eyetools-style workflows, optional external gazeR preprocessing cross-checks, and optional external eyetools fixation/saccade detection wrappers.
* The current recalibration and exclusion-decision set is complete for offline gaze drift correction using known target/check-target coordinates and explicit trial/participant exclusion recommendation tables.
* Current full package status after the README, vignette, and example-data branches: `devtools::test()` passes with 6788 tests, and `devtools::check()` returns 0 errors, 0 warnings, and 0 notes.
