---
title: "Gazepoint and Gazepoint Biometrics Workflows"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Gazepoint and Gazepoint Biometrics Workflows}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r setup, include=FALSE}
knitr::opts_chunk$set(collapse = TRUE, comment = "#>", eval = FALSE)
```

Gazepoint is a first-class source while the downstream representation remains
vendor-neutral.

## Profile before import

```{r}
gp_profile_export("data/P001")
gp_audit_file_pairs("data/P001")
gp_list_export_fields("data/P001/P001-user.csv")
gp_validate_export("data/P001")
```

## Folder import

```{r}
x <- read_gazepoint_folder(
  "data/P001",
  include = c("gaze", "fixations", "events", "biometrics", "aoi"),
  participant_id = "P001"
)

x <- gp_reconstruct_trials(
  x,
  start_events = c("TRIAL_START", "START_TRIAL"),
  end_events = c("TRIAL_END", "END_TRIAL")
)

x <- gp_reconstruct_stimuli(x)
x <- gp_align_media_ids(x)
```

## Gazepoint-specific audits

```{r}
gp_check_sampling_rate(x)
gp_check_validity_fields(x)
gp_check_fixation_ids(x)
gp_check_media_timing(x)
gp_check_pupil_channels(x)
gp_check_biometrics_sync(x)
```

## Separate biometrics and synchronization

```{r}
gaze <- read_gazepoint_gaze("P001-user.csv")
bio  <- read_gazepoint_biometrics("P001-biometrics.csv")

# Marker times may be extracted from each object's event table.
source_markers <- bio$events$timestamp_seconds[bio$events$event_name == "SYNC"]
target_markers <- gaze$events$timestamp_seconds[gaze$events$event_name == "SYNC"]

x <- synchronize_eye_biometrics(
  gaze,
  bio,
  source_markers = source_markers,
  target_markers = target_markers,
  method = "linear"
)
```

Different native sampling rates and clocks are preserved. Alignment parameters
are recorded in provenance rather than hidden by automatic resampling.

## Gazepoint Analysis 7.2.0 paired exports

Gazepoint Analysis 7.2.0 may export files named `User 3_all_gaze.csv` and
`User 3_fixations.csv`, together with multi-section
`Data_Summary_export_*.csv` reports. The folder importer pairs these files by
their `User N` stem:

```{r eval=FALSE}
root <- "C:/path/to/gazepoint-export-folder"

gp_pair_exports(root)
x <- read_gazepoint_folder(root)
```

The sample export contains two clocks with different meanings. The
`TIMETICK(f=10000000)` field remains monotonic across the full recording and is
used to create zero-based `timestamp_seconds`. The `TIME(...)` field restarts
when the media item changes and is retained as `media_time_seconds`. Neither
clock is silently discarded.

Fixation identifiers restart for each media item in these exports. Therefore,
`eyeprocess` constructs canonical episode identifiers from the recording,
media, and source fixation identifier. The original identifier remains in
`source_fixation_id`.

```{r eval=FALSE}
summary <- read_gazepoint_summary(
  file.path(root, "Data_Summary_export_02-20-26-01.28.43.csv")
)
summary

aoi_data <- read_gazepoint_aoi_statistics(summary$path)
```

The Data Summary parser retains both its aggregate AOI table and its per-user
AOI statistics. Canonical AOI definitions and participant-AOI features are
created without inventing spatial geometry that is absent from the report.