| This works from version 3.4.1 |
Introduction
TIP: This is a medium to advanced topic. For this lesson you need to have some experience with coding PsyToolkit experiments.
Mouse tracking is the continued use of the mouse coordinates. The changing mouse coordinates during tracking can be used to act on directly and/or to save the tracking data to file for later analysis.
Why mouse tracking
There are two possible reasons why you might want to track the mouse cursor while a participant moves the mouse to a stimulus.
Reason 1. You might simply want to know exactly where the mouse is and also save these data for later analysis.
Reason 2. You might want to know exactly where mouse is during a task and act on that, but not actually save all those data.
Needed instructions
All mouse tracking needs to be programmed in the task or an experiment script. This requires a good understanding of PsyToolkit scripting.
In order to track the mouse, you need to understand a few things about the mouse. The following instructions and (PsyToolkit built-in) variables are all important:
-
The while / while-end loop to limit the time of tracking
-
The use of timestamp to keep track of time period
-
The readmouse instruction to get the mouse location
-
Variables MOUSE_X and MOUSE_Y to know where mouse is
Further, if you also want to save mousetracking data, I also recommend the following:
-
array variables to store mouse coordinates
-
save to save array variables to output data file
Basic code examples
In the following, two different examples will be provided. Example 1 is about using the mouse tracking to rotate a stimulus, while example 2 is about using the traking data to understand the movement path and save the data for later analysis.
At this point, you need to try to follow the code yourself. At the bottom, some of the main ideas are explained in detail.
Mouse tracking demonstration 1
This demo is about mouse tracking in order to change stimulus
In the following task, we track the mouse, act on it, but do not save the data (although we could, in this case it is not needed and therefore not saved).
Note that you need to decide how often you want to track. It seems pointless to track every millisecond, it makes more sense to use a 20 to 50 ms interval. But ultimately, you can decide this yourself.
Mouse tracking demonstration 2
This demo is about mouse tracking in order to save mouse trace of user.
Key ideas in these examples
In both examples, the key for mouse tracking is to have a while loop which keep collecting data. Below is the code from the demonstration 2 and explained here line by line.
task track_me
set &&trackX clear (1)
set &&trackY clear
set &&trackT clear
show text "First click yellow rectangle, then the appearing green one" 0 -250
delay 1000
show rectangle @1 @2 30 30 yellow
readmouse l 2 3000 range 2 2 ## wait until yellow rectangle is clicked
clear -1
show rectangle @3 @4 30 30 green
# now start tracking
timestamp time1 (2)
while $d < 99999 and $clicked == 0 (3)
readmouse l 3 20 (4)
set &&trackX append MOUSE_X ## x coordinate (5)
set &&trackY append MOUSE_Y ## y coordinate
set &&trackT append $d ## time since start
if STATUS == 1 (6)
set $reactionTime timestamp-diff time1 time2 (7)
set $clicked 1 (7)
fi
timestamp time2 (8)
set $d timestamp-diff time1 time2 (9)
while-end (10)
save TABLEROW @1 @2 @3 @4
save &&trackX (11)
save &&trackY
save &&trackT
block test
tasklist
track_me 5
end
| 1 | We use three arrays called &&trackX (for storing X coordinates), &&trackY (for storing Y coordinates), and &&trackT for storing times. The clear resets them to empty arrays at the begin of each trial |
| 2 | This is the real start of the tracking. We set a time stamp which is a variable for storing time. |
| 3 | We start a while loop which will stop after either 99999 ms or when the user has clicked somewhere (we keep track with our own variable $clicked) |
| 4 | We now check if the participant has clicked. We do this for 20 ms at the time |
| 5 | Even if people did not click, the MOUSE_X and MOUSE_Y will be set to where the mouse was after the 20 ms of the previous readmouse instruction. We add the values to the arrays |
| 6 | Now we check if the participant had actually clicked within the 20 ms |
| 7 | If they did click, the reaction time is the difference between the start time and the current time (saved as timestamps) |
| 8 | We update the timestamp each time. Thus, timestamp2 is increasing every 20 ms |
| 9 | We calculated the difference between the two timestamps |
| 10 | Note that while-end is the instruction to end a while loop. The while loop keeps running until satisfied (see point 3) |
| 11 | You can save an array. In this case, we use multiple save instructions, each will create an additional line in the data file |