Design of the number-to-position experiment software

The organization of python files

The number-to-position experiment program is organized in two main files and has 3 main data structures.

Files:

• _n2p_init.py: contains the initiailzation functions (which run before the experiment starts).
• _n2p_run.py: contains runtime functions (actually run the experiment)

Data structures:

• Config : an object containing the configuration of supported features.
• ExperimentInfo : an object that keeps all the experiment-level information: visual objects (number-line, stimulus), movement validators, the info from the CSV data file, experiment-level results (e.g., number of failed trial), etc.
• TrialInfo : an object that keeps the information about the present trial.

The persistent objects

The following objects exist throughout the experiment session (all are stored as part of the ExperimentInfo object):

• A NumberLine
• Objects that can visually denote specific locations on the number line: a feedback arrow, and a vertical line indicating the correct target location.
• A list of TrialInfo objects, typically created by loading from the CSV file.
• The Config object and some other configuration parameters (e.g., result file names, subject ID and name, etc.).

• Placeholders for the stimuli: a MultiTextBox for text stimuli, and a MultiStimulus for other stimuli (pictures, shapes, etc.)
• A RectStartPoint for initiating a trial
• A StimulusContainer that keeps all the experiment’s presentable objects
• A TrajectoryTracker for saving the finger trajectories
• Movement validators: GlobalSpeedValidator and InstantaneousSpeedValidator to enforce speed, MovementAngleValidator to prevent downward movement, and NCurvesValidator to prevent zigzag movement.
• An EventManager - because the program works with events
• Sounds (expyriment.stimuli.Audio objects) to play when the trial ends (successfully or with an error).
• An expyriment.stimuli.TextBox for presenting error messages.
• A dict with experiment-level results (which is saved to the results file at the end of the exepriment). Trial-level results (which are saved in trials.csv) are stored on the TrialInfo object.

Events

A trial can include the following events:

• trajtracker.events.TRIAL_INITIALIZED - when the trial was initialized (right after the previous trial ended)
• trajtracker.events.TRIAL_STARTED - when the finger touches the “start” rectangle
• FINGER_STARTED_MOVING - when the finger starts moving
• FINGER_STOPPED_MOVING - when the finger stops moving (either when a response was made or when the trial failed)
• trajtracker.events.TRIAL_SUCCEEDED - when the trial ended successfully (this does not mean that the subject’s response was good; it only means that some response was made). In case there are post-trial operations (e.g., get subjective confidence rating), the event will be dispatched these operations finished.
• trajtracker.events.TRIAL_FAILED - when the trial failed, for any reason
• trajtracker.events.TRIAL_ENDED - this event is dispatched whenever a TRIAL_SUCCEEDED or TRIAL_FAILED events are dispatched.

The operations triggered by events are:

• Showing/hiding stimuli: this happens in certain delay after TRIAL_STARTED (when config.stimulus_then_move = True) or after FINGER_STARTED_MOVING (when config.stimulus_then_move = False)
• Hiding the feedback arrow (runs on TRIAL_STARTED)
• Enabling the TrajectoryTracker and all validators on FINGER_STARTED_MOVING, and disabling them on FINGER_STOPPED_MOVING.

List of functions

The main program calls create_experiment_objects(); this function takes care of the complete initialization process: it calls all the other functions in this file.

Below is the list of functions specific to the number-to-position task. See here a list of common functions.

Functions in _n2p_init.py

trajtrackerp.num2pos.create_experiment_objects(exp_info)

Create the full default configuration for the experiment.

Parameters:exp_info (trajtracker.paradigms.num2pos.ExperimentInfo) –

trajtrackerp.num2pos.create_numberline(exp_info)

Create a NumberLine object with default configuration

Parameters:exp_info (trajtracker.paradigms.num2pos.ExperimentInfo) –

trajtrackerp.num2pos.create_sounds(exp_info)

Load the sounds for the experiment

Parameters:exp_info (trajtracker.paradigms.num2pos.ExperimentInfo) – The experiment-level objects

trajtrackerp.num2pos.load_data_source(exp_info)

Loads the CSV file with the per-trial configuration

Functions in _n2p_run.py

trajtrackerp.num2pos.initialize_trial(exp_info, trial)

Initialize a trial

trajtrackerp.num2pos.on_finger_touched_screen(exp_info, trial)

This function should be called when the finger touches the screen

trajtrackerp.num2pos.play_success_sound(exp_info, trial)

Play a “trial succeeded” sound. If required in the configuration, we select here the sound depending on the endpoint error.

trajtrackerp.num2pos.run_trials(exp_info)

trajtrackerp.num2pos.run_trial(exp_info, trial, trial_already_initiated)

Run a single trial

Parameters:trial_already_initiated – Indicates if the “start” point was already touched Returns:RunTrialResult

trajtrackerp.num2pos.trial_ended(exp_info, trial, success_err_code)

This function is called whenever a trial ends, either successfully or with failure. It updates the result files.

Parameters:success_err_code – A string code to write as status for this trial

trajtrackerp.num2pos.trial_failed(err, exp_info, trial)

Called when the trial failed for any reason (only when a strict error occurred; pointing at an incorrect location does not count as failure)

trajtrackerp.num2pos.trial_succeeded(exp_info, trial)

Called when the trial ends successfully (i.e. the finger touched the numberline - doesn’t matter where)