Token Test (Revised)

Version: v1 (current)

Overview

The Token Test (revised) assesses verbal comprehension by having participants follow multi-step instructions to manipulate colored tokens. Each token is a simple colored shape (circle, square, triangle, or rectangle).

Depending on the trial's interaction type, participants either click/tap a token to select it (select mode) or freely drag a token across an interactive canvas to place it on another token (move mode). The task records the interaction trace, timing, and the full factual board state of each response.

This implementation uses HTML Canvas for smooth, free-form interaction with visual feedback.

Scientific Background

• Origin: De Renzi & Vignolo (1962) - A sensitive test to detect receptive disturbances in aphasics
• Use Cases: Aphasia assessment, language comprehension research, auditory processing evaluation
• Standard Format: Commands of increasing complexity (e.g., "Touch the red circle", "Touch the large blue square, then the small yellow rectangle")

Add To A Study

1. Open your study and go to the Design tab
2. Under Behavioral tasks, find "Token Test (revised)" and click Add
3. Click Configure on the new task card to customize parameters

Configuration

Instructions

• Pre-task instructions: Shown before the task begins. Explain the rule (e.g., "You will see colored shapes. Follow the instructions to drag them into the correct slots.")
• Hint instructions: Short reminder shown during the task (optional)

Layout & Appearance

Parameter	Default	Description
Grid rows (token_layout.rows)	4	Number of rows in token grid (1-10)
Grid columns (token_layout.cols)	5	Number of columns in token grid (1-10)
Large token size (token_size_large_px)	80px	Size of large tokens in pixels (20-200)
Small token size (token_size_small_px)	50px	Size of small tokens in pixels (10-150)

The shapes, sizes, and colors of the tokens themselves are set per-cell in three grid spreadsheets (Token Shape Grid, Token Size Grid, Token Color Grid), sized to match the rows × columns layout.

Timing

• Response timeout (response_timeout_ms): Optional time limit (in milliseconds, minimum 0) before the trial auto-submits with source: 'timeout'. Empty by default (no limit). Can be overridden per trial.
• Delay before Next appears (ms) (token_min_time_before_next_ms): Minimum time (in milliseconds) before the Next button becomes available on each trial. Default 500.

Trials Configuration (Spreadsheet)

Trials are configured using a spreadsheet editor with the following columns:

• Instruction: Text shown to the participant (e.g., "Touch the red circle")
• Type: Interaction mode - select (click to select) or move (drag tokens)
• Target Shape: Expected token shape (circle, square, triangle, rectangle)
• Target Color: Expected token color (hex code, e.g., #e11d48)
• Target Size: Expected token size (large or small) - optional
• On Top Shape: For move trials - shape of token to place on top of - optional
• On Top Color: For move trials - color of token to place on top of - optional
• On Top Size: For move trials - size of token to place on top of - optional
• Fixation (ms): Delay before interaction starts (e.g., 300)
• Block: Label for grouping trials (e.g., A, B, C) - optional
• Reset Positions: Whether to reset tokens to grid positions before this trial (true/false, default: true)

Per-trial overrides for large/small token size and response timeout are supported in the stored trial data, but they are not editable columns in this spreadsheet — they are preserved when present and otherwise fall back to the general settings.

Understanding Reset Positions

The reset_positions option controls whether tokens return to their original grid positions before each trial:

• true (default): Tokens reset to grid layout - useful for independent trials
• false: Tokens remain where they were left - useful for sequential tasks where position matters

Example use case: In a move trial, you might set reset_positions to false for a follow-up trial that asks "Now touch the red circle" to test if the participant remembers where they placed it.

Example Spreadsheet Configuration

Instruction	Type	Target Shape	Target Color	Target Size	...	Fixation (ms)	Block	Reset Positions
Touch the red circle.	select	circle	#e11d48			300	A	true
Touch the small green square.	select	square	#10b981	small		300	A	true
Put the red circle on the green square.	move	circle	#e11d48			300	B	false
Now touch the red circle.	select	circle	#e11d48			300	B	false

Available Shapes

• circle: Round token
• square: Square token
• triangle: Upward-pointing triangle
• rectangle: Horizontal rectangle

Recommended Colors

• Red: #e11d48
• Green: #10b981
• Blue: #3b82f6
• Yellow: #f59e0b

You can use any hex color code.

Participant Experience

What Participants See

1. Instruction banner: The current trial's instruction text displayed above the canvas (e.g., "Touch the red circle.")
2. Token canvas: Tokens laid out on a grid drawn on an HTML canvas
3. Next button: Manual submit (disabled until input is accepted)

How Participants Interact

In select trials:

1. Click/tap a token to select it; clicking again deselects it
2. Multiple tokens can be selected for multi-step instructions
3. Submit the response with the Next button (or it auto-submits on response timeout)

In move trials:

1. Press and drag a token freely across the canvas
2. Release to drop it anywhere (there are no fixed target slots — placement is free-form)
3. Overlap and z-order relationships are recorded at submit time

Visual Feedback

• Highlight ring: The most recently touched token shows a bright ring; other selected tokens show a dimmer ring
• Shadow effect: Dragged tokens have a drop shadow
• Cursor change: Cursor changes to "grabbing" during a drag

Data Output

Markers and Responses

The task records high-resolution timestamps in two separate collections. Multiple marker types track token interactions. The trial lifecycle is bounded by trial_start / trial_end (plus main_phase_start at the first trial), and response_recorded is emitted at submit time.

Markers (stimulus_shown — emitted when the tokens become interactive):

{
  "type": "stimulus_shown",
  "ts": "2024-01-01T00:00:01.000Z",
  "hr": 1234.56,
  "data": {
    "trial": 1,
    "block": "A",
    "fixation_ms": 300,
    "instruction": "Touch the red circle.",
    "instruction_type": "select",
    "token_count": 20,
    "grid": {"rows": 4, "cols": 5}
  }
}

Markers (token_touch — emitted on every pointerdown that hits a token, in all modes):

{
  "type": "token_touch",
  "data": {
    "token_id": "large_circle_0_0",
    "shape": "circle",
    "color": "#e11d48",
    "size": "large",
    "position": {"x": 200, "y": 150}
  }
}

Markers (token_select / token_deselect in select mode):

{
  "type": "token_select",
  "data": {
    "token_id": "token_0",
    "shape": "circle",
    "color": "#e11d48",
    "size": "large"
  }
}

Markers (drag_start / drag_end in move mode):

{
  "type": "drag_end",
  "data": {
    "token_id": "token_0",
    "shape": "circle",
    "color": "#e11d48",
    "size": "large",
    "position": {"x": 200, "y": 150},
    "z_index": 5
  }
}

Response Data:

Field	Type	Description
trial_index	number	Trial number (1-based)
source	string	'user_submit', 'timeout', or 'moderator_advance'
instruction_type	string	'select' or 'move'
selected_tokens	array	Tokens selected by the participant [{ id, shape, color, size }]
token_positions	array	Position of all tokens at submit time [{ id, x, y, zIndex }]
overlaps	array	Detected overlap relationships at submit time [{ top, bottom }]
evaluation_details	array	Per-target factual details (no correct field; researchers score from these facts)
interactions	array	Full interaction trace [{ type, tokenId, timestamp_hr, position? }]
latency_ms	number?	Time from instruction onset to submit (omitted when onset is unavailable)
artifact_filename	string?	Filename of the board screenshot (e.g., token_test_0_trial-1_select-001.png), available under data/media/ in the export
sequence_index	number?	1-based index of the screenshot within the trial
is_final	boolean?	true on the submit-time screenshot record; false on intermediate screenshots
capture_reason	string?	Which interaction triggered this screenshot: select (a token was selected or deselected), drag_start (captured at contact, before the token moves), drag_end (captured at release), or final (the confirmed board state at submit time, matching is_final: true)

No response_correct field: Token Test correctness depends on clinical scoring criteria (partial credit, multiple targets, overlap relationships) that researchers decide in post-processing. The full factual state is recorded so researchers can derive accuracy with any scoring scheme.

Board screenshots: After each significant board change and at submit time, a PNG screenshot is captured and emitted as a file artifact, named token_test_{task index}_trial-{trial}_{capture reason}-{sequence}.png (e.g. token_test_0_trial-1_select-001.png, token_test_0_trial-1_drag-start-002.png, token_test_0_trial-1_final-003.png). The screenshot filename is linked from the response record via artifact_filename, and the same capture reason is recorded in the capture_reason field so the filename is not the only source of that meaning. Intermediate screenshots (before submit) have is_final: false.

Screenshot detail in the Scoring tab: the Scoring view's Token Test card includes a collapsible "Token Test screenshots" table that lists every screenshot with its trial, sequence number, capture reason, and final flag next to a thumbnail of the PNG, so a researcher can see the context for each captured board state without decoding the filename.

Summary Artifact

When the task finishes (outside preview mode), a summary JSON file is emitted as an artifact named token_test_summary_{task_index}.json. It contains factual counts only — no correctness judgement:

{
  "task_kind": "token_test_revised",
  "task_index": 0,
  "overall": {
    "total_trials": 3,
    "completed_trials": 3,
    "timeouts": 0
  },
  "breakdowns": {
    "block": { "A": { "total": 2, "timeouts": 0 }, "B": { "total": 1, "timeouts": 0 } },
    "instruction_type": { "select": { "total": 2, "timeouts": 0 }, "move": { "total": 1, "timeouts": 0 } }
  },
  "trials": [
    {
      "trial_index": 1,
      "instruction": "Touch the red circle.",
      "instruction_type": "select",
      "block": "A",
      "source": "user_submit",
      "selected_tokens": [{ "id": "large_circle_0_0", "shape": "circle", "color": "#e11d48", "size": "large" }],
      "interactions_count": 1
    }
  ]
}

The breakdowns.block field is null when no blocks are used. completed_trials counts trials whose source is not 'timeout'.

Tips for Researchers

Creating Effective Commands

1. Start simple: A single token to select
2. Increase complexity: Multiple tokens, specific order
3. Vary attributes: Mix shapes and colors
4. Test comprehension: Include distractors
5. Consider language: Adapt instructions to participant's language

Color Considerations

• Use high-contrast colors
• Consider color-blind friendly palettes:
  • Red/Blue: Most color-blind friendly
  • Avoid Red/Green combinations only
• Test on your target population

Trial Design

• Block A: Simple commands (1-2 tokens)
• Block B: Moderate complexity (3-4 tokens)
• Block C: Complex commands (5+ tokens with attributes)

Moderation Modes

• Unmoderated: Written commands, participants work independently
• Moderated: Researcher observes, can give verbal commands
• Strictly moderated: Researcher controls task progression, Next button hidden

Troubleshooting

Tokens Not Responding

• Ensure task has started (instruction should be visible)
• Check browser console for errors
• Verify JSON trial configuration is valid

Dragged Tokens Not Moving

• In move trials, press directly on a token before dragging
• Check the canvas is not being zoomed/scaled
• Tokens are dropped free-form; there are no fixed slots to snap to

Touch Not Working

• Ensure device supports pointer events
• Try using a stylus or finger (not palm)
• Check browser compatibility (modern browsers only)

Technical Details

• Canvas size: Computed from the grid layout and token size (rows × columns × cell size), not a fixed value
• Token sizes: Large and small token sizes are configurable (defaults 80px / 50px)
• Rendering: HTML5 Canvas with pointer events; tokens drawn by z-order with overlap detection
• Touch support: Yes (via pointer events)
• Accessibility: Keyboard support not yet implemented

References

• De Renzi, E., & Vignolo, L.A. (1962). The token test: A sensitive test to detect receptive disturbances in aphasics. Brain, 85(4), 665-678.
• Revised Token Test standardization (various versions available)