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).

Participants drag tokens from a palette to target slots on an interactive canvas. The task records the selection order, timing, and correctness of each response.

This implementation uses HTML Canvas for smooth, free-form dragging 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

Open your study and go to the Design tab
Under Behavioral tasks, find "Token Test (revised)" and click Add
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	2	Number of rows in token grid (1-10)
Grid columns	5	Number of columns in token grid (1-10)
Large token size	80px	Size of large tokens in pixels (20-200)
Small token size	50px	Size of small tokens in pixels (10-150)
Background color	`#FFFFFF`	Canvas background color
Grid line color	`#EEEEEE`	Color of grid lines (visual guide)
Selection color	`#FFD700`	Highlight color for selected tokens (gold)
Text color	`#000000`	Instruction text color

Feedback & Timing

Show feedback: Brief indication after each response (enabled by default)
Response timeout: Optional time limit (in milliseconds) before auto-submit

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)
Token Size Large (px): Large token size for this trial - optional (empty = use general setting)
Token Size Small (px): Small token size for this trial - optional (empty = use general setting)
Response Timeout (ms): Response timeout for this trial - optional (empty = use general setting)

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

Instruction banner: Command displayed above the canvas (e.g., "Drag the red circle to slot 1")
Palette area: Tokens displayed in a grid at the top
Target slots: Numbered dashed boxes where tokens should be placed
Submit button: Optional manual submit (hidden in strictly moderated mode)

How Participants Interact

Drag: Click/touch a token in the palette and drag it
Drop: Release the token over a target slot
Snap: Token automatically snaps to slot center
Return: If dropped outside slots, token returns to palette
Auto-submit: Task advances automatically when all required slots are filled

Visual Feedback

Shadow effect: Dragged tokens have a shadow
Slot highlighting: Filled slots turn green
Slot numbers: Each slot shows its order number
Cursor change: Cursor changes to "grabbing" during drag

Data Output

Markers and Responses

The task records high-resolution timestamps in two separate collections. Multiple marker types track token interactions:

Markers (stimulus_shown):

{
  "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": 10,
    "grid": {"rows": 2, "cols": 5}
  }
}

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:

{
  "trial_index": 1,
  "source": "user_submit",
  "instruction_type": "select",
  "selected_tokens": [{"id": "token_0", "shape": "circle", "color": "#e11d48", "size": "large"}],
  "token_positions": [{"id": "token_0", "x": 80, "y": 40, "zIndex": 0}],
  "overlaps": [],
  "evaluation": {"correct": true, "details": "..."},
  "interactions": [{"type": "select", "tokenId": "token_0", "timestamp": 1500}]
}

This task does not produce summary artifacts. All data is in the markers and responses collections.

Tips for Researchers

Creating Effective Commands

Start simple: Single token, single slot
Increase complexity: Multiple tokens, specific order
Vary attributes: Mix shapes and colors
Test comprehension: Include distractors
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, submit 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

Tokens Not Snapping to Slots

Tokens only snap when released over a slot
Try dragging closer to the slot center
Check canvas is not being zoomed/scaled

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: 800x600 pixels
Token size: 50px diameter/width
Palette area: 760x150px at top
Slots area: 600x100px in center
Rendering: HTML5 Canvas with pointer events
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)

Overview​

Scientific Background​

Add To A Study​

Configuration​

Instructions​

Layout & Appearance​

Feedback & Timing​

Trials Configuration (Spreadsheet)​

Understanding Reset Positions​

Example Spreadsheet Configuration​

Available Shapes​

Recommended Colors​

Participant Experience​

What Participants See​

How Participants Interact​

Visual Feedback​

Data Output​

Markers and Responses​

Tips for Researchers​

Creating Effective Commands​

Color Considerations​

Trial Design​

Moderation Modes​

Troubleshooting​

Tokens Not Responding​

Tokens Not Snapping to Slots​

Touch Not Working​

Technical Details​

References​