Reporting and reproducibility¶
The minimum reporting bundle¶
Run a reviewable evidence bundle¶
From the repository root:
A successful run ends with JSON containing:
To retain the artifacts, choose an output directory.
Recorded sample data
Keep the bounded analysis input distinct from the study-design table and retain source/provenance information when adapting the example.
Condition and task structure
Export the participant-by-task design rather than reconstructing conditions from filenames, row order, or downstream summaries.
Signal activity and time resets
Retain machine-readable QC tables before event locking or feature construction so exclusions and timing assumptions remain inspectable.
TTL identity and alignment
Save the extracted TTL table, alignment overview, alignment event table, and event-relative sample rows instead of reporting only a window definition.
Event-locked summaries
Keep summary rows together with their event definitions, baseline/summary windows, recorded signal names, and grouping structure.
Figure, software and methods evidence
Export the shared timeline, software identity, reporting checklist, methods starting text, and an evidence manifest alongside derived tables.
The saved directory is designed to be inspected rather than merely archived. It includes the structured audit components rather than collapsing them into ambiguous files:
outputs/research-evidence/
├── study_design.csv
├── signal_activity_overview.csv
├── signal_activity_by_group.csv
├── time_reset_overview.csv
├── time_reset_segments.csv
├── time_reset_flags.csv
├── ttl_events.csv
├── alignment_overview.csv
├── alignment_events.csv
├── aligned_data.csv
├── eventlocked_summary.csv
├── eventlocked_samples.csv
├── analysis_checklist_overview.csv
├── software.json
├── methods_text.txt
├── evidence_manifest.json
└── research-evidence-bundle-01.png
How to review the bundle¶
| Artifact family | Question it should let you answer | Do not substitute |
|---|---|---|
| Design | Which participant/task/condition rows define the analysis context? | Filename or row-order inference |
| Signal activity | Which requested channels were active within each analysis group? | A single undocumented “quality passed” flag |
| Time-reset audit | Were resets, duplicate times, non-finite values, or segment boundaries visible? | A statement that timestamps were “checked” |
| TTL/event evidence | What marker changes were detected and where? | An undocumented event index |
| Alignment | Which rows entered each event-relative window and under which settings? | A claim of synchronization based only on successful code execution |
| Event-locked summaries | How were recorded channels summarized around explicit events? | A table detached from windows, events, and grouping |
| Software/reporting | Which software identity and reporting objects reproduce the run? | Package name without version or settings |
The example intentionally uses the bundled synthetic kiosk data. Before substituting a research export, first use Validate a new dataset, inspect the synthetic demo guide, and resolve clock assumptions with Timebase and alignment. The evidence bundle is a retention pattern, not a shortcut around modality-specific QC.
Capture software identity early¶
import platform
import gpbiometricspy as gp
software = {
"gpbiometricspy": gp.__version__,
"python": platform.python_version(),
}
If an optional backend contributes to the scientific result, record its version too. The public interoperability matrix tests supported floor/current combinations, but a manuscript should still state what the study actually used.
Retain QC as data¶
Do not reduce QC to “data were cleaned.” Keep the tables or objects that support each decision.
activity = gp.audit_gazepoint_signal_activity(
dat,
signal_cols=["GSR_US", "HR", "IBI", "LPMM"],
group_cols=["participant_id"],
)
resets = gp.audit_gazepoint_time_resets(
dat,
time_col="TIME",
group_cols=["participant_id"],
)
Both calls return structured audit objects. Retain their named tables—for example activity["overview"], activity["signal_by_group"], resets["overview"], resets["segment_summary"], and resets["row_flags"]—rather than treating the outer object as one flat table.
The exact QC functions depend on modality, but the reporting principle is stable: retain the evidence that justified inclusion, exclusion, interpolation, or model readiness.
Report transformations in scientific order¶
A methods section is easier to audit when it follows the order in which information was transformed:
- acquisition/export and source identity;
- schema standardisation;
- timebase and signal QC;
- preprocessing and artifact rules;
- event/AOI alignment;
- feature construction;
- statistical or predictive modelling;
- sensitivity checks;
- software and reproducibility information.
This order prevents downstream model details from obscuring earlier measurement assumptions.
What to report for modelling¶
For grouped or hierarchical models, state:
- outcome and predictor definitions;
- grouping factors and whether levels are crossed or nested;
- fixed effects;
- random-effect structure;
- distributional family;
- estimation/integration strategy where relevant;
- how unseen groups/items are handled;
- validation split unit;
- optimization/convergence diagnostics;
- uncertainty or the explicit absence of inferential intervals;
- sensitivity or known-truth validation used to bound claims.
For the Python-native method families, use the dedicated Methods pages rather than inferring semantics from class or function names.
Figures are evidence, not decoration¶
Keep the figures used for decisions, including failed or borderline checks when they affected the analysis. The documentation gallery is generated from package functions and provides examples of the kinds of diagnostics worth retaining.
Reproducibility checklist¶
- Raw inputs are immutable or checksummed.
- Schema/renaming decisions are recorded.
- Sampling and timebase evidence is retained.
- QC outputs and warnings are saved.
- Exclusions have machine-readable reasons.
- Preprocessing settings are explicit.
- Random seeds are fixed where stochastic procedures are used.
- Optional backend versions are recorded.
- Figures used for QC are generated from code.
- Model specification and prediction target are explicit.
- Scientific interpretation is narrower than or equal to what the design supports.
Where to go next¶
- Reporting and reproducibility workflow — frozen R-companion workflow.
- Private real-data smoke testing — validate private data without committing it.
- Citation and archival — package citation and software archive information.
- Validation & trust — parity and certification evidence.