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, 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 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], n_trials=30, trial_dur=4, iti_dur=1.0, question_dur=2.0, display_feedback=True, run_number=None, file_name=None, **unused)

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, task_dur, run_time=None)

adds start and end times to the dataframe

Parameters:

• dataframe (dataframe) – dataframe to be shuffled

• offset (float) – offset of the task

• task_dur (float) – duration of the task

• run_time (float) – Time (in seconds) that the run should last. Use this to ensure the last task runs until the end of the imaging run

Returns:

dataframe (dataframe) – dataframe with start and end times

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

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