StartPoint class

A starting point for a trial.

The starting point defines two areas: a start area, which you must touch/click to initiate a trial. After touching the start area, the subject must move the finger/mouse (without lifting it) from the start area directly into an exit area. The movement into the exit area can be used as a trigger for starting the trial voluntarily by the subject, or can be the mandatory behavior when a trial start is imposed by the software.

If the finger leaves the start area into a position other than the exit area, the trial may fail.

Technically, the check_xy() ,method tracks the mouse/finger movement, and returns one of four states: The screen not touched yet; the start area was touched; the finger moved from the start area into the exit area; or the finger moved to an invalid location.

Using this class:

  • Define a start area and an exit_area.
  • When the trial is initialized, call reset()

Then, you can go in two ways. The convenient way consists of two steps:

Alternatively, if you want to create a slighly different flow, you can skip the two functions above and repeatedly call check_xy() . This may monitor the subject behavior in more detail.

Methods and properties:

class trajtracker.movement.StartPoint(start_area, exit_area='above')
__init__(start_area, exit_area='above')

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

Parameters:
  • start_area – The area where you must touch/click to initiate a trial. This object must support an overlapping_with_position() method and a “center” property. It can be an expyriment stimulus, a shape from nvshapes(), or your own object
  • exit_area – See exit_area
check_xy(x_coord, y_coord)

Check whether the new finger coordinates imply starting a trial

Returns:bool - whether the state was changed
exit_area

After the mouse/finger leaves the start area, it must enter immediately the exit_area in order for the trial to start. Otherwise, it would count as an error. This object must support the overlapping_with_position() method. It can be an expyriment stimulus, a shape from nvshapes(), or your own object.

Also, you can use any of the predefined keywords “above”, “below”, “right” and “left”. Each of those define a region that is a 90-degrees sector, centered on start_area’s center (“above” = -45 degrees to 45 degrees; the others accordingly)

Setting exit_area to None means that any exit direction from the start point would be valid.

log_level

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

mark_as_initialized()

Force the StartPoint object into an “init” State, as if it was touched by the mouse/finger. This is useful in case trial initiation was triggered in another way.

reset()

Reset this object. This method should be called when the trial is initialized.

state

The current state of starting the trial - a value of the StartPoint.State enum

  • State.reset - The trial was just initialized, finger/mouse did not touch the screen yet
  • State.mouse_up - The mouse was unclicked (or finger lifted from the screen) since the trial was initialized.
    This is to enforce that the subject raises the finger before starting a new trial.
  • State.init - The finger touched the screen (or mouse clicked), indicating that the trial started
  • State.start - The finger/mouse left the start area in a valid way (into the exit area)
  • State.error - The finger/mouse left the start area in an invalid way (not into the exit area)
  • State.aborted - The trial was aborted - finger lifted before it started moving
  • State.timeout - The timeout for starting a trial has expired
wait_until_exit(exp, on_loop_callback=None, on_loop_present=None, event_manager=None, trial_start_time=None, session_start_time=None, max_wait_time=None)

Wait until the finger leaves the starting area

The on_loop_xxx and event_manager parameters define what to do on each iteration of the loop that waits for the area to be touched. If neither on_loop_callback nor on_loop_present are provided, the function will wait for 15 ms on each loop iteration.

If several on_loop parameters are provided, they will be invoked in this order: callback - event manager.on_frame() - present().

Parameters:
  • exp – The Expyriment experiment object
  • on_loop_callback – A function to call on each loop iteration. If the function returns any value other than None, the waiting will be terminated and that value will be returned. The function gets 2 arguments: time_in_trial, time_in_session
  • on_loop_present – A visual object that will be present()ed on each loop iteration.
  • event_manager – The event manager’s on_frame() will be called on each loop iteration. If you provide an event manager, you also have to provide trial_start_time and session_start_time (whose values were obtained by trajtracker.utils.get_time()
  • max_wait_time – Maximal time (in seconds) to wait
Returns:

The value returned by the on_loop_callback function (in case it returned anything other than None). Otherwise the function returns None. Use state to learn about the StartPoint’s exit status.
wait_until_startpoint_touched(exp, on_loop_callback=None, on_loop_present=None, event_manager=None, trial_start_time=None, session_start_time=None, max_wait_time=None)

Wait until the starting point is touched.

The on_loop_xxx and event_manager parameters define what to do on each iteration of the loop that waits for the area to be touched. If neither on_loop_callback nor on_loop_present are provided, the function will wait for 15 ms on each loop iteration.

If several on_loop parameters are provided, they will be invoked in this order: callback - event manager.on_frame() - present().

Parameters:
  • exp – The Expyriment experiment object
  • on_loop_callback – A function (without arguments) to call on each loop iteration. If the function returns any value other than None, the waiting will be terminated and that value will be returned.
  • on_loop_present – A visual object that will be present()ed on each loop iteration.
  • event_manager – The event manager’s on_frame() will be called on each loop iteration. If you provide an event manager, you also have to provide trial_start_time and session_start_time (whose values were obtained by trajtracker.utils.get_time()
  • max_wait_time – Maximal time (in seconds) to wait
Returns:

The value returned by the on_loop_callback function (in case it returned anything other than None). Otherwise the function returns None. Use state to learn about the StartPoint’s exit status.