Config class (discrete choice)

Configuration parameters for a discrete-choice experiment.

All parameters can be set directly and via the constructor.

General:

Config.experiment_id (str, mandatory parameter)

A unique ID of the present experiment configuration. Will be saved as-is in the results file, to help you identify the specific configuration you were executing.

Config.save_results = True (bool)

Whether to save the results (trials and trajectory).

Targets to show

Main parameters

Config.data_source - str, mandatory parameter

The name of a CSV file with the per trial data. See (TBD) for detailed description of this file format. Alternatively, you can provide a list of numbers, each of which will be presented as a text target.

Config.shuffle_trials = True (bool)

Whether to randomize the order of trials, or to present them in the order in which they were provided in data_source.

Config.use_text_targets = True (bool)

Whether to present text targets. If True, you should have a text.target column in the CSV file.

Config.use_generic_targets = False (bool)

Whether to present generic targets. A generic target is any Expyriment (or equivalent) stimulus - e.g., image, shape, etc.

Additional parameters

Config.stimulus_distance_from_top = 5 (int)

The distance (in pixels) between top of screen and the target’s top

Config.target_onset_time = [0.0] (list of numbers)

Default onset time for the target. If more than one target is specified, one onset time per target is due. See MultiStimulus.onset_time

Config.target_duration = [1000.0] (list of numbers)

Additional parameters when config.use_text_targets = True

Config.text_target_colour = White (RGB color)
Config.text_target_font = 'Arial' (str)

Font name.

Config.text_target_height = 1.0 (number)

The height of the text target, specified as percentage of the available distance between the number line and the top of the screen (value between 0 and 1). The actual target size (in pixels) will be printed in the output file.

Config.text_target_justification = 1

0 = left, 1 = center, 2 = right

Config.text_target_last_stimulus_remains = False (boolean)

When showing multiple texts, this indicates if the last one should remain on screen or disappear after a delay (see MultiTextBox.last_stimulus_remains)

Config.text_target_width = 300 (int)

Width (in pixels) of the target’s text box

Config.text_target_x_coord = 0 (int)

The x position of the target text box

Additional parameters when config.use_generic_targets = True

Config.generic_target_x_coord = 0 (int)

The x position of the generic target

Config.generic_target_last_stimulus_remains = False (boolean)

When showing multiple texts, this indicates if the last one should remain on screen or disappear after a delay (see MultiStimulus.last_stimulus_remains)

Fixation stimulus

Config.fixation_text - str

The default fixation text to use when fixation_type = ‘text’. This value can be overriden by column fixation.text in the CSV config file.

Config.fixation_type - 'cross' (default), 'dot', 'text', 'zoom', or None

The type of fixation stimulus.

When using ‘text’ fixation, you can set the text via fixation_text or via the CSV config file.

Config.fixzoom_box_size = (40, 40) (width, height)

Relevant when fixation_type = ‘zoom’. See FixationZoom.box_size

Config.fixzoom_dot_colour = Grey (RGB color)

Relevant when fixation_type = ‘zoom’. See FixationZoom.dot_colour

Config.fixzoom_dot_radius = 3 (int)

Relevant when fixation_type = ‘zoom’. See FixationZoom.dot_radius

Config.fixzoom_show_event = None (trajtracker.events.Event)

Relevant when fixation_type = ‘zoom’. See FixationZoom.show_event

Config.fixzoom_start_zoom_event = None (trajtracker.events.Event)

Relevant when fixation_type = ‘zoom’. See FixationZoom.start_zoom_event

Config.fixzoom_stay_duration = 0.1 (number)

Relevant when fixation_type = ‘zoom’. See FixationZoom.stay_duration

Config.fixzoom_zoom_duration = 0.2 (number)

Relevant when fixation_type = ‘zoom’. See FixationZoom.zoom_duration

Config.hide_fixation_event = FINGER_STARTED_MOVING (trajtracker.events.Event)

The event on which the fixation stimulus will be hidden. None = don’t hide the fixation.

Config.log_stimulus_onset_offset = False (bool)

Whether to log (in a CSV file) the exact times when each stimulus appeared and disappeared

“Start” rectangle

Config.stimulus_then_move = False (bool)

True: The software decides when the target appears, and then the finger must start moving

False: The finger moves at will and this is what triggers the appearance of the target

Config.finger_moves_max_time = None (number)

The maximal time (in seconds) in which the finger should start moving. The time is specified relatively to the time point of touching the screen

Config.finger_moves_min_time = None (number)

The minimal time (in seconds) in which the finger should start moving. The time is specified relatively to the time point of touching the screen

Config.finger_must_start_upwards = True (boolean)

Whether the finger must leave the “start” point upwards, or can leave it in any direction (including sideways)

Config.start_point_colour = Grey (RGB color)

Colour of the “start” rectangle

Config.start_point_size = (40, 30) (tuple width, height)

The size of the “start” rectangle, in pixels.

Config.start_point_tilt = 0 (number)

Rotation of the “start” rectangle (clockwise degrees)

Config.start_point_x_coord = 0 (number)

X position the “start” rectangle

Movement restrictions (validators)

Config.grace_period = 0.3 (number)

Duration (in seconds) in the beginning of the trial during which speed is not validated. This parameter applies to both InstantaneousSpeedValidator and GlobalSpeedValidator.

Config.max_movement_time - number, mandatory parameter

Maximal valid time from leaving the “start” rectangle until reaching the number line (in seconds) This parameter also affects the speed limit per time point (via GlobalSpeedValidator)

Config.min_movement_time = 0.2 (number)

Minimal valid time from leaving the “start” rectangle until reaching the number line (in seconds)

Specific configuration for FingerLiftedValidator

Config.max_offscreen_duration = 0 (number)

The maximal duration (in seconds) that the finger can be off the screen before a “finger lifted” error is issued.

When using finger/mouse, this value should be 0 (don’t allow any finger-lift). However, the value may be increased when using inaccurate input devices that may lose the touch information for a split-second.

Specific configuration for InstantaneousSpeedValidator

Config.min_inst_speed = 10 (number)

The minimal instantaneous speed (pixels per second).

Specific configuration for GlobalSpeedValidator

Config.global_speed_validator_milestones = [(.5, .33), (.5, .67)]

See GlobalSpeedValidator.milestones

Config.speed_guide_enabled = False (bool)

If True, the speed limit will be visualized as a moving line.

Specific configuration for MovementAngleValidator

Config.dir_validator_calc_angle_interval = 20 (int)

See MovementAngleValidator.calc_angle_interval

Config.dir_validator_max_angle = 90 (number)

See MovementAngleValidator.max_angle

Config.dir_validator_min_angle = -90 (number)

See MovementAngleValidator.min_angle

Specific configuration for NCurvesValidator

Config.max_zigzags = 8 (int)

Maximal number of left-right deviations allowed per trial.

Config.zigzag_validator_min_angle_change_per_curve = 10 (int)

See NCurvesValidator.min_angle_change_per_curve

Finger trajectory tracking

Config.max_post_response_record_duration = 0.3 seconds (Number)

Defines how long to keep recording the finger trajectory after a response was made.

By default, any of the following will stop trajectory recording:

  • A response was made: keep recording for max_post_response_record_duration seconds.
  • The finger was lifted from screen
  • An error occurred in the trial

Note: Changing TrajectoryTracker.disable_events will override this default behavior. The max_post_response_record_duration parameter will be ignored in this case.

Subjective confidence rating

This feature will show, after each trial, a slider with which the subjects will rate their confidence.

Config.confidence_rating = False (bool)

Whether to ask for such confidence rating after each trial

Config.confidence_slider_height = 0.7 in num2pos paradigm, or 0.8 in discrete-choice paradigm

The slider’s height. Either height in pixels (int) or percentage of the screen height (a value between 0 and 1)

Config.confidence_slider_y = -0.05 in num2pos paradigm, or 0 in discrete-choice paradigm

The slider’s vertical position (horizontal position = middle). Either position in pixels (int) or percentage of the screen height (a value between -0.5 and 0.5)

Error-message text box

Config.errmsg_textbox_coords = (0, 0) (tuple x, y)
Config.errmsg_textbox_size = (290, 180) (tuple width, height)
Config.errmsg_textbox_font_size = 16 (int)
Config.errmsg_textbox_font_name = 'Arial' (str)
Config.errmsg_textbox_font_colour = Red (RGB color)

Response buttons

Config.resp_btn_colours = Grey (RGV color)

Colour of the response button. If two colours are provided, they will be used for the left and right buttons, correspondingly.

Config.resp_btn_font_name = 'Arial' (str)
Config.resp_btn_font_size = 16 (int)
Config.resp_btn_positions = None

Position of the response button. This can be either of:

  • (x,y) tuple denoting the position of the right button. The left button will be symmetric.
  • A list with (x,y) positions of both buttons - [(xleft,yleft), (xright,yright)]
Config.resp_btn_size = (0.05, 0.1) (tuple width, height)

Size of the response buttons. Specify fractions between 0 and 1 to indicate % of screen width/height.

Config.resp_btn_texts = None (str)

Text of the response buttons. If two texts are provided, they will be used for the left and right buttons, correspondingly.

Config.resp_btn_text_colour = White (RGV color)

A single color, used for both buttons.

Visual feedback on responses

How to use it:

  • Determine the type of feedback stimulus (rectangle/pictures) by setting feedback_stim_type .
  • Determine where the stimulus appears: set feedback_stim_position or rely on default positions by setting feedback_place
  • For rectangle feedback, use the other properties to set its size, color, etc.
  • Each trial can show either of two feedback stimuli. Set feedback_select_by to decide how to select one of these two stimuli.
Config.feedback_stim_type = None

The kind of feedback stimulus to show, following a participant response:

  • ‘rectangle’: a rectangle (you can configure its shape and position)
  • ‘picture’: Configure it via feedback_pictures
Config.feedback_place = 'button'

Where to place the feedback stimuli. This affects the default values of feedback_stim_position and feedback_btn_colours

Valid values:

  • ‘buttons’: over the response buttons
  • ‘middle’: between the buttons (on top of screen)
Config.feedback_select_by = 'response'

Determnes how to select which of the two feedback stimuli will be shown. Possible values:

  • ‘response’: The feedback is determined by the button touched
  • ‘expected’: The feedback is the button that should be pressed
  • ‘accuracy’: The feedback is determined by whether the touched button was correct.
    (when configuring the two feedback stimuli, e.g., size and position, the first one refers to correct response). If you use this feature, you must include an “expected_response” column in the trials CSV file.
Config.feedback_btn_colours = None

The colour of the feedback button/rectangle. If two colors are provided, the first colour will be used for correct responses and the second colour for incorrect responses

Default: Green for feedback_place = ‘button’, [Green Red] for feedback_place = ‘middle’

Config.feedback_duration = 0.2 (number)

Duration (in seconds) for which feedback is presented

Config.feedback_rect_size (optional)

The size of the feedback stimuli: either (width, height) if both have the same size, or an array of two sizes i.e. [(width1, height1), (width2, height2)].

  • For feedback_place = ‘button’, the default size is the size of the response buttons.

  • For feedback_place = ‘middle’, you should either specify feedback_rect_size and feedback_stim_position or neither of them. Default: the feedback rectangle will be at the top of the screen, between the two buttons.

    For feedback_place = ‘middle’, if a single number is defined here, it denotes the rectangle’s height.

Config.feedback_stim_position (optional)

The position of the feedback stimulus - either (x,y) coordinates (indicating that both feedback areas are in the same location) or [(x1,y1), (x2,y2)].

  • For feedback_place = ‘middle’, the default position is in the middle-top of the screen.
  • For feedback_place = ‘button’, the default position is at the two top corners of the screen.
Config.feedback_pictures (array with two expyriment.stimuli.Picture objects)

Pictures to use as feedback (when feedback_mode = ‘picture’).