---
title: "Getting Started with eyeprocess"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Getting Started with eyeprocess}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

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

`eyeprocess` harmonizes heterogeneous eye-tracking, pupil, event, response, and
biometric streams without erasing their source semantics. The core object is a
relational `eye_dataset`, not a single wide data frame.

## Installation

For the CRAN release (**0.11.1**, published 28 September 2026):

```{r}
install.packages("eyeprocess")
```

The canonical CRAN record is <https://CRAN.R-project.org/package=eyeprocess> and
the package DOI is <https://doi.org/10.32614/CRAN.package.eyeprocess>.

The GitHub stable release is currently newer than CRAN. Install **v0.12.0**
explicitly when that release line is required:

```{r}
install.packages("remotes")
remotes::install_github("stefanosbalaskas/eyeprocess", ref = "v0.12.0")
```

For the current **0.12.0.9000** development branch:

```{r}
remotes::install_github("stefanosbalaskas/eyeprocess")
```

Always record the installed package version in reproducible reports with
`packageVersion("eyeprocess")`.

## Simulate a complete project

```{r}
library(eyeprocess)

x <- simulate_eye_dataset(n_person = 20, n_item = 8, seed = 42)
x
summary(x)
validate_eye_dataset(x)
provenance_manifest(x)
```

## Standard workflow

```{r}
spec <- preprocess_spec(
  gaze_filter = "median",
  pupil_interpolation = "linear",
  pupil_filter = "median",
  fixation_algorithm = "ivt"
)

x <- preprocess_eye(x, spec)
x <- build_aoi_visits(x)
x <- derive_all_features(x)

analysis_readiness(x)
feature_dictionary(x)
```

## Inspect and visualize

```{r}
trial <- x$intervals$trial_id[1]
plot_eye_overview(x)
plot_scanpath(x, trial_id = trial)
plot_pupil_timeseries(x, trial_id = trial)
plot_transition_matrix(x)
```

## Persist the canonical representation

```{r}
write_eye_dataset(x, "analysis/eye-dataset.rds")
export_canonical(x, "analysis/canonical-folder")
report_eye_dataset(x, "analysis/eyeprocess-report.md", include_plots = TRUE)
```