Writing JavaScripts for group studies
Group studies differ from single-worker studies simply in that the JavaScript needs to handle groups and communications between members. The jatos.js library provides some useful functions for this.
If you like to dive right into jatos.js’ reference:
Joining a group and opening group channels
There are two requisites for allowing group members to interact:
-
Workers can only communicate with members of their own group. So, interacting workers must all join the same group. A worker will remain in a group until jatos.js is explicitly told to leave the group (or the study run is finished). This means that if a worker moves between components or reloads a page they will remain in the same group. This feature makes groups much more robust.
-
Communication can only be done if a group channel is open. Although jatos.js opens and closes all necessary group channels so you don’t have to care for them directly while writing components. Group channels in turn use WebSockets. WebSockets are supported by all modern browsers.
So here’s how a typical JATOS group study run would look like:
Component 1
- jatos.joinGroup -> joins group and opens group channel
- jatos.nextComponent -> closes group channel and jumps to next component
Component 2
- jatos.joinGroup -> opens group channel in the same group
- jatos.nextComponent -> closes group channel and jumps to next component
Component 3
- jatos.joinGroup -> opens group channel same group
- jatos.endStudy -> closes group channel, leaves group, ends component, and ends study
Notice that by calling jatos.joinGroup in the second and third component JATOS does not let workers join a new group but just opens a group channel in the already joined group. To make a worker leave a group, use the function jatos.leaveGroup.
Every know and then you probably would like to know who the members of your groups are. This and other stats you can get by clicking on your batch’s Groups button in the Worker & Batch Manger.
Reassigning to a different group
To move a worker from one group to a different one, use jatos.reassignGroup. This function will make a worker leave their group and join a different one. JATOS can only reassign to a different group if there is another group available. If there is no other group JATOS will not start a new one but put the worker into the same old group again.
Fixing a group
Sometimes you want to stay with the group like it is in the moment and don’t let new members join - although it would be allowed according to the group properties. For example in the Prisoner’s Example study after the group is assembled in the waiting room component it is necessary to keep the two members as it is. Even if one of the members leaves in the middle of the game, JATOS shouldn’t just assign a new member. To do this you can call jatos.js’ function jatos.setGroupFixed. Alternatively (since JATOS >= v3.4.1) you can fix a group in JATOS’ GUI, in the groups table.
Communication between group members
JATOS provides three ways for communicating within the group: direct messaging, broadcast messaging and via the Group Session.
Direct messaging
Members can send direct messages to a single other member of the same group with the jatos.sendGroupMsgTo function. Like broadcast messaging this way of group communication is fast but can be unreliable in case of an unstable network connection. We use direct messaging in the Snake example to send the coordinates of the snakes on every step. Here, speed is more critical than reliability in the messages, because a few dropped frames will probably go unnoticed.
Broadcast messaging
Members can send messages to all other members of the same group with the jatos.sendGroupMsg function. Like direct messaging this way of group communication is fast but can be unreliable in case of an unstable network connection.
Group session
The Group Session is one of the three types of session that JATOS provides. Members can access the Group Session data with the Group Session functions. The Group Session data are stored in JATOS’ database only while the group is active. It is deleted when the group is finished. Communication via Group Session is slower, but more reliable than group messaging. If one member has an unstable internet connection or does a page reload, the Group Session will be automatically restored after the member reopens the group channel. Workers communicate via the Group Session data in the Prisoner’s Example study, because here one dropped message would lead to important information loss.