Running MouseView.js experiment on Gorilla
The Gorilla Experiment Builder is a fully tooled platform that deals wih every aspect of experiment design and hosting through a GUI. You can sign up for Gorilla here: Gorilla.sc.
Using Gorilla is the quickest and easiest way to get your MouseView.js experiment up and running.
#
Task BuilderThe Task builder is where the MouseView.js script is configured and installed. There are two ways to do this, using a drag and drop zone (the easiest), or using the script tab (less easy).
#
Drag and Drop ZoneCurrently a drag and drop zone is under development. It's available on Gorilla via their contact form. The documentation for this zone is available here and also below.
Try out a Mouse View Zone Example
#
Setting up the MouseView ZoneUpload a background stimuli to your screen then place the MouseView Zone on each of your Task Screens where you wish to use mouse view.
Edit Configuration settings of the MouseView Zone - see details below.
1) Use the (setting) mode.
Setting (record or upload : Type either 'record' or 'upload' to choose the operation mode for the Zone. Default = record; If no mode is set the MouseView Zone will default to the 'record' mode.
Record: In record mode the MouseView Zone will record participant video and return the recorded video to the MouseView Zone Metrics.
Upload: You only need to use upload if you want to upload on at, say, the end of a task or end of a block. Otherwise, use the Continue Recording setting instead.
2) Prefix filename with (setting) for captured data
Setting (text): Type a name to identify the mouse tracking data file.
Default = mouseview; By default, the MouseView Zone will produce data with the filename mouseview-1-3, or similar.
When set to any text, this changes the filename of the MouseView data i.e. if set to 'MouseTask', the file might be named 'MouseTask-1-3'.
Note: Only use alpha-numeric characters in your file names. Do not use special characters as this could prevent you from retrieving data files.
3) If (setting) continue recording after the end of this screen.
Only set this if you are recording data across multiple screens, and ensure that the last screen does not have this set. Choose 1 (continue recording) or 0 (stop recording). Default: 0
#
Mouseview Zone Settings1) Overlay Colour: (setting).
Enter the colour for the overlay as a colour name or hexcode. Default: black
2) Overlay Alpha: (setting).
Enter the alpha (transparency) value for the overlay as a float between 0.0 and 1.0. Default: 0.8
3) Overlay Gaussian Blur: (setting) pixels.
Enter the standard deviation, as a number of pixels, for the Gaussian Blur. Higher numbers = more blur. Default: 20
4) Aperture Size: (setting) % of screen space.
Enter the size of the viewing aperture as a number representing percentage of screen. Default: 5 (i.e. 5%)
Click to view an Example of a simple Task which makes use of the MouseView Zone.
#
Task Builder Scriptcaution
This assumes you to know a bit of JavaScript, if you are new to this please check out Gorilla's tutorials on Task Builder scripting first.
To activate the overlay, track across a single screen, and pip in data there are several elements that need to be included in your Script tab.
#
General settingsIt's often easy to specify variables at the start of your script, so they are referred to later. It's easy to change them.
Let's specify our mouseview settings:
And also a list of displays we want to use the MouseView plugin on, and the index of the screen in these displays which we want everything to happen on.
Gorilla gives us hooks that run everytime given events happen. We use these to setup, start and stop MouseView.js. We use two here, OnScreenStart and OnScreenFinish
#
On Screen StartThere are several things you need to do at the start of a screen. So we use this hook. It has the form:
All the code in this subsection is placed within this hook.
#
Hiding CoverIf you are using the Gaussuan Blur overlay, you will need to hide everything on screen whilst it loads. This avoids previewing the trial in full before the blur layer is draw. We only need to create this overlay once and then use .show() and .hide() to use it.
Below we use rowIndex == 0 conditional to create this overlay on the first trial.
#
On MouseView.js displaysIf this display is one we want to use MouseView.js on, and the screen is at the correct index, then we can start loading the script and hiding things. Read the comment lines in the code below for more details.
#
On Screen FinishAt the end of the screen we want to do several things:
- Stop tracking
- Save data
- Save information about the screen dimensions
- Hide everything and shut down
The Gorilla hook looks like this, everything in this section is within that hook:
additionally we only want this to run on the MouseView.js displays and screens so we do this:
#
Stop tracking mouse/touches and remove overlayWe stop tracking, find the cover we use to hide the trial, then have MouseView.js remove all it's overlay stuff.
#
Calculate things about your trialcaution
Warning! These settings are specific to your design. So won't just work on any random Gorilla experiment
We want to calculate the dimensions on the participant's screen, for data analysis purposes. Because everyone's screens are going to be different sizes and ratios, this is vital.
Below we have two zones containing images called 'Zone1' and 'Zone2' so we get those in addition to the screen size.
We then log out these using the gorill.metric() function from the gorilla API.
#
Save MouseView coordinates!Now the most important bit, we save the data for the mousecoordinates overtime. We do this by looping through our data object and logging Gorilla metrics. We also get rid of the cover, ready for the next trial
#
full example script:Here's a full example:
caution
Warning! These settings are specific to your design. So won't just work on any random Gorilla experiment.