# Following Instructions

Web demo of an fMRI instruction-following task with semantic categorisation and
motor responses. Part of the NCCR Evolving Language task library at the
University of Geneva.

Participants receive a French instruction (e.g. *"Choisissez l'image qui a le
contenu le plus petit"*), then see two images presented sequentially, and must
choose one according to the instruction. The full experiment crosses four
orthogonal factors — semantic category (animals, fruits, vehicles), stimulus
modality (auditory, visual, visual-enhanced), task instruction (colour, size
judgement) and response mapping (left, right) — across 4 blocks of 54 trials
(216 trials total). A 2-back working memory task (OpenSesame) complements the
fMRI session.

The code in this repository is the **web demo** shown in the task library
iframe. It runs 5 representative trials from block 1 so visitors can get a
feel for the paradigm. The complete experiment (PsychoPy scripts for fMRI +
online version + N-back) is distributed as a ZIP via the library.

## Requirements

- Any modern browser (Chrome, Firefox, Safari, Edge) with JavaScript enabled.
- No build toolchain, no npm, no server-side code. It is a single static
  `index.html` plus the `images/` folder.
- For the full experiment (not included here, see Downloads below): PsychoPy
  on Windows, macOS or Linux.

## Install

Clone the repo and you are done — there are no dependencies to install.

```bash
git clone <repo-url> following-instructions
cd following-instructions
```

## Run

Open `index.html` directly in a browser, or serve the folder with any static
file server, for example:

```bash
python3 -m http.server 8000
# then open http://localhost:8000/
```

Press any key on the info overlay to start the demo. Trials loop
automatically once the demo ends.

## Controls

- **Any key** on the intro screen: start the demo.
- **F**: choose the **first** image of the pair.
- **J**: choose the **second** image of the pair.
- Images are shown sequentially and are **not** re-displayed during the
  response window, so the task has a short-term memory component. You have
  4 seconds to respond; no answer is logged as *Pas assez rapide*.

In the scanner version, keys map to button-box responses `1` (left, F) and
`6` (right, J).

## Trial timing (ms)

| Phase       | Duration |
|-------------|----------|
| Fixation    | 600      |
| Instruction | 3000     |
| Blank       | 200      |
| Image 1     | 1500     |
| Blank       | 200      |
| Image 2     | 1500     |
| Blank       | 200      |
| Response    | up to 4000 |
| Feedback    | 1500     |

Timings match the fMRI task.

## Outputs

The web demo is a **visual-only preview** and does not log or save any data —
feedback (correct / incorrect / too slow) is shown on screen then discarded.

The full experiment (ZIP) produces one CSV per participant per block, one row
per trial, with at minimum: `trial_index`, `block_id`, `sentence`,
`semantic_category`, `modality`, `task_type`, `response_mapping`, `picture1`,
`picture2`, `response_key`, `accuracy`, `rt` (ms). Derived measures include
accuracy (%), mean RT, fMRI contrast maps across the four factors, and
language-ROI selectivity against Fedorenko parcels. See `task.json` for the
full variable dictionary.

## Files

```
.
├── index.html        Single-page demo (HTML + inline CSS + inline JS)
├── images/           36 stimulus JPEGs (animals, fruits, vehicles; 3 exemplars × 3 items per category, plus training set)
├── task.json         Library metadata (domains, contributors, design, variables)
├── .gitlab-ci.yml    CI pipeline: zips everything except task.json/CI config into task.zip as an artifact
└── README.md         This file
```

Stimulus naming convention: `A*` = animals, `V*` = vehicles, `VE*` = fruits
(*végétaux*); `*train_*` = practice set.

## Deployment

The repo is mirrored from
`ttf-digital-data-generation/nccr-evolang-tasks/following-instructions` on
GitLab. On push to the default branch (or on tag), GitLab CI copies all
non-meta files into `dist/`, zips them into `task.zip`, and publishes
`task.json`, `dist/` and `task.zip` as artifacts (retained 90 days). The
library SPA (`library.nccr-ttf-ddg.ch`) pulls these via
`npm run registry:sync`.

## Contact

- **Software / methodology / data curation:** Marion Bouffier —
  <marion.bouffier@unige.ch>
- **Conceptualization / supervision / methodology:** Valentina Borghesani
  (ORCID [0000-0002-7909-8631](https://orcid.org/0000-0002-7909-8631))
- **Lab:** [Brain & Language Lab, UNIGE](https://www.unige.ch/fapse/brainandlanguage/)

Battery: *Following Instructions Study*. Engine: PsychoPy (web demo in
plain HTML/JS). Language: French. Target population: healthy young adults
scanned with fMRI.
