inst/doc/integrated-research-workflow.R

In gp3ml: Governance-First Predictive Modelling for 'Gazepoint' Research

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

## ----bundle-------------------------------------------------------------------
bundle <- simulate_gazepoint_research_handoffs(
  n_participants = 18L,
  n_stimuli = 4L,
  seed = 3401L
)
validation <- validate_gazepoint_research_bundle(bundle)
validation
plot(validation)

## ----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"
)

## ----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)

## ----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)

## ----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)
}