Design of the discrete-choice experiment software¶

The organization of python files¶

The discrete-choice experiment program is organized in two main files and has 3 main data structures.

Files:

_dc_init.py: contains the initiailzation functions (which run before the experiment starts).
_dc_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 (e.g. stimuli, response feedback), 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):

The response buttons
The stimuli used as visual feedback once a response is selected
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 _dc_init.py¶

trajtrackerp.dchoice.create_experiment_objects(exp_info)¶

Create the full default configuration for the experiment.

Parameters:	exp_info (trajtrackerp.dchoice.ExperimentInfo) –

trajtrackerp.dchoice.create_feedback_stimuli(exp_info)¶: Create the stimuli to be used as feedback for the participant’s response :param exp_info: :type exp_info: trajtrackerp.dchoice.ExperimentInfo

trajtrackerp.dchoice.create_response_buttons(exp_info)¶

Create the two response buttons

Parameters:	exp_info (trajtrackerp.dchoice.ExperimentInfo) –

trajtrackerp.dchoice.create_sounds(exp_info)¶

Load sounds for this experiment

Parameters:	exp_info (trajtrackerp.dchoice.ExperimentInfo) –

trajtrackerp.dchoice.hide_feedback_stimuli(exp_info)¶

trajtrackerp.dchoice.initialize_experiment(config, xpy_exp, subj_id, subj_name='')¶

A default implementation for running a complete experiment, end-to-end: loading the data, initializing all objects, running all trials, and saving the results.

Parameters:	config (trajtrackerp.dchoice.Config) – xpy_exp – Expyriment’s active experiment object subj_id – The subject initials from the num2pos app welcome screen subj_name – The subject name from the num2pos app welcome screen (or an empty string)

trajtrackerp.dchoice.load_data_source(exp_info)¶

Loads the CSV file with the per-trial configuration

Parameters:	exp_info (trajtrackerp.dchoice.ExperimentInfo) –

Functions in _dc_run.py¶

trajtrackerp.dchoice.initialize_trial(exp_info, trial)¶

Initialize a trial

trajtrackerp.dchoice.get_touched_button(exp_info)¶

Check if any response button was touched

Returns:	The number of the touched button, or None if no button was touched

trajtrackerp.dchoice.run_trials(exp_info)¶

trajtrackerp.dchoice.run_trial(exp_info, trial, trial_already_initiated)¶

Run a single trial

Parameters:	exp_info (trajtracker.paradigms.dchoice.ExperimentInfo) – trial (trajtracker.paradigms.dchoice.TrialInfo) – trial_already_initiated – Indicates if the “start” point was already touched
Returns:	RunTrialResult

trajtrackerp.dchoice.trial_ended(exp_info, trial, success_err_code, user_response)¶

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 user_response – The number of the button that was pressed (-1 = no button)

trajtrackerp.dchoice.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)

Parameters:	err (ExperimentError) – The error that occurred exp_info (trajtracker.paradigms.dchoice.ExperimentInfo) – trial (trajtracker.paradigms.dchoice.TrialInfo) –

trajtrackerp.dchoice.trial_succeeded(exp_info, trial, user_response)¶

Called when the trial ends successfully (this does not mean that the answer was correct)

Parameters:	exp_info (trajtracker.paradigms.dchoice.ExperimentInfo) – trial (trajtracker.paradigms.dchoice.TrialInfo) – user_response – The button selected by the user (0=left, 1=right)

trajtrackerp.dchoice.update_trials_file(exp_info, trial, success_err_code, user_response)¶

Add an entry (line) to the trials.csv file

Parameters:	success_err_code – A string code to write as status for this trial user_response – The number of the button that was pressed (-1 = no button)