Skip to content

Commit 881a73b

Browse files
zh1pengzh1peng
committed
Refactor cookiecutter to paradigm-agnostic scaffold
1 parent 33754f5 commit 881a73b

14 files changed

Lines changed: 637 additions & 833 deletions

File tree

‎psyflow/templates/cookiecutter-psyflow/{{cookiecutter.project_name}}/README.md‎

Lines changed: 60 additions & 134 deletions
Original file line numberDiff line numberDiff line change
@@ -1,169 +1,95 @@
1-
# Monetary Incentive Delay (MID) Task
1+
# PsyFlow Task Template
22

33
| Field | Value |
44
|----------------------|------------------------------|
5-
| Name | Monetary Incentive Delay (MID) Task |
6-
| Version | main (1.0) |
7-
| URL / Repository |https://github.com/TaskBeacon/T000006-mid |
8-
| Short Description | A task measuring reward anticipation and feedback processing using adaptive timing |
9-
| Created By |Zhipeng Cao (zhipeng30@foxmail.com) |
10-
| Date Updated |2025/06/21 |
11-
| PsyFlow Version |0.1.0 |
12-
| PsychoPy Version |2025.1.1 |
13-
| Modality |Behavior/EEG |
14-
| Language | Chinese |
15-
5+
| Name | PsyFlow Task Template |
6+
| Version | main (0.1.0) |
7+
| URL / Repository | https://github.com/TaskBeacon/{{cookiecutter.project_name}} |
8+
| Short Description | Paradigm-agnostic scaffold for building a PsyFlow task from literature evidence |
9+
| Created By | Template Maintainer |
10+
| Date Updated | 2026-03-02 |
11+
| PsyFlow Version | 0.1.0 |
12+
| PsychoPy Version | 2025.1.1 |
13+
| Modality | Behavior |
14+
| Language | English |
1615

1716
## 1. Task Overview
1817

19-
The Monetary Incentive Delay (MID) Task is designed to assess reward processing and motivational control. Participants respond to brief target stimuli that follow cues indicating potential monetary gain, loss, or neutral outcomes. By analyzing reaction times and success rates, the task evaluates anticipatory and feedback-related cognitive processes. An adaptive timing algorithm adjusts target durations based on participant performance, maintaining consistent task difficulty.
18+
This repository is a generic PsyFlow task scaffold. It includes standardized mode wiring (human/qa/sim), config split, trigger plumbing, responder integration, and contract-ready reference artifacts.
19+
20+
The default trial logic is intentionally minimal and non-paradigm-specific. Replace condition generation, timing, scoring, and stimuli with task-specific logic grounded in references under `references/`.
2021

2122
## 2. Task Flow
2223

2324
### Block-Level Flow
2425

25-
| Step | Description |
26-
|----------------------------|-----------------------------------------------------------------------------|
27-
| Load Config | Load task configuration and subject form |
28-
| Collect Subject Info | Collect demographic/subject info using `SubInfo` form |
29-
| Setup Triggers | Initialize trigger sender using serial port (COM3) |
30-
| Initialize Window/Input | Create PsychoPy window and keyboard handler |
31-
| Load Stimuli | Load all stimuli via `StimBank`, convert instructions to voice, preload |
32-
| Setup Controller | Create adaptive controller from config |
33-
| Show Instructions | Present text and voice instruction before starting |
34-
| Loop Over Blocks | For each block: countdown, run 60 trials, compute and show block feedback |
35-
| Show Goodbye | Present final feedback with total score |
36-
| Save Data | Save all trial data to CSV |
37-
| Close | Close serial port and quit PsychoPy |
26+
| Step | Description |
27+
|---|---|
28+
| Load Config | Load selected mode config (`config.yaml`, `config_qa.yaml`, or sim config). |
29+
| Collect Subject Info | Collect participant info in human mode; inject deterministic IDs in qa/sim mode. |
30+
| Setup Runtime | Initialize triggers, window, keyboard, and stimuli bank. |
31+
| Show Instructions | Present configurable instruction stimuli. |
32+
| Run Blocks | Generate per-block conditions and execute `run_trial(...)` for each trial. |
33+
| Show Block Break | Present summary values from trial outputs (for example, accuracy and mean RT). |
34+
| Save Data | Write trial-level CSV outputs and settings JSON. |
35+
| Finalize | Emit end trigger, close trigger runtime, and quit PsychoPy. |
3836

3937
### Trial-Level Flow
4038

41-
| Step | Description |
42-
|---------------------|-----------------------------------------------------------------------------|
43-
| Cue | Show condition-specific cue (win/lose/neutral) with trigger |
44-
| Anticipation | Display fixation; allow response (early keypress logged) |
45-
| Target | Show target with adaptive duration; record response |
46-
| Pre-feedback Fixation | Display fixation before feedback |
47-
| Feedback | Present hit/miss feedback based on performance |
48-
| Adaptive Update | Update target duration based on hit/miss outcome |
39+
| Step | Description |
40+
|---|---|
41+
| Fixation | Show baseline fixation stimulus. |
42+
| Response Window | Show prompt stimulus, collect key response with timeout handling. |
43+
| Feedback | Show configurable feedback stimulus based on response presence. |
44+
| ITI | Show inter-trial fixation. |
4945

5046
### Controller Logic
5147

52-
| Feature | Description |
53-
|---------------------|-----------------------------------------------------------------------------|
54-
| Adaptive Duration | Target duration adjusts between 0.04 and 0.37 seconds |
55-
| Step Size | ±0.03 seconds |
56-
| Accuracy Target | 66% accuracy threshold |
57-
| Condition Specific | Tracks performance separately by condition (win/lose/neutral) |
58-
| Logging | Performance logs are printed to PsychoPy console |
48+
| Feature | Description |
49+
|---|---|
50+
| Condition Scheduling | Uses a generic controller to distribute conditions across a block. |
51+
| Determinism | Supports seed-driven scheduling for reproducible QA/sim runs. |
52+
| Extensibility | Replace `src/utils.py` with task-specific planners/adaptive controllers when needed. |
5953

6054
## 3. Configuration Summary
6155

6256
### a. Subject Info
6357

64-
| Field | Meaning |
65-
|-------------|----------------------------|
66-
| subject_id | Unique participant number (101�99, 3 digits) |
67-
| subname | Participant name (pinyin) |
68-
| age | Participant age (5�0) |
69-
| gender | Participant gender (Male/Female) |
58+
| Field | Meaning |
59+
|---|---|
60+
| `subject_id` | Numeric participant ID from subform or qa/sim context. |
7061

7162
### b. Window Settings
7263

73-
| Parameter | Value |
74-
|-----------------------|-------------|
75-
| size | [1920, 1080]|
76-
| units | deg |
77-
| screen | 1 |
78-
| bg_color | gray |
79-
| fullscreen | True |
80-
| monitor_width_cm | 60 |
81-
| monitor_distance_cm | 72 |
64+
| Parameter | Meaning |
65+
|---|---|
66+
| `window.size` | Window resolution in pixels. |
67+
| `window.units` | PsychoPy units used for stimulus placement. |
68+
| `window.bg_color` | Background color. |
69+
| `window.fullscreen` | Fullscreen mode toggle. |
8270

8371
### c. Stimuli
8472

85-
| Name | Type | Description |
86-
|--------------------------|-----------|-------------------------------------------------------|
87-
| fixation | text | Central cross "+" |
88-
| win_cue | circle | Magenta circle (reward) |
89-
| lose_cue | rect | Yellow square (punishment) |
90-
| neut_cue | triangle | Cyan triangle (neutral) |
91-
| win_target | circle | Black circle target |
92-
| lose_target | rect | Black square target |
93-
| neut_target | triangle | Black triangle target |
94-
| win_hit_feedback | textbox | “击�+10 分�(black text, SimHei) |
95-
| win_miss_feedback | textbox | “未击中 +0 分� |
96-
| lose_hit_feedback | textbox | “击�-0 分� |
97-
| lose_miss_feedback | textbox | “未击中 -10 分� |
98-
| neut_hit_feedback | textbox | “击�+0 分� |
99-
| neut_miss_feedback | textbox | “未击中 -0 分� |
100-
| instruction_text | textbox | Multi-line Chinese instructions (includes scoring rules) |
101-
| block_break | text | Inter-block message showing block, accuracy, and score |
102-
| good_bye | text | End screen showing final score |
73+
| Stimulus ID | Purpose |
74+
|---|---|
75+
| `instruction_text` | Entry instruction text. |
76+
| `fixation` | Baseline fixation symbol. |
77+
| `trial_prompt` | Response window prompt text. |
78+
| `feedback_hit` / `feedback_miss` | Response-dependent feedback messages. |
79+
| `block_break` | Inter-block summary message. |
80+
| `good_bye` | End-of-task summary message. |
10381

10482
### d. Timing
10583

106-
| Phase | Duration (s) |
107-
|------------------------|--------------------|
108-
| cue | 0.3 |
109-
| anticipation | random 1.0�.2 |
110-
| target | adaptive (0.04�.37)|
111-
| prefeedback fixation | random 0.6�.8 |
112-
| feedback | 1.0 |
113-
114-
### e. Triggers
115-
116-
| Event | Code |
117-
|--------------------------|-------|
118-
| exp_onset | 98 |
119-
| exp_end | 99 |
120-
| block_onset | 100 |
121-
| block_end | 101 |
122-
| win_cue_onset | 10 |
123-
| win_anti_onset | 11 |
124-
| win_target_onset | 12 |
125-
| win_hit_fb_onset | 13 |
126-
| win_miss_fb_onset | 14 |
127-
| win_key_press | 15 |
128-
| win_no_response | 16 |
129-
| lose_cue_onset | 20 |
130-
| lose_anti_onset | 21 |
131-
| lose_target_onset | 22 |
132-
| lose_hit_fb_onset | 23 |
133-
| lose_miss_fb_onset | 24 |
134-
| lose_key_press | 25 |
135-
| lose_no_response | 26 |
136-
| neut_cue_onset | 30 |
137-
| neut_anti_onset | 31 |
138-
| neut_target_onset | 32 |
139-
| neut_hit_fb_onset | 33 |
140-
| neut_miss_fb_onset | 34 |
141-
| neut_key_press | 35 |
142-
| neut_no_response | 36 |
143-
| fixation_onset | 1 |
144-
145-
### f. Adaptive Controller
146-
147-
| Parameter | Value |
148-
|--------------------|----------|
149-
| initial_duration | 0.2 |
150-
| min_duration | 0.04 |
151-
| max_duration | 0.37 |
152-
| step | 0.03 |
153-
| target_accuracy | 0.66 |
154-
| condition_specific | true |
84+
| Parameter | Meaning |
85+
|---|---|
86+
| `timing.fixation_duration` | Pre-response fixation duration. |
87+
| `timing.response_window_duration` | Response collection window duration. |
88+
| `timing.feedback_duration` | Feedback duration. |
89+
| `timing.iti_duration` | Inter-trial interval duration. |
15590

15691
## 4. Methods (for academic publication)
15792

158-
Participants performed a computerized Monetary Incentive Delay (MID) task to assess motivational processing under different reward contingencies. The task consisted of **3 blocks**, each comprising **60 trials**, totaling **180 trials**. Each trial began with a cue, a colored shape (circle, square, or triangle), signaling whether the trial was a reward, punishment, or neutral condition. Following a variable anticipation phase (1.0�.2 s), a black target appeared briefly. Participants were instructed to press the spacebar as quickly as possible upon target onset.
159-
160-
The target's presentation duration was controlled by an adaptive algorithm that updated the duration after each trial based on performance. Initial target duration was set to 0.2 s and was adjusted between 0.04 and 0.37 s using ±0.03 s increments to stabilize performance at a target accuracy of 66%, tracked separately by condition.
161-
162-
Feedback followed the target phase, based on whether participants responded within the target duration. “击中�(“hit� and “未击中�(“miss� messages were shown with point gain/loss specific to the cue type. After each block, a break screen summarized the participant's accuracy and cumulative score. The task began with audio-visual instructions and ended with a final message displaying total score.
163-
164-
## 5. References
165-
The task is originally developed by Knutson 2000:
166-
>Knutson, B., Westdorp, A., Kaiser, E., & Hommer, D. (2000). FMRI visualization of brain activity during a monetary incentive delay task. Neuroimage, 12(1), 20-27.
93+
Participants completed a computerized behavioral paradigm implemented in PsychoPy/PsyFlow. The runtime architecture supports human testing, QA replay, and simulation with shared task code. Trial flow and timing parameters are fully config-defined, and simulation context fields are attached per phase to support reproducible responder behavior and post-hoc auditing.
16794

168-
Here, we adopted the ABCD Study design of the task:
169-
>Casey, B. J., Cannonier, T., Conley, M. I., Cohen, A. O., Barch, D. M., Heitzeg, M. M., ... & Dale, A. M. (2018). The adolescent brain cognitive development (ABCD) study: imaging acquisition across 21 sites. Developmental cognitive neuroscience, 32, 43-54.
95+
For publication use, replace this template section with task-specific participant/sample details, condition definitions, timing values, scoring rules, and citation-grounded implementation rationale.

0 commit comments

Comments
 (0)