NumberLine class

A class that plots a number line and detects when the participant touches it in certain points.

Visual features:

  • The number line can be horizontal or vertical
  • Optional tick marks at the end of the line and in locations along the line
  • Optional text labels at the end of the line
  • Standard properties of the line and the text labels (colour, font, etc.)

Behavioral features:

  • Detect when the finger/mouse clicks or crosses the number line
  • Get the touch location as coordiantes or on the number line’s scale
  • Show the response location on screen
  • Convert between the physical coordinate space and the number line values (coord_to_value() , value_to_coord(), and value_to_coords())

Using this class

  • Configure the number line (via the constructor or by setting properties)

  • To show the response location (finger landing position): provide one or more feedback_stimuli and define a feedback_stim_chooser that decides, once the numberline was touched, which of them to show.

    The stimulus selector may rely on the response_bias, in which case you should set target in advance.

    When defining a feedback stimulus, the numberline will automatically show it when the line is touched (in fact, touching the line only sets an indication that the feedback should be presented; the feedback will be actually displayed on the next call to present() ).

    Hide the feedback stimulus by calling hide_feedback_stim() or, if you use the events mechanism , by setting feedback_stim_hide_event .

  • Draw the number line on screen with plot() or present()

  • Call reset() when mouse/finger starts moving

  • Call update_xyt() when the mouse/finger continues moving

  • Check touched to see if the number-line was touched

    When the line was touched, get the touch location - either as coordinates (last_touched_coord) or by the numberline’s numeric scale (last_touched_value).

    In case you updated target , you can also obtain response_bias .

Methods and properties:

class trajtracker.stimuli.NumberLine(position, line_length, max_value, min_value=0, orientation=<Orientation.Horizontal: 1>, line_width=1, line_colour=None, end_tick_height=None, feedback_stimuli=(), visible=True)
__init__(position, line_length, max_value, min_value=0, orientation=<Orientation.Horizontal: 1>, line_width=1, line_colour=None, end_tick_height=None, feedback_stimuli=(), visible=True)

Constructor - invoked when you create a new object by writing NumberLine()

Parameters:
  • position (tuple) – the (x,y) coordinates of the middle of the line
  • orientation – Orientation.Horizontal or Orientation.Vertical
  • line_length (int) – the length of the line, in pixels
  • line_width (number) – the width (thickness) of the line, in pixels (default = 1)
  • line_colour (tuple) – the color of the line (default = None)
  • end_tick_height (number) – the height of the ticks at the end of the line (default = None; see property for details)
  • min_value (number) – the logical value at the beginning of the line (default = 0)
  • max_value (number) – the logical value at the end of the line
  • visible – set the line as visible/invisible in the next plotting
  • feedback_stimuli – See feedback_stimuli
coord_to_value(coord)

Get the numberline value for a given screen coordinate

Parameters:coord – The x or y coordinate, (depending on the number line’s Orientation). If you specify an (x,y) tuple, either x or y will be used, as appropriate
Returns:float
end_tick_height

The height of the ticks at the ends of the number line (in pixels) Positive values = ticks above the line or to its right; negative values = below/left.

feedback_stim_chooser

A function that selects the stimulus to show as finger-landing feedback.

When several feedback_stimuli are provided, this function is used to select the stimulus that will be shown as feedback.

The function gets the numberline as an argument and returns the index of the stimulus to show.

When setting this attribute, you can specify a list of numbers between 0 and 1 (order doesn’t matter). Each number represents a response accuracy error (as a value between 0 and 1 - percentage of the number line length); the feedback stimulus will be selected by the response accuracy. Note that if you use this method, the number of feedback_stimuli must be larger than the number of accuracy levels specified here, because there is an implicit, additional accuracy level (“worse than all specified accuracies”).

feedback_stim_hide_event

Hide the feedback_stimulus when this event occurs.

feedback_stim_offset

An offset for feedback_stim - present the stimulus in this offset relatively to the number line’s touch location

feedback_stimuli

A list of stimuli to be used as feedback (showing where the mouse/finger landed on the line).

The number line will take care of showing a feedback stimulus when appropriate. You hide them by calling hide_feedback_stim() or, if you use the events mechanism , by setting feedback_stim_hide_event.

The actual display is updated when present() is called). put it in a stimulus container.

When using more than one feedback stimulus, specify a feedback_stim_chooser, otherwise the first feedback stimulus will always be used.

Use feedback_stim_offset if needed.

hide_feedback_stim(hide_target_pointer=True)

Hide a previously-showed feedback stimulus

label_max_text

The text for the label at the MAX end of the number line

label_min_text

The text for the label at the MIN end of the number line

labels_box_size

The textbox size of the end-of-line labels (height, width)

labels_font_colour

The font color of the end-of-line labels. The value is an expyriment color - tuple of 3 values, each 0-255

labels_font_name

The font name of the end-of-line labels

labels_font_size

The font size of the end-of-line labels

labels_offset

The number line’s position: the (x,y) coordinates of the line mid point (tuple/list are accepted)

labels_visible

Whether the end-of-line labels are visible or not (boolean)

line_colour

The color of the number line. None = the line will not be plotted.

line_length

The number line length (in pixels). Only positive values are valid.

line_width

The number line width (in pixels). Only positive values are valid.

log_level

Logging level of this object: trajtracker.log_none, log_error (default), log_warn, log_info, log_debug, log_trace

max_value

The maximal logical value on the number line

min_value

The minimal logical value on the number line

offset_event

The time when the object should disappear from screen.

Type:Event, or None to avoid automatic offset.
onset_event

The time when the object should appear on screen.

Type:Event, or None to avoid automatic onset.
orientation

The number line’s orientation (horizontal or vertical)

Type:trajtracker.stimuli.Orientation
plot(stim)

Plot the number line on another stimulus

Parameters:stim – Any Expyriment visual object
Returns:The time it took this function to run (seconds)
position

The number line’s position: the (x,y) coordinates of the line mid point (tuple/list are accepted)

preload()

Pre-load the number line - prepare for plotting

Returns:The time it took this function to run. (seconds)
present(clear=False, update=False)

Present the stimulus

Parameters:
  • clear (bool) – Whether to clear the screen buffer prior to presenting. Default=False
  • update (bool) – Whether to flip buffer after plotting. Default=False
Returns:

The time it took this function to run. (seconds)
reset(time0=None)

Reset the last-known mouse position, so that update_xy() will forget any previous movement This function is typically called in the beginning of a trial.

Parameters:time0 – ignored.
response_bias

The delta between the touch position and the target position (positive = rightward bias)

response_coord

Get the coordinate where the mouse/finger last touched the number line. This is either the x or y coordinate, depending on the number line orientation If the finger didn’t touch the line since the last call to reset_mouse_pos(), the function returns None.

Type:int
response_coords

Get the (x,y) coordinates where the mouse/finger last touched the number line. Returns None if the line was not touched yet.

Type:tuple
response_value

The position where the mouse/finger last touched the number line. The value returned is in the number line’s scale. If the finger didn’t touch the line since the last call to reset_mouse_pos(), the function returns None.

Type:float
show_labels(visible=True, box_size=None, font_name=None, font_size=None, font_colour=None, offset=(0, 0), text_min=None, text_max=None)

Determine appearance of the two text labels at the ends of the line

Parameters:
  • visible (bool) – Whether the labels are visible or not (boolean)
  • box_size (tuple) – Size of the text box in pixels (width, height)
  • font_name (str) – Name of font
  • font_size (int) – Size of font
  • font_colour (Expyriment colour spec) – Color of font
  • offset (tuple) – (x,y) offset of a label (in pixels) relatively to the corresponding end of the number line
  • text_min (str) – Text for the label at the MIN end of the number line (default: min value)
  • text_max (str) – Text for the label at the MAX end of the number line (default: max value)
show_target_pointer_on(nl_value)

Show target_pointer_stimulus in the specified location

Parameters:nl_value (numbers.Number) – A location on the number line, defined using its scale
size

Get the size of the rectangle surrounding the number line, with all its elements. The number line center will be at the center of the rectangle

Returns:tuple (width, height)
target

The target number. Setting this is needed only if you want to use response_bias

target_pointer_offset

An offset of target_pointer_stimulus relatively to the target location on the number line.

Type:tuple (x, y)
target_pointer_stimulus

A stimulus that will indicate the target, positioned on the number line.

touch_directioned

Whether the number line can be touched only from the finger’s movement direction (True) or from any direction (False)

touch_distance

Minimal distance from line that counts as touch (negative value: finger must cross to the other side)

touched

Indicates whether the number line was touched or not

Type:bool
update_xyt(position, time_in_trial=None, time_in_session=None)

This function is called when mouse/touch has moved. It checks whether the movement implies touching the number line.

Parameters:
  • position (tuple (x,y)) –
  • time_in_trial – ignored.
  • time_in_session – ignored.
validate()

Validate that the number line configuration is ok.

Raise:ValueError - if the configuration is invalid
value_to_coord(value)

Get the coordinate for a given value on the number line This is either the x or y coordinate, depending on the number line orientation

Returns:int
value_to_coords(value)

Get the (x,y) coordinate corresponding with a given value on the number line

Returns:tuple
visible

Whether the number line is visible (boolean)