Add custom block structure API #39
Open
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
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
BlockAPI 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.pyfile. If the variablestructureexists and is defined as a list of Block objects, the runtime will generate blocks and trials using the given structure: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_blockhas 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 parameterP.trials_per_blockis 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
TerminateBlockhas 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
closes #<issue-number>to automatically close an issue