Documentation Index

Fetch the complete documentation index at: https://docs.assesskit.com/llms.txt

Use this file to discover all available pages before exploring further.

​

Variables

​

Overview

• Trial-by-trial variation - Different stimuli, parameters, or settings each trial
• Efficient experiment building - 160 trials from one template, not 160 components
• Systematic control - Define exact trial parameters in spreadsheet
• Data organization - Each row represents one trial with all parameters
• Import/export - Work with CSV files and external tools
• Randomization - Shuffle trial order automatically

• Multi-trial experiments (20+ trials)
• Systematic stimulus variation (different words/images each trial)
• Counterbalancing conditions
• Complex trial structures with many parameters
• Any time you’d build the “same” component many times with slight variations

​

Timeline Variables Concept

​

How It Works

1. Create a component template - Build one trial with variable placeholders
2. Define variables in spreadsheet - Each row is one trial, columns are parameters
3. Map columns to elements - Link spreadsheet columns to component properties
4. Variables substitute automatically - System generates unique trial for each row

• Create 160 separate components manually
• Each with different word, color, correct key
• Time-consuming, error-prone, hard to modify

• Create 1 component template
• Add 160 rows to variables spreadsheet
• Each row specifies: word, color, congruency, correct key
• System generates 160 trials automatically

​

Each Row = One Trial

​

Columns = Trial Parameters

• Stimulus content - Words, numbers, image filenames
• Display properties - Colors, positions, sizes
• Response configuration - Correct keys, feedback messages
• Trial metadata - Condition labels, block numbers
• Timing - Variable durations (if needed)

​

Variable Substitution in Components

Content: "${word}"
Color: ${color}

Image source: "${stimulus}.png"

Correct response: ${correctKey}

• Trial 1: ${word} → “RED”, ${color} → red, ${correctKey} → “F”
• Trial 2: ${word} → “BLUE”, ${color} → yellow, ${correctKey} → “J”
• And so on for each row in variables

​

Generating Many Trials from One Template

• Add text element with ${word} as content
• Set text color to ${color}
• Configure valid keys: F, J
• Set correct response to ${correctKey}

• Each row defines word, color, and correctKey
• System creates 160 unique trials at runtime
• All using the same template component

• Change template once, affects all 160 trials
• Add new trials by adding rows
• Modify trial parameters by editing cells
• Export/import for collaboration or reuse

​

When to Use Variables

​

Perfect Use Cases

• Stroop task (160 trials, varying word/color)
• N-Back task (100 trials, varying stimuli)
• Visual search (80 trials, varying target/distractor)
• Recognition memory (200 trials, old/new items)
• Lexical decision (300 trials, words/nonwords)

• Show each image from set exactly once
• Counterbalance condition order
• Present stimuli in predefined sequence
• Vary stimulus parameters systematically

• Multiple parameters per trial (stimulus, condition, block, difficulty)
• Trial-specific feedback messages
• Variable timing across trials
• Conditional correct responses

​

When NOT to Use Variables

• Same stimulus 20 times → Use loop frame instead
• No parameter variation → Variables unnecessary

• 5-10 trials → Faster to create separate components
• Overhead of variables not worth it

• If random selection from pool → Use per-stimulus frame
• Variables better for systematic, controlled variation

​

The Variables Spreadsheet

​

Spreadsheet Interface

• Rows - Scroll through thousands of trials
• Columns - Add unlimited parameters
• Cells - Click to edit individual values
• Headers - Column names (variable names)
• Row numbers - Trial indices (1, 2, 3…)

• Handles 1000+ rows smoothly
• Only renders visible cells for performance
• Scroll with mouse wheel or keyboard arrows

​

Adding Rows (Trials)

1. Click ”+ Add Row” button
2. New trial row appears at bottom
3. Fill in values for each column

1. Click ”+ Add Rows” button
2. Specify number (e.g., 50)
3. 50 blank rows added
4. Fill in systematically or import

• Right-click row number
• Select “Insert Row Above/Below”
• New blank row inserted at position

​

Adding Columns (Parameters)

1. Click ”+ Add Column” button
2. Enter column name (e.g., “word”, “color”, “correctKey”)
3. Select column type (text, image, number, etc.)
4. Column appears on right

• Use descriptive names: “stimulus”, “condition”, “blockNumber”
• No spaces (use camelCase or snake_case): “correctKey” or “correct_key”
• Match exactly when using ${columnName} in components

• Drag column header to new position
• Useful for grouping related parameters

• Right-click column header
• Select “Delete Column”
• Confirm deletion (can’t undo)

​

Editing Cells

1. Click cell
2. Type new value
3. Press Enter or Tab to save
4. Or click outside cell

• Tab - Move to next cell (right)
• Shift+Tab - Move to previous cell (left)
• Enter - Move down one row
• Arrow keys - Navigate in any direction

• Copy cell: Cmd/Ctrl + C
• Paste: Cmd/Ctrl + V
• Copy range: Select multiple cells, copy, paste

1. Select cell with value
2. Drag fill handle (bottom-right corner) down
3. Value copies to all cells in range
4. Or select range and use “Fill Down” menu option

​

Column Types

​

Text Columns

• Stimulus words (Stroop: “RED”, “BLUE”, “GREEN”)
• Condition labels (“congruent”, “incongruent”)
• Feedback messages (“Correct!”, “Try again”)
• Participant instructions varying by trial

​

Image Columns

• Stimulus images (faces, objects, scenes)
• Target and distractor images
• Feedback icons (checkmark, X)
• Variable backgrounds

1. Click cell in image column
2. “Select Image” button appears
3. Choose from media library
4. Filename fills cell automatically

• Type filename directly (e.g., “face_001.jpg”)
• Must match exact filename in media library
• Include file extension (.jpg, .png)

Image element source: "${faceImage}.png"

​

Audio Columns

• Spoken words
• Tones or beeps
• Music clips
• Ambient sounds

• Select from media library
• Or type filename (e.g., “tone_440hz.mp3”)

​

Video Columns

• Video stimuli
• Instructional clips
• Dynamic scenes

​

Number Columns

• Difficulty levels (1, 2, 3)
• Display durations in milliseconds
• Target positions (X, Y coordinates)
• Confidence ratings (1-7)
• Reaction time thresholds

​

Correct Response Columns

• Correct keyboard key (“F”, “J”, “Space”)
• Correct button choice (“Left”, “Right”)
• Correct numeric answer (for math tasks)
• Correct yes/no response

Correct response: ${correctKey}

​

Adding Variables Step-by-Step

​

Step 1: Open Variables View

1. In Task Editor, click Variables in left sidebar
2. Or press V keyboard shortcut
3. Variables spreadsheet opens

​

Step 2: Add Columns for Trial Parameters

• word (what word to display)
• color (display color)
• congruent (yes/no or congruent/incongruent)
• correctKey (F or J)

1. Click ”+ Add Column”
2. Name: “word”, Type: Text
3. Click ”+ Add Column”
4. Name: “color”, Type: Text
5. Click ”+ Add Column”
6. Name: “congruent”, Type: Text
7. Click ”+ Add Column”
8. Name: “correctKey”, Type: Text

​

Step 3: Add Rows for Trials

1. Click ”+ Add Rows”
2. Enter number of trials (e.g., 160)
3. 160 blank rows appear

​

Step 4: Fill in Trial Data

• Click each cell and type value
• Use Tab/Enter to navigate
• Copy/paste for repeated values

• Enter first value
• Drag fill handle to copy down
• Useful for repeated blocks

• Prepare data in Excel/Google Sheets
• Export as CSV
• Import to Cajal (see Import section below)

​

Step 5: Map Columns to Component Elements

1. Switch to Screens view
2. Select component to vary (e.g., stimulus component)
3. Select element within component (e.g., text element showing word)
4. In properties panel, find property to vary (e.g., text content)
5. Click variable icon next to property
6. Select column from dropdown (e.g., “word”)
7. Property now shows ${word} instead of fixed value

• Text element content → ${word}
• Text element color → ${color}
• Response configuration correct key → ${correctKey}

​

Step 6: Create Frame with Variables

1. Switch to Flow view
2. Select component(s) that use variables
3. Right-click → “Create Frame”
4. Select “Per-Trial Variables” frame type
5. Frame created - component will repeat for each row in variables

​

Step 7: Preview with Variables

1. Start preview (press P)
2. Set to preview subset (e.g., first 10 trials)
3. Run through trials
4. Verify each trial shows different values from variables
5. Check substitution working correctly

​

Column Mapping

​

Mapping Process

1. Select text element
2. Find “Text Content” in properties
3. Click variable link icon
4. Choose column (e.g., “word”)
5. Property updates to ${word}

1. Select image element
2. Find “Image Source” in properties
3. Click variable link icon
4. Choose column (e.g., “stimulus”)
5. Property updates to ${stimulus}
6. System appends file extension automatically (if not in variable)

1. Select component (not element)
2. Open response configuration section
3. Find “Correct Response” field
4. Click variable link icon
5. Choose column (e.g., “correctKey”)
6. Value updates to ${correctKey}

​

Using $ Syntax

"The word is ${word} and the color is ${color}"

"Press ${correctKey} for ${condition}"

"You selected ${response}. Correct answer was ${correctKey}."

• Use exact column name (case-sensitive)
• Wrap in ${} brackets
• Can combine with literal text
• Multiple variables in same property allowed

​

Mapping to Multiple Elements

• Header text: ”$”
• Center display: ”$”
• Footer reminder: “Remember: $”

​

Multiple Columns in One Element

Text content: "${condition}: Press ${correctKey} if you see ${targetWord}"

• condition: “Congruent”
• correctKey: “F”
• targetWord: “RED”

​

Import and Export

​

Importing CSV Data

1. Create spreadsheet with trial data
2. First row = column names (variable names)
3. Subsequent rows = trial data
4. Save as CSV (comma-separated values)

word,color,congruent,correctKey
RED,red,yes,F
RED,yellow,no,J
BLUE,blue,yes,J
BLUE,red,no,F

1. Variables view → Import button
2. Select CSV file
3. Map CSV columns to variable columns (if names don’t match exactly)
4. Preview import
5. Confirm - data fills spreadsheet

​

Bulk Data Entry

1. Generate data in Excel using formulas
2. Example: Counterbalanced trial order
3. Export as CSV
4. Import to Cajal

• Randomize: =RAND() then sort by random column
• Repeat pattern: =MOD(ROW()-2, 4)+1 for 1,2,3,4 repeating
• Lookup: =VLOOKUP() to match stimulus to correct response

​

Exporting for Backup

1. Variables view → Export button
2. Choose format (CSV or Excel)
3. Download file
4. Store in version control or share with collaborators

• Backup before major changes
• Share trial list with co-authors
• Document exact stimulus order
• Recreate experiment elsewhere

​

Using Spreadsheet Software to Prepare Data

• Familiar interface
• Advanced formulas and functions
• Conditional formatting for QC
• Scripts for automation (e.g., Python pandas)
• Collaboration features (Google Sheets)

1. Design trial structure in Excel
2. Generate/randomize trials
3. Add formulas for counterbalancing
4. Quality check (conditional formatting to spot errors)
5. Export as CSV
6. Import to Cajal

• 4 conditions (A, B, C, D)
• Each participant sees random order
• Use Excel RAND() and SORT to create randomized lists
• Export multiple CSV files (one per participant order)

​

Randomization

​

Randomizing Trial Order

1. Variables view → Randomization settings
2. Toggle “Randomize trial order”
3. Choose randomization method:
   • Complete randomization - Pure random shuffle
   • Block randomization - Randomize within blocks
   • Constrained randomization - Prevent certain orders

• Each participant sees trials in different order
• Variables spreadsheet order is template, not actual presentation order
• Prevents order effects, practice effects, fatigue confounds

​

Shuffling Rows

1. Click “Shuffle Rows”
2. Rows reorder randomly
3. This changes template order (affects all participants unless per-participant randomization enabled)

• Create random order as default
• Shuffle between pilot sessions
• Generate randomized export

​

Random Sampling

• 100 total stimuli, show 50 random each participant
• Reduce experiment length
• Vary difficulty by sampling easy vs. hard trials

1. Variables view → Sampling settings
2. Enable “Sample trials”
3. Set sample size (e.g., 50 out of 100)
4. Choose sampling method:
   • Without replacement - No repeats
   • With replacement - Trials can repeat

• 200 word stimuli defined in variables
• Sample 100 without replacement
• Each participant sees 100 unique words (randomly selected from the 200)
• Different participants see different subset

​

Sampling Options

​

Fixed Number of Trials

• Total trials defined: 200
• Sample size: 80
• Each participant sees: 80 randomly selected

​

With vs. Without Replacement

• Each trial selected at most once
• 80 samples from 200 = 80 unique trials
• No repeats

• Trials can be selected multiple times
• 80 samples from 200 = 80 trials, some may repeat
• Less common for cognitive tasks

​

Weighted Sampling

• Show hard trials more frequently
• Oversample rare conditions
• Adaptive difficulty

1. Add “weight” column to variables
2. Assign weights (e.g., 1 for easy, 3 for hard)
3. Enable weighted sampling
4. Trials selected proportional to weights

​

Repetitions

​

Repeating Entire Variable Set

• Same 40 trials, repeat 4 times = 160 total trials (4 blocks)
• Practice block followed by test blocks

1. Variables view → Repetitions setting
2. Set repetition count (e.g., 4)
3. 40 trials × 4 repetitions = 160 presentations

• If randomization enabled: each repetition randomly ordered
• If not randomized: same order each repetition

​

Multiple Blocks with Same Trials

• Repetition 1: Trials in order A
• Repetition 2: Trials in order B (different random order)
• Repetition 3: Trials in order C
• Repetition 4: Trials in order D

​

Block Intermissions

​

Purpose of Intermissions

• Long experiments (160+ trials) cause fatigue
• Eye strain from continuous focus
• Maintain data quality
• Participant welfare
• Standard practice for long tasks

• Experiments >15 minutes
• Attention-demanding tasks
• High trial counts (>80 trials)

​

Configuring Intermissions

1. Variables view or Frame properties → Intermissions
2. Enable “Block intermissions”
3. Set interval (e.g., “Every 40 trials”)
4. Choose intermission component:
   • Use existing break component
   • Or create new intermission screen

• 160 total trials
• Intermission every 40 trials
• Breaks appear after trial 40, 80, 120
• 4 blocks with 3 breaks

​

Rest Screens Every N Trials

• “Take a break”
• “Press space when ready to continue”
• Progress indicator: “40 out of 160 complete”
• Optional timer: “Minimum 15 second break”

1. Add new Instruction component
2. Add text: “Take a short break”
3. Add text: “Press space to continue when ready”
4. Optional: Add minimum view time (e.g., 15 seconds)

​

Attention Checks

• “What color was the previous stimulus?”
• Must answer correctly to continue
• Detects inattentive participants

1. Create attention check question
2. Mark as intermission component
3. Insert every 30-50 trials
4. Score and flag low-accuracy participants

​

Break Frequency Configuration

• Every 40-60 trials for standard tasks
• Every 20-30 trials for demanding tasks
• Every 80-100 trials for easy tasks

• Task difficulty
• Trial duration (short trials = more frequent breaks)
• Stimulus complexity
• Participant population (children need more breaks)

• Fixed interval: Every N trials exactly
• Time-based: Every X minutes
• Adaptive: Based on performance decline

​

Common Variable Patterns

​

Stroop Task Example

• 40 congruent trials (word matches color)
• 40 incongruent trials (word doesn’t match color)
• 80 neutral trials (word doesn’t denote color)
• Across 4 blocks

• Text element content: ${word}
• Text element color: ${color}
• Correct response: ${correctKey}

​

Memory Task Example

• condition=“old”, block=“study”
• No response required (just encoding)

• condition=“old” or “new”, block=“test”
• correctResponse: “yes” if old, “no” if new

• Study phase: Show only rows where block=“study”
• Test phase: Show only rows where block=“test”

​

Questionnaire Example

• Text element: ${question}
• Likert scale points: Vary based on ${scale} column
• Scoring: Reverse if ${reverse_scored} = “yes”

• Easy to add/remove questions
• Export as CSV for scoring in R/Python
• Randomize question order

​

Variable Substitution Details

​

In Text Elements

Text content: "${word}"

"Press ${correctKey} if the word is ${targetWord}"

"Trial ${trialNumber}: ${condition} condition"

​

In Image Elements

Image source: "${stimulus}.png"

Image source: "faces/${stimulus}.jpg"

Image source: "${stimulus | default.png}"

​

In Feedback Messages

Feedback text: "You pressed ${response}. The correct answer was ${correctKey}."

If correct: "Correct! ${word} was the right answer."
If incorrect: "Incorrect. ${word} was not the correct answer."

​

Special Variables

• ${trialNumber} - Current trial index (1, 2, 3…)
• ${blockNumber} - Current block (if using blocks)
• ${rt} - Reaction time from previous response
• ${accuracy} - Running accuracy percentage
• ${response} - Participant’s most recent response

"Trial ${trialNumber} of 160 complete. Your accuracy so far: ${accuracy}%"

​

Advanced Features

​

Conditional Logic with Variables

If ${difficulty} = "easy": Show easy trial
If ${difficulty} = "hard": Show hard trial

​

Computed Values

Column "congruent" computed from:
  If word = color: "yes"
  Else: "no"

​

Variable-Based Branching

Block 1: ${blockType} = "practice"
  → Show feedback
Block 2: ${blockType} = "test"
  → No feedback

​

Tips and Best Practices

​

Start with Small Test Set

1. Design first 10 rows carefully
2. Test with preview - verify substitution works
3. Check all conditions represented
4. Expand to full set only after testing

​

Use Descriptive Column Names

• stimulus, correctResponse, condition, blockNumber

• col1, x, data, stuff

​

Check Variable Substitution in Preview

1. Run preview with first 5-10 trials
2. Check each trial shows expected values
3. Verify images load correctly
4. Confirm correct responses match stimuli

• Typo in column name: ${correctkey} vs ${correctKey}
• Missing images: filename doesn’t match media library
• Wrong column mapped to property

​

Keep Backup of Variable Data

1. Export variables to CSV
2. Save with version/date: stroop_variables_2024-11-27.csv
3. Commit to version control (Git) if using

​

Document Your Variable Scheme

• What each column represents
• Value coding (e.g., “F” = red, “J” = green)
• Trial structure (blocks, conditions)
• Counterbalancing scheme

STROOP VARIABLES
- word: Display word (RED, BLUE, GREEN, YELLOW)
- color: Text color (red, blue, green, yellow)
- congruent: yes (match) or no (mismatch)
- correctKey: F (red/green), J (blue/yellow)
- Trials 1-40: Block 1
- Trials 41-80: Block 2
...

​

Use Spreadsheet QC Techniques

• Conditional formatting - Highlight errors (e.g., correctKey not F or J)
• Data validation - Restrict values (dropdown: F, J only)
• Formulas - Auto-compute derived values
• Pivot tables - Check trial counts per condition

• Imbalanced conditions
• Missing values
• Typos in categories
• Incorrect response mappings

​

Next Steps