From gaze data to a defensible functional method¶
Choose the research question and observation structure before choosing a function. Published eyetrajectoriespy==1.2.0 provides stable module-scoped workflow routes for continuous, sparse and repeated-trial gaze, but a successful model fit is not proof of valid statistical inference.
1. What did the recorder actually observe?¶
For a long-format CSV, begin with the local structural readiness inspector. It reports possible grid and sampling problems before the statistical decisions below; its automated output does not establish that any method's assumptions hold.
| Data structure | Preserve | Recommended starting point |
|---|---|---|
| Common aligned x/y time grid | Coordinate and time units, observed gaps, participant and trial IDs | Continuous FPCA |
| Paired sparse x/y samples at shared times | Raw observation times, sample support per curve | Sparse planar MFPCA |
| x/y coordinates sampled at different times | Two coordinate-specific time vectors; no fabricated common grid | Irregular/asynchronous sampling |
| Multiple trials within each participant | The participant–trial hierarchy and covariate alignment | Repeated-trial functional mixed effects |
Do not silently replace missing gaze by zero, interpolate across long gaps or drop unsuccessful trials. Review the input schemas before converting data into functional objects.
2. What is your scientific question?¶
- What are the dominant modes of variation?
FPCA/MFPCA summarizes how x/y trajectories vary over time. Components are mathematical modes, not validated psychological constructs.
- How does a condition change gaze over time?
Functional regression estimates a specified time-varying association. Check whether each curve is independent or belongs to repeated trials.
- How do repeated participants or trials differ?
Preserve within-person clustering in estimation, prediction and reporting; do not treat repeated trials as independent people.
- Is recurrence or temporal organization the target?
Declare embedding, time delay, distance and recurrence threshold rather than tuning them after seeing the result.
3. What can the sample justify?¶
Before running an analysis, record the following five decisions:
- Independent unit: participant, curve or trial; number of independent units and repeats.
- Observed support: recording window, time units, channel-specific gaps, exclusions and missingness.
- Target: descriptive variability, prediction, functional coefficient, pointwise uncertainty or a whole-curve inference.
- Dependence: participant clustering, temporal autocorrelation and planar x/y covariance.
- Claim boundary: does the method's engineering qualification cover the operation, and is there independent evidence for the desired statistical claim?
The unresolved simultaneous band calibration issue #289 and outcome-dependent missing gaze issue #296 mean that no blanket W3 confidence-band or MNAR recovery guarantee should be inferred from the stable package release.
4. Try one reproducible supported workflow¶
python -m pip install "eyetrajectoriespy==1.2.0"
The three complete quick starts demonstrate dense planar FPCA, sparse planar MFPCA and function-on-scalar regression using seeded synthetic teaching data. They are not measured participant observations. For all ten W1–W4 route/configuration choices, use the workflow-selection guide.
Conceptual synthetic illustration, not evidence of estimator calibration or hardware performance.
5. Preserve interpretation and provenance¶
Report data source and permissions, package version, preprocessing and transformation decisions, participant/trial grouping, model specification, sensitivity analyses, diagnostics, warnings, failures and the precise inferential target. Use the reporting checklist, portable workflow bundles and scientific figure atlas to keep claims tied to their sources.
Start a complete example Public API stability Research boundaries