---
title: "Integrated Synthetic Gazepoint Research Workflow"
description: "A realistic cross-package handoff followed by governed participant-generalization validation."
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Integrated Synthetic Gazepoint Research Workflow}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r setup, include=FALSE}
knitr::opts_chunk$set(collapse = TRUE, comment = "#>")
options(gp3ml.reproducible_examples = TRUE)
library(gp3ml)
```

## Synthetic upstream outputs

This article represents prepared outputs from `gp3tools`, `gpbiometrics`, and
`gp3sequences`. The values are synthetic and shareable. The outcome is an
experimentally assigned condition; the workflow does not infer emotion,
stress, cognition, health, identity, intent, or another prohibited construct.

```{r bundle}
bundle <- simulate_gazepoint_research_handoffs(
  n_participants = 18L,
  n_stimuli = 4L,
  seed = 3401L
)
validation <- validate_gazepoint_research_bundle(bundle)
validation
plot(validation)
```

## Assemble the modelling handoff

```{r data}
combined <- validation$bundle
data <- as_gp3ml_data(combined)

predictors <- c(
  "valid_gaze_prop",
  "fixation_count",
  "mean_fixation_ms",
  "gaze_dispersion",
  "eda_valid_prop",
  "hr_valid_prop",
  "ibi_valid_prop",
  "sequence_length",
  "unique_state_count",
  "transition_rate"
)
```

## Declare task and provenance

```{r governance}
task <- declare_gazepoint_task(
  data = data,
  outcome = "assigned_condition",
  purpose = "Discriminate an experimentally assigned condition using predeclared observed non-sensitive Gazepoint-derived predictors",
  task_type = "classification",
  unit_id = "trial_id",
  participant_id = "participant_id",
  stimulus_id = "stimulus_id",
  generalization_target = "new_participants",
  positive = "B",
  observed_outcome = TRUE,
  sensitive_outcome = FALSE
)

manifest <- create_gazepoint_feature_manifest(
  features = predictors,
  scientific_source = c(
    rep("gp3tools prepared gaze/fixation summaries", 4L),
    rep("gpbiometrics prepared signal-quality summaries", 3L),
    rep("gp3sequences prepared sequence summaries", 3L)
  ),
  source_table = c(
    rep("gp3tools handoff", 4L),
    rep("gpbiometrics handoff", 3L),
    rep("gp3sequences handoff", 3L)
  ),
  transformation = "Prepared upstream summary passed through a validated interoperability handoff",
  availability_stage = "during_exposure",
  prediction_time_available = TRUE,
  outcome_derived = FALSE,
  post_outcome = FALSE,
  identifier = FALSE,
  preprocessing_scope = "none",
  fold_local_required = FALSE,
  reviewer_notes = "Synthetic shareable cross-package validation workflow."
)

validate_gazepoint_feature_manifest(manifest)
```

## Participant-grouped resampling

```{r folds}
folds <- create_gazepoint_group_folds(
  data = data,
  outcome = task$outcome,
  predictors = predictors,
  feature_manifest = manifest,
  generalization_target = task$generalization_target,
  participant_id = task$participant_id,
  trial_id = task$unit_id,
  stimulus_id = task$stimulus_id,
  v = 3L,
  repeats = 1L,
  seed = 3401L
)

validate_gazepoint_group_folds(folds)
audit_gazepoint_group_folds(folds)
```

## Repository-aware evaluation when available

```{r evaluation}
if ("evaluate_gazepoint_group_folds" %in% getNamespaceExports("gp3ml")) {
  evaluation <- evaluate_gazepoint_group_folds(
    folds,
    task,
    predictors,
    "glm",
    seed = 3401L
  )
  validate_gazepoint_resample_evaluation(evaluation)
  summarize_gazepoint_resample_performance(evaluation)
} else {
  diagnostics <- diagnose_gazepoint_group_folds(folds)
  validate_gazepoint_fold_diagnostics(diagnostics)
}
```

Any reported predictive metrics are row-level outcomes under a declared
participant-grouped assessment design. They are not participant-level
psychological measurements and do not support causal or latent-state claims.