Skip to content

Commit 8eebbfa

Browse files
zh1pengzh1peng
committed
Add two-armed bandit task to site indexes
1 parent bf01f85 commit 8eebbfa

File tree

6 files changed

+537
-2
lines changed

6 files changed

+537
-2
lines changed

‎public/psyflow-web/task-manifest.json‎

Lines changed: 16 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
{
22
"schema_version": 1,
3-
"generated_at": "2026-04-03T13:05:44.2838962Z",
3+
"generated_at": "2026-04-03T15:13:08.7191831Z",
44
"org": "TaskBeacon",
55
"runner_repo": "psyflow-web",
66
"runner_url": "https://taskbeacon.github.io/psyflow-web/",
@@ -34,6 +34,21 @@
3434
"download_url": "https://github.com/TaskBeacon/H000037-game-of-dice/archive/refs/heads/main.zip",
3535
"run_url": "https://taskbeacon.github.io/psyflow-web/?task=H000037-game-of-dice",
3636
"last_updated": "2026-04-03T13:05:44Z"
37+
},
38+
{
39+
"directory": "H000038-two-armed-bandit",
40+
"id": "H000038",
41+
"slug": "two-armed-bandit",
42+
"title": "Two-Armed Bandit Task",
43+
"acquisition": "behavior",
44+
"maturity": "prototype",
45+
"release_tag": "v0.2.3-dev",
46+
"short_description": "Browser preview of the two-choice probabilistic reward learning task with block-wise contingencies",
47+
"repo_url": "https://github.com/TaskBeacon/H000038-two-armed-bandit",
48+
"default_branch": "main",
49+
"download_url": "https://github.com/TaskBeacon/H000038-two-armed-bandit/archive/refs/heads/main.zip",
50+
"run_url": "https://taskbeacon.github.io/psyflow-web/?task=H000038-two-armed-bandit",
51+
"last_updated": "2026-04-03T15:06:58Z"
3752
}
3853
]
3954
}

‎public/readmes/H000038-two-armed-bandit.md‎

Lines changed: 124 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,124 @@
1+
# Two-Armed Bandit Task (HTML Preview)
2+
3+
![Maturity: prototype](https://img.shields.io/badge/Maturity-prototype-64748b?style=flat-square&labelColor=111827)
4+
5+
| Field | Value |
6+
|---|---|
7+
| Name | Two-Armed Bandit Task |
8+
| Version | html (v0.2.3-dev) |
9+
| URL / Repository | https://github.com/TaskBeacon/H000038-two-armed-bandit |
10+
| Short Description | Browser preview of the two-choice probabilistic reward learning task with block-wise contingencies |
11+
| Created By | TaskBeacon py2js port |
12+
| Date Updated | 2026-04-03 |
13+
| Modality | Behavior |
14+
| Language | Chinese |
15+
16+
## 1. Task Overview
17+
18+
This HTML companion mirrors the local `T000038-two-armed-bandit` task. Participants repeatedly choose between a left and a right machine, receive stochastic reward feedback, and learn which side is better within each block. The browser preview preserves the local trial contract and response mapping, while shortening the run to a 2-block, 12-trial preview for fast review in the shared runner.
19+
20+
## 2. Task Flow
21+
22+
### Block-Level Flow
23+
24+
| Step | Description |
25+
|---|---|
26+
| Load Config | Load the browser preview config. |
27+
| Show Instructions | Present the Chinese instruction screen. |
28+
| Initialize Reward Tracker | Start cumulative reward at 0 points. |
29+
| Generate Conditions | Expand the block-wise left/right reward probabilities into repeated trial conditions. |
30+
| Run Trials | Execute the same fixation -> choice -> confirmation -> feedback -> ITI flow as the local task. |
31+
| Block Summary | Show per-block response and reward summary when more than one block remains. |
32+
| Finalize | Show the final total score and export data through the shared runner. |
33+
34+
### Trial-Level Flow
35+
36+
| Step | Description |
37+
|---|---|
38+
| Pre-choice fixation | A central fixation cross is shown briefly. |
39+
| Bandit choice | Left and right machines are shown; the participant presses `F` or `J`. |
40+
| Choice confirmation | The selected machine is highlighted briefly. |
41+
| Outcome feedback | Win/no-win feedback and running total are shown. |
42+
| Inter-trial interval | A short fixation interval separates trials. |
43+
44+
### Controller Logic
45+
46+
| Feature | Description |
47+
|---|---|
48+
| Condition scheduling | A block-specific `(p_left, p_right)` schedule is repeated across trials. |
49+
| Reward sampling | The chosen side is sampled with Bernoulli reward using the configured probability. |
50+
| No-response fallback | If the response deadline expires, a configurable fallback choice is imputed. |
51+
| State tracking | A cumulative reward tracker updates the running score after every trial. |
52+
| Adaptive control | None. This is a static probabilistic learning task, not a staircase or reversal task. |
53+
54+
### Other Logic
55+
56+
| Feature | Description |
57+
|---|---|
58+
| Trial context | Every participant-visible screen emits trial context before `show()` or `captureResponse()`. |
59+
| Deterministic QA seed | Preview sampling uses the configured block seeds for reproducible browser QA runs. |
60+
| Summary metrics | Block and final summaries report left-choice rate, win rate, response rate, and total score. |
61+
62+
## 3. Configuration Summary
63+
64+
Settings are defined in `config/config.yaml`.
65+
66+
### a. Subject Info
67+
68+
| Field | Meaning |
69+
|---|---|
70+
| `subject_id` | Numeric participant identifier supplied by the shared runner. |
71+
72+
### b. Window Settings
73+
74+
| Parameter | Value |
75+
|---|---|
76+
| `window.size` | `[1280, 720]` |
77+
| `window.units` | `pix` |
78+
| `window.screen` | `0` |
79+
| `window.bg_color` | `black` |
80+
| `window.fullscreen` | `false` |
81+
| `window.monitor_width_cm` | `35.5` |
82+
| `window.monitor_distance_cm` | `60` |
83+
84+
### c. Stimuli
85+
86+
| Name | Type | Description |
87+
|---|---|---|
88+
| `instruction_text` | text | Chinese instructions describing the left/right machine choice task. |
89+
| `fixation` | text | Central fixation marker shown before choice and during ITI. |
90+
| `machine_left` / `machine_right` | rect | Left/right machine panels. |
91+
| `machine_left_label` / `machine_right_label` | text | Left/right machine labels. |
92+
| `highlight_left` / `highlight_right` | rect | Selected-machine highlight overlays. |
93+
| `choice_prompt` | text | Prompt asking the participant to choose a machine. |
94+
| `target_prompt` | text | Brief confirmation of the selected machine. |
95+
| `feedback_win` / `feedback_loss` | text | Reward outcome feedback with the updated score. |
96+
| `block_break` | text | Optional block summary for multi-block preview runs. |
97+
| `good_bye` | text | Final total score shown at task completion. |
98+
99+
### d. Timing
100+
101+
| Phase | Duration |
102+
|---|---|
103+
| `timing.pre_choice_fixation_duration` | `0.5 s` |
104+
| `timing.bandit_choice_duration` | `2.5 s` |
105+
| `timing.choice_confirmation_duration` | `0.4 s` |
106+
| `timing.outcome_feedback_duration` | `0.8 s` |
107+
| `timing.iti_duration` | `0.6 s` |
108+
109+
### e. Browser Preview Differences
110+
111+
| Parameter | Meaning |
112+
|---|---|
113+
| `task.total_blocks` | Shortened to 2 for preview. |
114+
| `task.trial_per_block` | Shortened to 6 for preview. |
115+
| `task.total_trials` | Shortened to 12 for preview. |
116+
| `condition_generation.block_probabilities` | Uses the first two block contingencies from the full local task. |
117+
118+
## 4. Methods (for academic publication)
119+
120+
The HTML companion presents the same two-armed bandit learning task as the local PsychoPy build, but inside the shared browser runner. On each trial, participants choose one of two machines with block-specific reward probabilities, receive stochastic feedback, and update their choice strategy over time. The preview keeps the same stage order, scoring meaning, and timeout/fallback behavior as the local task while shortening the overall run length for browser testing and gallery navigation.
121+
122+
## Run
123+
124+
Open the TaskBeacon browser runner and launch `H000038-two-armed-bandit` to inspect the preview.

‎public/readmes/T000038-two-armed-bandit.md‎

Lines changed: 115 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,115 @@
1+
# Two-Armed Bandit Task
2+
3+
![Maturity: draft](https://img.shields.io/badge/Maturity-draft-64748b?style=flat-square&labelColor=111827)
4+
5+
| Field | Value |
6+
|---|---|
7+
| Name | Two-Armed Bandit Task |
8+
| Version | v0.2.3-dev |
9+
| URL / Repository | https://github.com/TaskBeacon/T000038-two-armed-bandit |
10+
| Short Description | Two-option bandit learning task with block-wise probability reversals. |
11+
| Created By | TaskBeacon |
12+
| Date Updated | 2026-04-03 |
13+
| PsyFlow Version | 0.1.9 |
14+
| PsychoPy Version | 2025.1.1 |
15+
| Modality | Behavior |
16+
| Language | Chinese |
17+
| Voice Name | zh-CN-YunyangNeural |
18+
19+
## 1. Task Overview
20+
21+
This task implements a two-option bandit paradigm. On each trial, participants choose left or right, receive stochastic reward feedback, and update behavior across repeated trials. Reward probabilities are stable within a block and change across blocks to test learning and adaptation.
22+
23+
## 2. Task Flow
24+
25+
### Block-Level Flow
26+
27+
| Step | Description |
28+
|---|---|
29+
| 1. Parse mode/config | `main.py` loads runtime mode and YAML config. |
30+
| 2. Initialize runtime | Window, keyboard, trigger runtime, stimulus bank, and task schedule settings are initialized. |
31+
| 3. Prepare block schedule | Condition-generation settings prepare per-trial `(p_left, p_right)` schedule for the block. |
32+
| 4. Execute trials | `BlockUnit(...).run_trial(...)` executes all planned trials. |
33+
| 5. Block summary | Choice rates and reward metrics are displayed. |
34+
| 6. Final summary | Final cumulative metrics are shown and data are saved. |
35+
36+
### Trial-Level Flow
37+
38+
| Step | Description |
39+
|---|---|
40+
| Pre-choice fixation | Central fixation before choice. |
41+
| Bandit choice | Two options are displayed and response is captured (`F/J`). |
42+
| Choice confirmation | Selected option is highlighted briefly. |
43+
| Outcome feedback | Reward/no-reward feedback and running total are displayed. |
44+
| Inter-trial interval | Fixation before next trial. |
45+
46+
### Controller Logic
47+
48+
| Component | Description |
49+
|---|---|
50+
| Architecture note | No adaptive controller object is used; static condition-generation settings and task utilities drive scheduling/outcomes. |
51+
| Block probabilities | Per-block left/right reward probabilities are configured. |
52+
| Reward sampling | Bernoulli draw from selected-side probability. |
53+
| No-response fallback | Optional policy imputes a choice when no response is made. |
54+
| State tracking | `RewardTracker` tracks cumulative reward. |
55+
56+
### Runtime Context Phases
57+
58+
| Phase Label | Meaning |
59+
|---|---|
60+
| `pre_choice_fixation` | Fixation stage before choice. |
61+
| `bandit_choice` | Choice response window. |
62+
| `choice_confirmation` | Selected-option confirmation stage. |
63+
| `outcome_feedback` | Trial outcome feedback stage. |
64+
| `iti` | ITI stage. |
65+
66+
## 3. Configuration Summary
67+
68+
### a. Subject Info
69+
70+
| Field | Meaning |
71+
|---|---|
72+
| `subject_id` | Participant identifier. |
73+
74+
### b. Window Settings
75+
76+
| Parameter | Value |
77+
|---|---|
78+
| `size` | `[1280, 720]` |
79+
| `units` | `pix` |
80+
| `screen` | `0` |
81+
| `bg_color` | `black` |
82+
| `fullscreen` | `false` |
83+
| `monitor_width_cm` | `35.5` |
84+
| `monitor_distance_cm` | `60` |
85+
86+
### c. Stimuli
87+
88+
| Name | Type | Description |
89+
|---|---|---|
90+
| `fixation` | text | Central fixation marker. |
91+
| `machine_left/right` | rect | Left/right option panels. |
92+
| `machine_left_label/right_label` | text | Option labels. |
93+
| `highlight_left/right` | rect | Selected option highlight. |
94+
| `choice_prompt` | text | Choice prompt with response deadline. |
95+
| `target_prompt` | text | Choice confirmation text. |
96+
| `feedback_win/loss` | text | Reward outcome feedback. |
97+
| `block_break` / `good_bye` | text | Block/final summary pages. |
98+
99+
### d. Timing
100+
101+
| Phase | Duration |
102+
|---|---|
103+
| pre_choice_fixation_duration | 0.5 s |
104+
| bandit_choice_duration | 2.5 s |
105+
| choice_confirmation_duration | 0.4 s |
106+
| outcome_feedback_duration | 0.8 s |
107+
| iti_duration | 0.6 s |
108+
109+
## 4. Methods (for academic publication)
110+
111+
Participants repeatedly chose between two bandit options under uncertain reward contingencies. Choice was followed by explicit selection confirmation and immediate reward/no-reward feedback. This design supports estimation of trial-wise value learning and choice bias.
112+
113+
Reward probabilities were manipulated at the block level. Within each block, option probabilities remained fixed; across blocks, probabilities changed to induce strategy adaptation. Core outcomes include side choice proportions, reward rate, cumulative score, and response timing.
114+
115+
The implementation supports `human`, `qa`, and `sim` modes under a shared trial pipeline with standardized context instrumentation.

‎src/data/readmes/H000038-two-armed-bandit.md‎

Lines changed: 124 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,124 @@
1+
# Two-Armed Bandit Task (HTML Preview)
2+
3+
![Maturity: prototype](https://img.shields.io/badge/Maturity-prototype-64748b?style=flat-square&labelColor=111827)
4+
5+
| Field | Value |
6+
|---|---|
7+
| Name | Two-Armed Bandit Task |
8+
| Version | html (v0.2.3-dev) |
9+
| URL / Repository | https://github.com/TaskBeacon/H000038-two-armed-bandit |
10+
| Short Description | Browser preview of the two-choice probabilistic reward learning task with block-wise contingencies |
11+
| Created By | TaskBeacon py2js port |
12+
| Date Updated | 2026-04-03 |
13+
| Modality | Behavior |
14+
| Language | Chinese |
15+
16+
## 1. Task Overview
17+
18+
This HTML companion mirrors the local `T000038-two-armed-bandit` task. Participants repeatedly choose between a left and a right machine, receive stochastic reward feedback, and learn which side is better within each block. The browser preview preserves the local trial contract and response mapping, while shortening the run to a 2-block, 12-trial preview for fast review in the shared runner.
19+
20+
## 2. Task Flow
21+
22+
### Block-Level Flow
23+
24+
| Step | Description |
25+
|---|---|
26+
| Load Config | Load the browser preview config. |
27+
| Show Instructions | Present the Chinese instruction screen. |
28+
| Initialize Reward Tracker | Start cumulative reward at 0 points. |
29+
| Generate Conditions | Expand the block-wise left/right reward probabilities into repeated trial conditions. |
30+
| Run Trials | Execute the same fixation -> choice -> confirmation -> feedback -> ITI flow as the local task. |
31+
| Block Summary | Show per-block response and reward summary when more than one block remains. |
32+
| Finalize | Show the final total score and export data through the shared runner. |
33+
34+
### Trial-Level Flow
35+
36+
| Step | Description |
37+
|---|---|
38+
| Pre-choice fixation | A central fixation cross is shown briefly. |
39+
| Bandit choice | Left and right machines are shown; the participant presses `F` or `J`. |
40+
| Choice confirmation | The selected machine is highlighted briefly. |
41+
| Outcome feedback | Win/no-win feedback and running total are shown. |
42+
| Inter-trial interval | A short fixation interval separates trials. |
43+
44+
### Controller Logic
45+
46+
| Feature | Description |
47+
|---|---|
48+
| Condition scheduling | A block-specific `(p_left, p_right)` schedule is repeated across trials. |
49+
| Reward sampling | The chosen side is sampled with Bernoulli reward using the configured probability. |
50+
| No-response fallback | If the response deadline expires, a configurable fallback choice is imputed. |
51+
| State tracking | A cumulative reward tracker updates the running score after every trial. |
52+
| Adaptive control | None. This is a static probabilistic learning task, not a staircase or reversal task. |
53+
54+
### Other Logic
55+
56+
| Feature | Description |
57+
|---|---|
58+
| Trial context | Every participant-visible screen emits trial context before `show()` or `captureResponse()`. |
59+
| Deterministic QA seed | Preview sampling uses the configured block seeds for reproducible browser QA runs. |
60+
| Summary metrics | Block and final summaries report left-choice rate, win rate, response rate, and total score. |
61+
62+
## 3. Configuration Summary
63+
64+
Settings are defined in `config/config.yaml`.
65+
66+
### a. Subject Info
67+
68+
| Field | Meaning |
69+
|---|---|
70+
| `subject_id` | Numeric participant identifier supplied by the shared runner. |
71+
72+
### b. Window Settings
73+
74+
| Parameter | Value |
75+
|---|---|
76+
| `window.size` | `[1280, 720]` |
77+
| `window.units` | `pix` |
78+
| `window.screen` | `0` |
79+
| `window.bg_color` | `black` |
80+
| `window.fullscreen` | `false` |
81+
| `window.monitor_width_cm` | `35.5` |
82+
| `window.monitor_distance_cm` | `60` |
83+
84+
### c. Stimuli
85+
86+
| Name | Type | Description |
87+
|---|---|---|
88+
| `instruction_text` | text | Chinese instructions describing the left/right machine choice task. |
89+
| `fixation` | text | Central fixation marker shown before choice and during ITI. |
90+
| `machine_left` / `machine_right` | rect | Left/right machine panels. |
91+
| `machine_left_label` / `machine_right_label` | text | Left/right machine labels. |
92+
| `highlight_left` / `highlight_right` | rect | Selected-machine highlight overlays. |
93+
| `choice_prompt` | text | Prompt asking the participant to choose a machine. |
94+
| `target_prompt` | text | Brief confirmation of the selected machine. |
95+
| `feedback_win` / `feedback_loss` | text | Reward outcome feedback with the updated score. |
96+
| `block_break` | text | Optional block summary for multi-block preview runs. |
97+
| `good_bye` | text | Final total score shown at task completion. |
98+
99+
### d. Timing
100+
101+
| Phase | Duration |
102+
|---|---|
103+
| `timing.pre_choice_fixation_duration` | `0.5 s` |
104+
| `timing.bandit_choice_duration` | `2.5 s` |
105+
| `timing.choice_confirmation_duration` | `0.4 s` |
106+
| `timing.outcome_feedback_duration` | `0.8 s` |
107+
| `timing.iti_duration` | `0.6 s` |
108+
109+
### e. Browser Preview Differences
110+
111+
| Parameter | Meaning |
112+
|---|---|
113+
| `task.total_blocks` | Shortened to 2 for preview. |
114+
| `task.trial_per_block` | Shortened to 6 for preview. |
115+
| `task.total_trials` | Shortened to 12 for preview. |
116+
| `condition_generation.block_probabilities` | Uses the first two block contingencies from the full local task. |
117+
118+
## 4. Methods (for academic publication)
119+
120+
The HTML companion presents the same two-armed bandit learning task as the local PsychoPy build, but inside the shared browser runner. On each trial, participants choose one of two machines with block-specific reward probabilities, receive stochastic feedback, and update their choice strategy over time. The preview keeps the same stage order, scoring meaning, and timeout/fallback behavior as the local task while shortening the overall run length for browser testing and gallery navigation.
121+
122+
## Run
123+
124+
Open the TaskBeacon browser runner and launch `H000038-two-armed-bandit` to inspect the preview.

0 commit comments

Comments
 (0)