Task_file Module

class ActionObservation(const)

Bases: TaskFile

The TaskFile class is class for creating TaskFile files for different tasks :param const: module for constants

make_task_file(run_number=None, task_dur=30, trial_dur=14, iti_dur=1, file_name=None)

Create an action-observation task file (knot-tying videos).

Parameters:

• run_number (int) – Run number, used to select which knot stimulus to show.

• task_dur (float) – Total task duration in seconds.

• trial_dur (float) – Duration of each video trial in seconds.

• iti_dur (float) – Inter-trial interval duration in seconds.

• file_name (str) – Name of the file to save the task data.

Returns:

pd.DataFrame – Task information as a DataFrame.

class Affective(const)

Bases: TaskFile

The TaskFile class is class for creating TaskFile files for different tasks :param const: module for constants

make_task_file(task_dur=30, trial_dur=1.6, iti_dur=0.4, file_name=None, hand='right', responses=[1, 2])

Create an affective-picture task file (judge pleasant vs unpleasant).

Parameters:

• task_dur (float) – Total task duration in seconds.

• trial_dur (float) – Duration each image is displayed in seconds.

• iti_dur (float) – Inter-trial interval duration in seconds.

• file_name (str) – Name of the file to save the task data.

• hand (str) – Hand used for response (‘right’ or ‘left’).

• responses (list) – Response keys for [unpleasant, pleasant].

Returns:

pd.DataFrame – Task information as a DataFrame.

class AuditoryNarrative(const)

Bases: TaskFile

The TaskFile class is class for creating TaskFile files for different tasks :param const: module for constants

make_task_file(task_dur=30, trial_dur=30, iti_dur=0, file_name=None, run_number=None)

Create an auditory-narrative task file. Each run plays a distinct narrative clip (narrative_NN.wav) selected by run_number.

Parameters:

• task_dur (float) – Total task duration in seconds.

• trial_dur (float) – Duration of each audio clip in seconds.

• iti_dur (float) – Inter-trial interval duration in seconds.

• file_name (str) – Name of the file to save the task data.

• run_number (int) – Run number, used to select which audio clip to play.

Returns:

pd.DataFrame – Task information as a DataFrame.

Raises:

ValueError – If run_number is None or exceeds the number of available narrative clips.

class DemandGrid(const)

Bases: TaskFile

The TaskFile class is class for creating TaskFile files for different tasks :param const: module for constants

generate_sequence(grid_size, num_steps, num_boxes_lit)

Generate the original sequence of lit-up boxes, ensuring adjacency between boxes in each step and no reuse of positions across the entire sequence.

Parameters:

• grid_size (tuple) – Size of the grid (rows, cols).

• num_steps (int) – Number of steps in the sequence.

• num_boxes_lit (int) – Number of boxes lit up per step.

Returns:

list – Original sequence of steps, where each step is a list of positions.

get_adjacent_positions(pos, grid_size)

Get all adjacent positions within the grid boundaries.

Parameters:

• pos (tuple) – Current position (x, y).

• grid_size (tuple) – Size of the grid (rows, cols).

Returns:

list – List of adjacent positions.

make_task_file(hand='right', responses=[1, 2], grid_size=(3, 4), num_steps=3, num_boxes_lit=2, task_dur=30, trial_dur=7, question_dur=3, sequence_dur=4, iti_dur=0.5, condition=None, file_name=None)

Create a task file with the specified parameters.

Parameters:

• hand (str) – Hand used for response (‘right’ or ‘left’).

• responses (list) – Response keys for left and right.

• grid_size (tuple) – Size of the grid (rows, cols).

• num_steps (int) – Number of steps in the sequence.

• num_boxes_lit (int) – Number of boxes lit up per step.

• task_dur (float) – Total task duration in seconds.

• trial_dur (float) – Duration of each trial.

• question_dur (float) – Duration of the question phase.

• sequence_dur (float) – Duration of the sequence presentation phase.

• iti_dur (float) – Inter-trial interval duration.

• file_name (str) – Name of the file to save the task data.

Returns:

pd.DataFrame – Task information as a DataFrame.

modify_sequence(sequence, grid_size)

Modify the original sequence to create a new sequence for comparison, ensuring adjacency and uniqueness within the modified step. If a step cannot be modified due to lack of valid adjacent positions, try another step.

The modified sequence is constrained to have the same number of connected components as the original, so the distractor is not visually distinguishable by spatial continuity alone.

Parameters:

• sequence (list) – Original sequence of steps.

• grid_size (tuple) – Size of the grid (rows, cols).

Returns:

list – Modified sequence of steps.

class FauxPas(const)

Bases: TaskFile

The TaskFile class is class for creating TaskFile files for different tasks :param const: module for constants

make_task_file(hand='right', responses=[1, 2], run_number=None, task_dur=30, trial_dur=14, iti_dur=1, story_dur=10, question1_dur=4, text_height=1.25, file_name=None, stim_file=None, condition=None, half=None, stimulus_seed=None, exclude_stimuli=None)

class FingerRhythmic(const)

Bases: TaskFile

The TaskFile class is class for creating TaskFile files for different tasks :param const: module for constants

make_task_file(hand='right', responses=[1], run_number=None, task_dur=70, trial_dur=35, iti_dur=0, ioi=0.6, file_name=None)

class FingerSequence(const)

Bases: TaskFile

The TaskFile class is class for creating TaskFile files for different tasks :param const: module for constants

generate_sequence()

make_task_file(hand='bimanual', task_dur=30, trial_dur=3.25, iti_dur=0.5, file_name=None)

Create a finger-sequence task file (press a 6-digit sequence in order). Each digit (1-4) is the finger/key to press; scoring compares the pressed key number directly to the sequence digit.

Parameters:

• hand (str) – Hand(s) used for response (‘bimanual’, ‘right’, or ‘left’).

• task_dur (float) – Total task duration in seconds.

• trial_dur (float) – Duration of each trial in seconds.

• iti_dur (float) – Inter-trial interval duration in seconds.

• file_name (str) – Name of the file to save the task data.

Returns:

pd.DataFrame – Task information as a DataFrame.

class FlexionExtension(const)

Bases: TaskFile

The TaskFile class is class for creating TaskFile files for different tasks :param const: module for constants

make_task_file(task_dur=30, stim_dur=2, file_name=None)

Create a flexion-extension (toe movement) task file. The block is paced by a cue that alternates between ‘flexion’ and ‘extension’ every stim_dur seconds, written as one row per cue. The runtime just shows each cue for its duration.

Parameters:

• task_dur (float) – Total duration of the block in seconds.

• stim_dur (float) – Duration each cue (‘flexion’/’extension’) is shown.

• file_name (str) – Name of the file to save the task data.

Returns:

pd.DataFrame – Task information as a DataFrame.

class MotorLocalizer(const)

Bases: TaskFile

The TaskFile class is class for creating TaskFile files for different tasks :param const: module for constants

make_task_file(task_dur=30, trial_dur=1, condition=['hand', 'foot', 'tongue'], file_name=None)

Create a motor-localizer task file. The block is split into one equal segment per condition (segment_dur = task_dur / len(condition), e.g. 10 s each for three conditions in a 30 s block) and the condition order is RANDOMISED for the block. Within a condition’s segment the circle toggles present (trial_type=1) / absent (trial_type=0) every trial_dur seconds, which paces the movement.

What circle-present vs circle-absent means (e.g. move right vs move left, or move vs hold) is decided per experiment and explained to the participant in training – it is deliberately NOT encoded here. This is only the default layout; the runtime renders whatever the file specifies, so a hand-written file can use any condition order, segment length or on/off pattern.

Parameters:

• task_dur (float) – Total block duration in seconds.

• trial_dur (float) – Circle on/off toggle interval within a segment (seconds).

• condition (str or list) – Condition label(s), e.g. body parts; each gets an equal, randomly ordered share of the block.

• file_name (str) – Name of the file to save the task data.

Returns:

pd.DataFrame – Task information as a DataFrame.

class Movie(const)

Bases: TaskFile

The TaskFile class is class for creating TaskFile files for different tasks :param const: module for constants

make_task_file(run_number=None, task_dur=30, trial_dur=30, iti_dur=0, file_name=None, stim_file=None, condition=None, media_scale=0.4)

Create a movie-watching task file (passive viewing of a 30s clip).

Parameters:

• run_number (int) – Run number, used to select which clip to show.

• task_dur (float) – Total task duration in seconds.

• trial_dur (float) – Duration of each clip in seconds.

• iti_dur (float) – Inter-trial interval duration in seconds.

• file_name (str) – Name of the file to save the task data.

• stim_file (str) – Optional path to a custom stimulus CSV.

• condition (str) – Which clips to use (‘romance’, ‘nature’, or ‘landscape’). If None, all non-practice clips are used.

• media_scale (float) – Clip width as a fraction of the window width.

Returns:

pd.DataFrame – Task information as a DataFrame.

class NBack(const)

Bases: TaskFile

The TaskFile class is class for creating TaskFile files for different tasks :param const: module for constants

make_task_file(hand='right', responses=[1, 2], task_dur=30, trial_dur=2, iti_dur=0.5, picture_scale=1.0, n_back=2, stim=['9.jpg', '11.jpg', '18.jpg', '28.jpg'], file_name=None)

Create an n-back working-memory task file.

Parameters:

• hand (str) – Hand used for response (‘right’ or ‘left’).

• responses (list) – Response keys for [match, no-match].

• task_dur (float) – Total task duration in seconds.

• trial_dur (float) – Duration each stimulus is displayed in seconds.

• iti_dur (float) – Inter-trial interval duration in seconds.

• picture_scale (float) – Scaling factor for stimulus images (>1 enlarges).

• n_back (int) – How many items back a match refers to (2 = classic 2-back).

• stim (list) – List of stimulus image filenames to draw from.

• file_name (str) – Name of the file to save the task data.

Returns:

pd.DataFrame – Task information as a DataFrame.

class OddBall(const)

Bases: TaskFile

The TaskFile class is class for creating TaskFile files for different tasks :param const: module for constants

make_task_file(hand='right', responses=[1, 2], task_dur=30, trial_dur=0.15, iti_dur=0.85, file_name=None)

Create an oddball-detection task file (respond only to a red ‘K’).

Parameters:

• hand (str) – Hand used for response (‘right’ or ‘left’).

• responses (list) – Response keys.

• task_dur (float) – Total task duration in seconds.

• trial_dur (float) – Duration the stimulus is displayed in seconds.

• iti_dur (float) – Inter-trial interval duration in seconds.

• file_name (str) – Name of the file to save the task data.

Returns:

pd.DataFrame – Task information as a DataFrame.

class PassageListening(const)

Bases: TaskFile

The TaskFile class is class for creating TaskFile files for different tasks :param const: module for constants

make_task_file(run_number, condition='intact', task_dur=30, trial_dur=14.5, iti_dur=0.5, file_name=None, stim_file=None)

Create a passage-listening task file (intact vs degraded speech).

Parameters:

• run_number (int) – Run number, used to select which passages to play.

• condition (str) – Which condition to include (‘intact’ or ‘degraded’).

• task_dur (float) – Total task duration in seconds.

• trial_dur (float) – Duration of each passage in seconds.

• iti_dur (float) – Inter-trial interval duration in seconds.

• file_name (str) – Name of the file to save the task data.

• stim_file (str) – Optional path to a custom stimulus CSV.

Returns:

pd.DataFrame – Task information as a DataFrame.

class RMET(const)

Bases: TaskFile

The TaskFile class is class for creating TaskFile files for different tasks :param const: module for constants

make_task_file(hand='right', responses=[1, 2, 3, 4], run_number=None, task_dur=30, trial_dur=6, iti_dur=1.5, option_text_height=1.2, option_position_scale=1.0, picture_scale=0.7, show_last_seconds=0, file_name=None, stim_file=None, condition=None, half=None, stim=None)

Create an RMET task file (Reading the Mind in the Eyes; emotion or age).

Parameters:

• hand (str) – Hand used for response (‘right’ or ‘left’).

• responses (list) – Response keys mapped to the four options.

• run_number (int) – Run number, used to select which stimuli to present.

• task_dur (float) – Total task duration in seconds.

• trial_dur (float) – Duration each stimulus is displayed in seconds.

• iti_dur (float) – Inter-trial interval duration in seconds.

• option_text_height (float) – Height of the answer-option text in degrees of visual angle.

• option_position_scale (float) – Spatial scaling for option positions (<1 brings them closer).

• picture_scale (float) – Scaling of the eye-region image (>1 enlarges).

• show_last_seconds (float) – If >0, show options only for the final N seconds of the trial.

• file_name (str) – Name of the file to save the task data.

• stim_file (str) – Optional path to a custom stimulus CSV.

• condition (str) – If set, only trials of this condition are included (‘emotion’ or ‘age’).

• half (str) – Optional split of the stimulus set into halves.

• stim (pd.DataFrame) – Optional pre-loaded stimulus table.

Returns:

pd.DataFrame – Task information as a DataFrame.

class Reading(const)

Bases: TaskFile

The TaskFile class is class for creating TaskFile files for different tasks :param const: module for constants

make_task_file(run_number=None, condition='sentences', task_dur=30, trial_dur=5.8, iti_dur=0.2, file_name=None, stim_file=None)

Create a reading task file (sentences or nonwords, shown word by word).

Parameters:

• run_number (int) – Run number, used to select which sentences to show.

• condition (str) – ‘sentences’ or ‘nonwords’.

• task_dur (float) – Total task duration in seconds.

• trial_dur (float) – Duration of each sentence presentation in seconds.

• iti_dur (float) – Inter-trial interval duration in seconds.

• file_name (str) – Name of the file to save the task data.

• stim_file (str) – Optional path to a custom stimulus CSV.

Returns:

pd.DataFrame – Task information as a DataFrame.

class Rest(const)

Bases: TaskFile

The TaskFile class is class for creating TaskFile files for different tasks :param const: module for constants

make_task_file(task_dur=30, file_name=None)

Create a rest task file (single fixation block, no stimuli or response).

Parameters:

• task_dur (float) – Total duration of the rest block in seconds.

• file_name (str) – Name of the file to save the task data.

Returns:

pd.DataFrame – Task information as a DataFrame.

class SemanticPrediction(const)

Bases: TaskFile

The TaskFile class is class for creating TaskFile files for different tasks :param const: module for constants

make_task_file(hand='right', responses=[1, 2], run_number=None, task_dur=30, trial_dur=15, sentence_dur=2, file_name=None, stim_file=None, stim=None)

Create a semantic-prediction task file (judge whether the final word makes the sentence meaningful).

Parameters:

• hand (str) – Hand used for response (‘right’ or ‘left’).

• responses (list) – Response keys for [meaningful, meaningless].

• run_number (int) – Run number, used to select which sentences to present.

• task_dur (float) – Total task duration in seconds.

• trial_dur (float) – Total duration budgeted for each trial in seconds.

• sentence_dur (float) – Response window for the final word, in seconds.

• file_name (str) – Name of the file to save the task data.

• stim_file (str) – Optional path to a custom stimulus CSV.

• stim (pd.DataFrame) – Optional pre-loaded stimulus table.

Returns:

pd.DataFrame – Task information as a DataFrame.

class SensMotControl(const)

Bases: TaskFile

The TaskFile class is class for creating TaskFile files for different tasks :param const: module for constants

make_task_file(hand='right', responses=[1, 2], run_number=None, task_dur=300, trial_dur=3, question_dur=2, iti_dur=1, file_name=None, stim_file=None, condition=None)

class SerialReactionTime(const)

Bases: TaskFile

The TaskFile class is class for creating TaskFile files for different tasks :param const: module for constants

make_task_file(hand='bimanual', task_dur=30, initial_wait=1.0, trial_dur=0.5, iti_dur=1.0, file_name=None)

class SpatialNavigation(const)

Bases: TaskFile

The TaskFile class is class for creating TaskFile files for different tasks :param const: module for constants

make_task_file(task_dur=30, trial_dur=30, iti_dur=0, file_name=None, run_number=None)

Create a spatial-navigation task file (imagined navigation between two remembered locations).

Parameters:

• task_dur (float) – Total task duration in seconds.

• trial_dur (float) – Duration of the imagination period in seconds.

• iti_dur (float) – Inter-trial interval duration in seconds.

• file_name (str) – Name of the file to save the task data.

• run_number (int) – Run number, used to select which location pair to use.

Returns:

pd.DataFrame – Task information as a DataFrame.

class TaskFile(const)

Bases: object

The TaskFile class is class for creating TaskFile files for different tasks :param const: module for constants

class TheoryOfMind(const)

Bases: TaskFile

The TaskFile class is class for creating TaskFile files for different tasks :param const: module for constants

make_task_file(hand='right', responses=[1, 2], run_number=None, task_dur=30, trial_dur=14, iti_dur=1, story_dur=10, question_dur=4, text_height=1.25, file_name=None, stim_file=None, condition=None)

Create a theory-of-mind task file (story followed by a true/false statement).

Parameters:

• hand (str) – Hand used for response (‘right’ or ‘left’).

• responses (list) – Response keys for [True, False].

• run_number (int) – Run number, used to select stimuli for that run.

• task_dur (float) – Total task duration in seconds.

• trial_dur (float) – Total duration of each trial in seconds.

• iti_dur (float) – Inter-trial interval duration in seconds.

• story_dur (float) – Duration the story is displayed in seconds.

• question_dur (float) – Duration the question is displayed in seconds.

• text_height (float) – Height of the story/question text in degrees of visual angle.

• file_name (str) – Name of the file to save the task data.

• stim_file (str) – Optional path to a custom stimulus CSV.

• condition (str) – If set, only trials of this condition are included (‘belief’ or ‘photo’).

Returns:

pd.DataFrame – Task information as a DataFrame.

class TimePerception(const)

Bases: TaskFile

The TaskFile class is class for creating TaskFile files for different tasks :param const: module for constants

make_task_file(modality='time', responses=[1, 2], task_dur=30, n_trials=None, trial_dur=4, iti_dur=1.0, question_dur=2.0, display_feedback=True, run_number=None, file_name=None, **unused)

Create a time/volume-perception task file (2AFC discrimination).

Parameters:

• modality (str) – Dimension judged: ‘time’ (shorter/longer) or ‘volume’ (quieter/louder).

• responses (list) – Response keys for [left option, right option].

• task_dur (float) – Total block duration in seconds. Used to derive n_trials when n_trials is None.

• n_trials (int) – Number of trials. If None, computed from task_dur as floor(task_dur / (trial_dur + iti_dur)); rounded down to an even number so the two response sides stay balanced.

• trial_dur (float) – Tone + question window duration per trial in seconds.

• iti_dur (float) – Inter-trial interval duration in seconds.

• question_dur (float) – Response window after the tones in seconds.

• display_feedback (bool) – Whether to show green/red trial feedback.

• run_number (int) – Run number; seeds the side-order shuffle.

• file_name (str) – Name of the file to save the task data.

Returns:

pd.DataFrame – Task information as a DataFrame.

class TongueMovement(const)

Bases: TaskFile

The TaskFile class is class for creating TaskFile files for different tasks :param const: module for constants

make_task_file(task_dur=30, trial_dur=1, iti_dur=0, file_name=None)

Create a tongue-movement task file.

Parameters:

• task_dur (float) – Total task duration in seconds.

• trial_dur (float) – Duration of each tongue-movement cycle in seconds.

• iti_dur (float) – Inter-trial interval duration in seconds.

• file_name (str) – Name of the file to save the task data.

Returns:

pd.DataFrame – Task information as a DataFrame.

class VerbGeneration(const)

Bases: TaskFile

The TaskFile class is class for creating TaskFile files for different tasks :param const: module for constants

make_task_file(condition=['read', 'generate'], task_dur=30, trial_dur=2, iti_dur=0.5, order='blocked', file_name=None, stim_file=None)

Create a verb-generation task file.

Parameters:

• condition (str or list) – Which condition(s) to run. A single value (‘read’ or ‘generate’) fills the whole block with one condition. A list (e.g. [‘read’, ‘generate’]) mixes conditions within the block.

• task_dur (float) – Total task duration in seconds.

• trial_dur (float) – Duration each word is displayed in seconds.

• iti_dur (float) – Inter-trial interval duration in seconds.

• order (str) – How to arrange multiple conditions across trials: ‘blocked’ (default) runs each condition in a contiguous chunk in the given order; ‘interleaved’ cycles through them trial by trial; ‘random’ assigns a balanced set in random order. Ignored for a single condition.

• file_name (str) – Name of the file to save the task data.

• stim_file (str) – Optional path to a custom word-list CSV. Defaults to the packaged verb_generation.csv.

Returns:

pd.DataFrame – Task information as a DataFrame.

class VisualSearch(const)

Bases: TaskFile

The TaskFile class is class for creating TaskFile files for different tasks :param const: module for constants

make_task_file(hand='right', responses=[1, 2], task_dur=30, trial_dur=2, iti_dur=0.5, easy_prob=0.5, file_name=None)

Create a visual-search task file (find a canonically-oriented ‘L’).

Parameters:

• hand (str) – Hand used for response (‘right’ or ‘left’).

• responses (list) – Response keys for [target present, target absent].

• task_dur (float) – Total task duration in seconds.

• trial_dur (float) – Duration of each trial in seconds.

• iti_dur (float) – Inter-trial interval duration in seconds.

• easy_prob (float) – Probability of an easy trial (4 stimuli vs. 8).

• file_name (str) – Name of the file to save the task data.

Returns:

pd.DataFrame – Task information as a DataFrame.

add_start_end_times(dataframe, offset, run_time=None)

Lay blocks end-to-end using each row’s own instruction_dur + task_dur, so blocks in a run can have different lengths.

Parameters:

• dataframe (dataframe) – the run dataframe (rows already in final order, with ‘instruction_dur’ and ‘task_dur’ columns)

• offset (float) – start time of the first block

• run_time (float) – if set, the last block’s end_time is extended to this (e.g. to capture activity overhang from the final task in a run)

Returns:

dataframe (dataframe) – dataframe with start_time and end_time columns

get_task_class(name, exp_dir=None)

Creates an object of the task class based on the task name :param name: name of the task :type name: str :param exp_dir: path to the experiment directory :type exp_dir: str, path, optional

Returns:

class_name (str) – class name for task

make_run_file(task_list, tfiles, offset=0, instruction_dur=5, task_dur=30, run_time=None, keep_in_middle=None, exp_dir=None)

Make a single run file.

Parameters:

• task_list (list) – Task names for this run (one per block).

• tfiles (list) – Task-file name for each block, matching task_list.

• offset (float) – Start time of the first block (e.g. to skip dummy scans).

• instruction_dur (float or list) – Instruction-period duration. A scalar applies to every block; a per-task list gives each block its own.

• task_dur (float or list) – Task duration. A scalar applies to every block; a per-task list lets a run mix blocks of different lengths (e.g. task_dur=[30, 30, 70]).

• run_time (float) – If set, the last block’s end_time is extended to this, so the run lasts run_time (captures overhang from the final task).

• keep_in_middle (list) – Task names to keep away from the first/last block (passed to shuffle_rows).

• exp_dir (str, Path) – Experiment directory, used to load the task table.

Any list passed for instruction_dur/task_dur must have one value per task. The per-task durations are stored as columns and travel with their task through the row shuffle; blocks are then laid out end-to-end by their own duration.

Returns:

pd.DataFrame – the run file (one row per block, with start/end times).

move_edge_tasks_to_middle(dataframe, keep_in_middle)

Moves tasks that should be kept in the middle and are at the edge of the dataframe to the middle of the dataframe :param dataframe: dataframe to be shuffled :type dataframe: dataframe :param keep_in_middle: list of tasks that should be kept in the middle :type keep_in_middle: list

Returns:

dataframe (dataframe) – shuffled dataframe

shuffle_rows(dataframe, keep_in_middle=None)

randomly shuffles rows of the dataframe

Parameters:

• dataframe (dataframe) – dataframe to be shuffled

• keep_in_middle (list) – list of tasks that should be kept in the middle

Returns:

dataframe (dataframe) – shuffled dataframe