Dynamic Architecture Experiment

Code for running and processing data from the Dynamic Architecture Experiment used in the initial validation of psychological monitoring signals.

This repository is being prepared as a reproducible research artifact. The current code preserves the original local experiment pipeline while adding a documented command-line interface and publication metadata.

The associated article describes patent-pending technology (U.S. Patent Application No. 19/227,299) owned by McClafferty Innovations, LLC. This repository is licensed under the PolyForm Noncommercial License 1.0.0. Commercial use and any rights beyond those expressly granted by that license require separate permission.

This repository contains the experimental presentation, data collection, synchronization, and subject-level data-processing pipeline. It does not contain the code used to estimate the reported models or implement the resulting real-time psychological monitoring system.

Repository Layout

• src/Lib/: experiment scripts, hardware capture, data-processing steps, and shared helpers.
• data/LatinSquare.csv: stimulus counterbalancing table.
• config/example.json: example local configuration for machine-specific paths.
• docs/reproducibility.md: setup notes, data boundaries, and validation checklist.
• docs/data_dictionary.md: expected input and derived output columns.
• docs/references.md: article, software, and stimulus references.
• Protocols/: experimenter and computer protocols for study execution.

Requirements

The pipeline depends on Python packages and external lab software/hardware:

• Python 3.10 or newer.
• PsychoPy for the experiment presentation script.
• OpenFace FeatureExtraction.exe for facial action-unit, gaze, and pose extraction.
• BIOPAC AcqKnowledge .acq files readable by bioread.
• A joystick supported by pygame, if collecting motivation/continuous response data.
• FilmStim stimulus videos stored outside version control in a local videos/ directory.

Install Python dependencies with:

python -m pip install -r requirements.txt

Configuration

Copy config/example.json to a local file, for example config/local.json, and edit machine-specific paths:

Copy-Item config/example.json config/local.json

The same file can be passed with --config, or exposed through DAE_CONFIG. Do not commit private local config files, raw participant recordings, or stimulus assets unless you have explicit redistribution rights.

If OpenFace is installed outside the default Windows path, set openface_executable in config/local.json to the full path of FeatureExtraction.exe.

Display, microphone, and webcam setup are described in docs/reproducibility.md.

Study execution protocols are available in Protocols/. The Markdown files are the reviewable publication copies; the Word documents are retained as original working documents.

Commands

Reprocess all available data for a subject: This reruns the subject-level preprocessing and data-assembly pipeline; it does not reproduce the statistical analyses or model estimation reported in the article.

python src/Lib/cli.py --config config/local.json reanalyze SUBJECT_ID

Run a single step:

python src/Lib/cli.py --config config/local.json openface-summary SUBJECT_ID
python src/Lib/cli.py --config config/local.json physio SUBJECT_ID
python src/Lib/cli.py --config config/local.json combine SUBJECT_ID

Run collection plus reanalysis on a configured lab machine:

python src/Lib/cli.py --config config/local.json collect SUBJECT_ID

Collection checks that the required videos are present before starting hardware capture. If videos are missing, run setup with video download first.

Download the required FilmStim videos into the configured videos/ directory:

python src/Lib/cli.py --config config/local.json setup --download-videos
python src/Lib/cli.py --config config/local.json setup-videos

By default this downloads the video IDs referenced by data/LatinSquare.csv plus the neutral video 49.mp4 from https://sites.uclouvain.be/ipsp/FilmStim/En/{id}.mp4. Existing files are left in place. Use setup --overwrite-videos, setup-videos --overwrite, or setup-videos --ids 3 49 56 for specific IDs.

Expected Subject Inputs

Each subject folder under subs/SUBJECT_ID/ is expected to contain:

• eyetrack.csv from OpenFace.
• joystick.csv from joystick capture.
• psychopy.csv from the PsychoPy task.
• A BIOPAC .acq recording in subs/ or a processed physio.csv in the subject folder.

The exact private/raw data are intentionally ignored by Git.

Notes

See docs/reproducibility.md for data boundaries, private-component exclusions, and the validation checklist. See docs/data_dictionary.md for expected file schemas. See docs/references.md for source references.

Citation

If you use this repository, cite the associated article:

McClafferty, S. R., & Friedman, B. H. (2026). A Dynamic Architecture Linking Autonomic Activity to Emotional Dimensions: Real-Time Estimation From Photoplethysmography. Psychophysiology. https://doi.org/10.1111/psyp.70359

Machine-readable citation metadata are available in CITATION.cff.