Skip to main content

Matrix Reasoning

Version: v1 (current)

A Raven-style fluid reasoning task in which participants complete a visual pattern by selecting the answer tile that fits the missing piece of a matrix.

Overview​

Matrix Reasoning is a pattern-completion task that measures fluid intelligence, the ability to reason about novel problems independently of prior knowledge or verbal ability. Each item presents a single stimulus image (the matrix or pattern with a missing element) together with a set of answer tiles. The participant studies the pattern, infers the underlying rule, and clicks the tile that correctly completes it.

Unlike verbal or knowledge-based reasoning measures, matrix items rely on perceptual and abstract relations such as progression, addition, distribution, and analogy across rows and columns. Because the rules are conveyed entirely through the image, the format minimizes language and cultural loading and is widely used as a culture-reduced index of reasoning ability.

This implementation is fully manual and content-free. It ships with no bundled stimuli and no item templates: the researcher uploads their own stimulus and option images and builds each item in the configuration spreadsheet. The task is invalid until at least one scored item has been defined, which gives full control over the difficulty, length, and design of the matrix set.

Scientific Background​

Classic Findings:

  • Fluid Intelligence Marker: Matrix-style reasoning is one of the strongest single indicators of general fluid ability (Gf)
  • g Loading: Pattern-completion tasks load heavily on general intelligence (g) in factor-analytic studies
  • Culture-Reduced: Minimal verbal and cultural content makes the format suitable for cross-population comparison
  • Developmental Trajectory: Performance rises through childhood and adolescence, peaks in early adulthood, and declines gradually in later life
  • Working Memory Relationship: Correlates moderately with working-memory capacity, reflecting shared demands on rule maintenance and manipulation

Key Mechanisms:

  • Rule Induction: Identifying the relations that govern changes across rows and columns
  • Relational Reasoning: Integrating multiple relations simultaneously to constrain the answer
  • Hypothesis Testing: Generating and checking candidate completions against the pattern
  • Selective Attention: Suppressing distractor tiles that satisfy only part of the rule

Construct Notes:

  • Matrix tasks are typically interpreted as measures of inductive reasoning and fluid intelligence
  • Item difficulty is driven by the number of rules and the perceptual similarity of distractors
  • Performance is sensitive to time pressure, which can shift the construct toward processing speed

Why Researchers Use This Task​

  1. Individual-Differences Research: Index fluid intelligence as a predictor or covariate in cognitive studies
  2. Developmental and Aging Research: Track the rise and decline of reasoning ability across the lifespan
  3. Clinical and Neuropsychological Assessment: Characterize reasoning in conditions affecting cognition
  4. Cross-Cultural Studies: Provide a reduced-language reasoning measure for diverse samples
  5. Intervention and Training Studies: Measure transfer to fluid reasoning following cognitive training
  6. Covariate Control: Statistically adjust for general ability when interpreting performance on other tasks

Current Implementation Status​

Fully Implemented:

  • ✅ Fully manual item authoring: upload your own stimulus and option images and build items in a spreadsheet
  • ✅ Multi-file image upload that populates the image dropdowns for both stimulus and option cells
  • ✅ Reorder-safe answer key: the correct answer references an option id, not a tile position
  • ✅ Optional practice block with per-trial correct/incorrect feedback
  • ✅ Per-item response timeout and per-block countdown timer (both optional)
  • ✅ Optional minimum time before response: a short answer lockout right after each item appears, to discourage accidental immediate clicks
  • ✅ Configurable stimulus image width and answer tile size
  • ✅ Areas of interest (AOIs) emitted for the stimulus and each answer tile for eye-tracking alignment
  • ✅ Automated, reorder-safe scoring with a per-block summary artifact
  • ✅ Hard validation that blocks save and preview on malformed items (never a silent drop)
  • ✅ Full moderation support (unmoderated, moderated, strictly moderated)

Not Yet Implemented:

  • ❌ Bundled stimulus sets or item templates (the task is intentionally content-free)
  • ❌ AI-assistant item generation
  • ❌ Adaptive administration based on performance

Configuration Parameters​

Display​

ParameterTypeDefaultDescription
stimulus_image_max_width_pxnumber480Maximum display width of the stimulus image in pixels
answer_tile_size_pxnumber120Display size of each answer tile in pixels

Timing​

ParameterTypeDefaultDescription
response_timeout_msnumber0Default time limit per item in milliseconds (0 = no limit). A per-item response_timeout_ms can override this.
block_time_limit_msnumber0Per-block countdown in milliseconds (0 = no limit). Started at the first item of a block and restarted at main entry; when it elapses the block ends.
matrix_min_time_before_response_msnumber0Minimum time before response: an answer lockout, in milliseconds, applied after every item appears (0 = no lockout). This is not a response deadline and has no per-item override. Answer tiles stay visible during the lockout, only their styling changes; a tile click during this window is captured and logged but never accepted as the answer.

Practice​

ParameterTypeDefaultDescription
practice_enabledbooleanfalseRun a practice block before the main task
feedback_in_practicebooleantrueShow correct/incorrect feedback after each practice item

Instructions​

ParameterTypeDefaultDescription
main_instructionshtml''Main task instructions (rich text)
practice_instructionshtml''Pre-practice instruction screen (shown only when practice is enabled)
trials_instructionshtml''Pre-main instruction screen shown after practice (shown only when practice is enabled)
hint_instructionshtml''Hint/help text (rich text)

Items​

ParameterTypeDefaultDescription
matrix_itemsarrayemptyA single array of all items. Practice and main items are distinguished by each item's block field ('practice' or 'main').

Each item carries: id (internal uuid, never shown in the editor, exported as stimulus_id), stimulus_image_url (canonical image reference), options (array of {id, url}), correct_option_id (references an option id, reorder-safe, not a position), block ('practice' or 'main'), and an optional per-item response_timeout_ms override.

The item editor exposes a spreadsheet with the columns: Stimulus, Option 1 through Option 8, Correct, Block (practice/main), and Timeout (ms). The image columns are dropdowns whose source is the set of uploaded image references; the cell stores the full canonical reference. The internal item id is not a column: it is preserved invisibly by content reconciliation in the serializer, where a row joins to a prior item by its stimulus reference plus its set of option references and keeps its id, while new items and options receive a fresh uuid.

Validation. Save and preview are both blocked (never a silent drop) when a row has no stimulus, has fewer than two options, has a blank Correct, has a Correct that is not among its options, or has duplicate option references. The whole configuration is invalid when there is no runnable main (scored) item, that is, an empty table or a practice-only table. Read-only studies disable the form and lock the sheet.

Data Output​

Markers​

The task emits a trial_order marker at start (order = array of item ids). Per-item markers include stimulus_shown, stimulus_aoi, response, feedback_shown (practice only), and the centrally emitted response_recorded. When matrix_min_time_before_response_ms is set, a tile click that lands during the lockout is captured as an invalid_response marker (interpretation: "locked_out") instead of being accepted: it is record-only and never selects an answer or advances the item. System markers emitted by the runner and base around the structure of the task include <name>_main_instruction_start/_end, <name>_practice_instruction_start/_end, <name>_trials_instruction_start/_end, <name>_practice_phase_start/_end, <name>_main_phase_start/_end, <name>_practice_trial_start/_end, <name>_trial_start/_end, and <name>_hint_show/_hide (where <name> is the task slug).

{
  "type": "stimulus_shown",
  "ts": "2026-01-01T00:00:01.000Z",
  "hr": 1234.56,
  "data": {
    "stimulus_id": "8f2c1a4e-...",
    "stimulus_image_url": "https://.../matrix-001.png",
    "options_count": 6,
    "correct_option_id": "b71d...",
    "block": "main"
  }
}

The stimulus_aoi marker reports normalized bounds for eye-tracking alignment:

{
  "type": "stimulus_aoi",
  "data": {
    "stimulus_bounds": { "x_pct": 0.0, "y_pct": 0.0, "width_pct": 0.0, "height_pct": 0.0 },
    "aois": {
      "<option_id>": { "x_pct": 0.0, "y_pct": 0.0, "width_pct": 0.0, "height_pct": 0.0 }
    }
  }
}

Response Data​

Emitted via the response marker (trial grain). Latency is high-resolution and mapped to *_recording_ms on export:

{
  "trial_index": 1,
  "is_practice": false,
  "stimulus_id": "8f2c1a4e-...",
  "source": "button",
  "stimulus_image_url": "https://.../matrix-001.png",
  "options_count": 6,
  "correct_option_id": "b71d...",
  "correct_option_url": "https://.../option-3.png",
  "response_value": "b71d...",
  "selected_option_id": "b71d...",
  "selected_option_index": 2,
  "selected_option_url": "https://.../option-3.png",
  "response_correct": true,
  "responded": true,
  "block": "main",
  "stimulus_onset_hr": 1234.56,
  "response_hr": 6054.32,
  "latency_ms": 4820
}

source is one of button, timeout, moderator_advance, or block_timeout (an item still on screen when the per-block countdown elapsed, recorded as a non-response rather than dropped). For any non-response (timeout, moderator advance, or block-timer cutoff), response_value, selected_option_id, and selected_option_index are null, response_correct is null (never false or 0), and latency_ms is omitted. Practice items carry practice_trial_index in place of trial_index.

Summary Artifact​

Emitted at task end as matrix_reasoning_summary_<taskIndex>.json:

{
  "task_kind": "matrix_reasoning",
  "task_index": 0,
  "main": {
    "items_total": 12,
    "items_administered": 12,
    "items_attempted": 11,
    "timeouts": 1,
    "total_correct": 8,
    "accuracy_attempted": 0.727,
    "accuracy_administered": 0.667,
    "median_latency_ms": 4120,
    "trials": [
      {
        "trial_index": 1,
        "stimulus_id": "8f2c1a4e-...",
        "response_correct": true,
        "responded": true,
        "source": "button",
        "block": "main",
        "latency_ms": 4820
      }
    ]
  },
  "practice": {
    "items_total": 2,
    "items_administered": 2,
    "items_attempted": 2,
    "timeouts": 0,
    "total_correct": 2,
    "accuracy_attempted": 1.0,
    "accuracy_administered": 1.0,
    "median_latency_ms": 3010,
    "trials": []
  }
}

Per-block stats are: items_total (configured count), items_administered (counted at presentation), items_attempted (responded count), timeouts, total_correct, accuracy_attempted (omitted when there were 0 attempts), accuracy_administered, and median_latency_ms (null when there are no latencies). Timeouts and never-administered items are excluded from accuracy and reaction time; they are never scored as 0. The practice object is present only when a practice block was administered. Each entry in trials carries trial_index, stimulus_id, response_correct, responded, source, block, and (only for a real response) latency_ms, so every summary row can be joined back to its event/export row.

Example Research Configurations​

Untimed Manual Set​

Items: Researcher-uploaded matrix set, all in the main block
Timing: Self-paced (response timeout = 0, block limit = 0)
Practice: Practice block enabled with feedback
Scoring: Total correct and accuracy across administered items

Timed Block (Power Under Time Limit)​

Items: Matrix set in the main block
Timing: Per-block countdown (e.g. block_time_limit_ms = 600000 for 10 minutes)
Practice: Practice block enabled with feedback
Analysis: Items administered, accuracy, and median latency under the block limit

Per-Item Speeded Administration​

Items: Matrix set in the main block
Timing: Per-item response timeout (e.g. response_timeout_ms = 20000)
Practice: Practice block enabled to familiarize participants with the pace
Analysis: Speed-accuracy trade-off; timeouts excluded from accuracy and RT

Practice-Free Reasoning Block​

Items: Matrix set in the main block only
Practice: Disabled
Timing: Self-paced
Use: Brief reasoning block embedded within a larger battery

Participant Experience​

  1. Instructions: The configured main instructions (rich text) describe the task, for example: "Each puzzle is missing a piece. Look at the pattern, then click the tile that best completes it."

  2. Practice Block (if practice_enabled):

    • Pre-practice instruction screen (practice_instructions)
    • For each practice item: study the stimulus image, then click one of the answer tiles
    • When feedback_in_practice is on, receive correct/incorrect feedback after each choice
    • Practice items are the items whose block is 'practice'

  3. Transition (if practice enabled): A pre-main instruction screen (trials_instructions) is shown before the scored trials begin.

  4. Main Task:

    • For each item:
      • View the stimulus image (the pattern with a missing piece)
      • Read the set of answer tiles
      • If matrix_min_time_before_response_ms is set, the tiles are briefly shown dimmed (still visible and clickable) right after the item appears; a click during this window does not register as an answer
      • Click the tile that completes the pattern
      • No feedback during the main task
    • An optional per-item response timeout advances a single item automatically
    • An optional per-block countdown ends the block when it elapses (practice → main, main → task complete); an item still on screen at that moment is recorded as a block_timeout non-response, so it still appears in the events and summary

  5. Completion: A summary artifact is generated with per-block statistics and per-trial results.

Design Recommendations​

General Guidelines​

  • Order Items by Difficulty: Place easier items first so participants learn the format before harder rules
  • Use a Practice Block: A short practice block with feedback ensures participants understand the click-to-complete format
  • Choose Distractors Carefully: Plausible distractors that satisfy only part of the rule make items more discriminating
  • Size for Legibility: Set stimulus_image_max_width_px and answer_tile_size_px so fine pattern details remain visible
  • Decide on Timing Deliberately: Self-pacing measures power; per-item or per-block limits introduce a speed component and shift the construct
  • Consider a Short Answer Lockout: A small matrix_min_time_before_response_ms (e.g. 300 ms) reduces accidental immediate clicks without adding real time pressure; it is a lockout, not a response deadline, and does not affect measured latency

Scoring and Interpretation​

  • Accuracy: accuracy_attempted reflects performance on items the participant actually answered; accuracy_administered reflects performance across all presented items
  • Timeouts: Treated as non-responses, excluded from accuracy and reaction time, never scored as incorrect
  • Latency: median_latency_ms summarizes response speed on answered items and is robust to slow outliers
  • Construct Caution: Heavy time pressure can turn a reasoning measure into a speed measure; interpret timed results accordingly

Common Issues and Solutions​

IssueSolution
Configuration will not save or previewCheck the validation rules: every row needs a stimulus, at least two options, a non-blank Correct that is one of its options, and no duplicate option references
"No runnable main item" errorAdd at least one item whose Block is main; a practice-only or empty table is invalid
Correct answer seems misassigned after reordering tilesThe answer key references an option id, not a position, so reordering tiles is safe; confirm the Correct cell still points to the intended option image
Image dropdowns are emptyUpload stimulus and option images first; the dropdown source is the set of uploaded image references
Fine pattern details hard to seeIncrease stimulus_image_max_width_px and answer_tile_size_px
Many timeoutsIncrease or remove response_timeout_ms / block_time_limit_ms; remember timeouts are excluded from accuracy, not scored as wrong
Ceiling effects (many perfect scores)Add harder items with more rules or more similar distractors, or introduce a time limit

See Also​