Skip to content

Conversation

@a-hurst
Copy link
Owner

@a-hurst a-hurst commented Feb 9, 2026

PR Description

This PR adds a new API for flexibly specifying custom block types and block sequences for experiments with more complex designs. The basic Block API has already been tested and refined in multiple different projects (e.g. CAST, ExoInstructions, Rotation_Maillet2024) and has been cleaned up for proper integration here.

Custom structures are specified in the task's _independent_variables.py file. If the variable structure exists and is defined as a list of Block objects, the runtime will generate blocks and trials using the given structure:

exp_factors = FactorSet({
    'sequence_type': ['practiced', 'unpracticed'],
})
practiced_only = exp_factors.override({'sequence_type': ['practiced']})

structure = [
     Block(exp_factors, label='exposure', trials=18),
     Block(practiced_only, label='training', trials=90),
     Block(exp_factors, label='test', trials=60),
]

If no structure is defined, KLibs will generate blocks of trials as usual.

Along with the new structure API, a new runtime parameter P.max_trials_per_block has been added for temporarily limiting the number of trials to run during each block. This is to make it easier to test progression through blocks during development without needing to change the trial count of each block separately (and then change them all back after). Additionally, the existing runtime parameter P.trials_per_block is now updated at the start of each block to reflect the block's actual trial count.

Furthermore, to better support tasks with variable-length practice blocks (e.g. ending once a participant meets a given performance threshold), a new exception type TerminateBlock has been added that will immediately end the current block when raised.

The structure API currently only supports single session projects, but is designed with future support for multi-session projects in mind!

Merge Checklist

  • the PR has been reviewed and all comments are resolved
  • all CI checks pass
  • (if applicable): the PR description includes the phrase closes #<issue-number> to automatically close an issue
  • (if applicable): bug fixes, new features, or API changes are documented in CHANGELOG.rst

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant