Welcome to the Experiment Tree Nodes Tooling Reference Guide.
Here you can find out information on how and when to use a particular Experiment Tree Node. There are 18 Nodes available. Browse the list of Nodes in the menu on the left to find out more information about each one.
Experiments are designed by combining the Questionnaires and Tasks you create into an 'Experiment Tree'. With the addition of Control Nodes which add powerful functionality such as Branching, Randomisation and Counterbalancing, you can create complex experiments with ease.
Each Experiment Tree Node has a Key that is automatically assigned when the Node is created. You can find this Node Key by clicking the Node to open its configuration menu (but it's also written on the Node itself). The Node Key is located at the top of the menu, just under the Node title. This Key will be included in the downloaded data from your experiment under the column 'Tree Node Key'.
For each Experiment Tree Node listed you will find a description of the Node and an image example. This will be followed by a configuration settings box which will list and explain all available configuration settings for the selected Node. Some Tree Nodes also have Demos, Examples and Tutorials to help you learn how to use them.
Questionnaire Nodes are green with a icon in the top left corner.
The Questionnaire Node has a single connection point and contains a single questionnaire within your experiment.
A Questionnaire Node can be used to proceed a task (for example, to include instructions), to collect demographic information (for example, through screening questionnaire) or to follow a task (for example, to display debrief information). It can also be used as the only Study Node in your Experiment Tree, for example, if you only need to collect survey data.
Once the participant has completed the questionnaire they will advance to the next Node in the experiment tree.
Task Nodes are blue with a icon in the top left corner.
The Task Node has a single connection point and contains a single task within your experiment.
In the Experiment Tree, a Task Node can be any of the following: a Task Builder 2 Task, a Task Builder 1 Task, a Code Editor Task, a game made in Game Builder, or a shop made in Shop Builder.
Click a Task Node to configure its node-specific manipulations, or conditions. These manipulations must first be set up in the task itself. Each Task Node which uses the same Task but with different manipulations will have any differences show up within the Experiment Tree.
Once the participant has completed the Task they will advance to the next Node in the experiment tree.
Manipulations
See image example of the configuration settings above.
Spreadsheet The Spreadsheet manipulation is the most common manipulation you will see available in your task nodes. In the dropdown menu you can choose from any spreadsheets you have uploaded.
Other Manipulation by Name Any other manipulations you have set up in your Task will appear here under the name you have given them. If you have also given them a default value and description (via the Manipulations tab within the Task Builder) then this will appear here as well.
Start Nodes are dark-grey with a icon in the top left corner.
The Start Node has a single connection point and marks the entry-point(s) into your experiment.
The initial screen shown to participants when they enter your experiment via your start node will depend on which recruitment option you have selected. After this initial start screen, the participant progresses directly on to the Questionnaire or Task Node connected immediately after your Start Node (or any other Control Node you are using).
As soon as a participant enters a Start Node, they will be recorded on your experiment's 'Participants' page as 'Live' and counted towards your total Recruitment Progress. A Token will be reserved for the participant at this point. Find out more about what happens to tokens as participants progress through your experiment.
Using Multiple Start Nodes:
Most experiments will only need one Start Node. However, it is possible to have multiple Start Nodes.
If your participants are already divided into groups, you can associate each Group to a separate Start Node. This way you can use multiple Start Nodes to ensure each group sees a different version of your experiment.
Using multiple start nodes is one way of dividing your participant pool. You may want to use this method if you wish to display different tasks or tasks with different manipulations to your different participant groups. Participants can either be assigned to different groups by offering them different links, or by manually assigning them to a group. Use the recruitment options, Email Shot, Email ID or Supervised if you wish to employ this method. You can also use this method in conjunction with a 3rd party recruitment service that allows you to pre-screen participants to check if they match your group criteria.
Check out this Gorilla Academy case study featuring the use of multiple Start Nodes to recruit groups with different pre-screening criteria in the context of a real experiment.
Group
Default = blank
Name of group participants will be matched to. Leave blank to match to any group.
Save data to the Store
Any query string parameter will be accepted as data which Gorilla saves to the Store. For example, if you send your participants to Gorilla with
https://research.sc/my-login-link?id=123&myvar=group1
then your participant would start the experiment with an Field in the Store called 'myvar' set to 'group1'.
Finish Nodes are dark-grey with a icon in the top left corner.
The Finish Node marks the end-point(s) of your experiment.
Once participants reach a Finish Node, they can perform no further tasks or questionnaires. At this point the participant:
If a participant has not reached a Finish Node, but you still want to use their data, you can manually include them. Note that doing this will permanently consume a token.
Using Multiple Finish Nodes: Most experiments will only need one Finish Node. However, it is possible to have multiple Finish Nodes.
This can be useful if you want to have participants end at different points in your experiment. If, for example, they did not score highly enough to progress to the next stage of testing, but you still want to use the data they generated up to that point.
Onward URL
Enter a URL to redirect participants to this address once they reach the Finish Node. By Default, the participant is sent to the Gorilla finish screen.
Append PublicID
If set, append the participant's PublicID to the Onward URL above, along with the prefix-value assigned here. For example, if you enter the prefix-value here as id this will result in the participant being redirected to http://www.your-onward-url-above.com?**id**=PUBLICID
Use this option if your onward URL will need an identifier from the participant.
Append Embedded Data
This allows you to carry information about responses given by participants on Gorilla to the external site. You may wish to do this if you intend to manipulate which external task/questionnaire etc. is presented to participants.
Append External Session ID
This allows you to append the external session ID to the URL. Name this according to the requirements of your external site.
Show Completion Code
If checked, the participant will be shown their completion code. They can then use this code on third-party tools & software such as Amazon Mechanical Turk, to verify that they have completed the task.
Disable default behaviour
If this setting is checked, the default behaviour will be disabled.
Default behaviours are the types of information that are passed back to your recruitment service, such as Survey Codes or Session IDs, or presented to your participant, such as Completion Codes.
If you are using Prolific, SONA or another integrated recruitment service, you only need to enter your return URL in the above settings, because Gorilla will automatically send other required information back.
The Third Party recruitment policy does not have default behaviour, so the above settings need to be configured manually.
If disabled, this information will not be sent automatically by Gorilla. Instead you must manually configure the settings above. Without this, you will be unable to validate which participants have completed the study or have been rejected, and so you may end up paying participants who have been rejected. If you select this setting, take care to ensure your manual configuration works correctly!
Reject Nodes are dark-grey with a icon in the top left corner.
The Reject Node marks an end-point of your experiment and functions similarly to the Finish Node.
Reject Nodes differ from the Finish Node in four ways: Participants who end at a Reject Node are by Default;
Using Multiple Reject Nodes:
It is possible to have multiple Reject Nodes in your experiment.
This can be useful if you want to reject participants at different points in your experiment; if for example, they do not meet the requirements for your experiment or did not score highly enough to progress to the next stage of testing.
Onward URL
Enter a URL to redirect participants to once they reach the Reject Node.
By Default, the participant is sent to the Gorilla finish screen. This is identical to the Finish Node's default finish screen.
Append PublicID
If set, append the participant's PublicID to the Onward URL above, along with the prefix-value assigned here. For example, if you enter the prefix-value here as id this will result in the participant being redirected to http://www.your-onward-url-above.com?id=PUBLICID
Use this option if your onward URL will need an identifier from the participant.
Append External Session ID
If set, append the participant's External Session ID to the onward URL in the query string. Enter the variable name you would like to use. For example, the value externalID will result in the participant being redirected to http://www.your-onward-url-above.com?externalID=EXTERNALSESSIONID
Append Embedded Data
If you want to append some other data Fields from the Store, enter them here, separated by commas. By default, they will be appended with the same name. If you need to append the values, but with a different name, enter the name of the Field followed by the name to use in the URL, separated by a colon.
For example, entering val1, val2:myval will result in http://www.your-onward-url-above.com?val1=VAL1&myval=VAL2
Show Completion Code
If checked, the participant will be shown their completion code.
They can then use this code on third-party tools & software such as Amazon Mechanical Turk, to verify that they have completed the task.
Disable default behaviour
If this setting is checked, the default behaviour will be disabled.
Default behaviours are the types of information that are passed back to your recruitment service, such as Survey Codes or Session IDs, or presented to your participant, such as Completion Codes.
If you are using Prolific, SONA or another integrated recruitment service, you only need to enter your return URL in the above settings, because Gorilla will automatically send other required information back.
The Third Party recruitment policy does not have default behaviour, so the above settings need to be configured manually.
If disabled, this information will not be sent automatically by Gorilla. Instead you must manually configure the settings above. Without this, you will be unable to validate which participants have completed the study or have been rejected, and so you may end up paying participants who have been rejected. If you select this setting, take care to ensure your manual configuration works correctly!
Participant Inclusion
Default = Exclude
Options:
Exclude: Default
Include:
Some experimental set-ups require collection of rejected participants' data. In this specific case, you may want to include participants who end your experiment at a Reject Node.
Rejection Status
Select an option from the dropdown to set the rejection type you wish participants who reach this Reject Node to be set to. For some recruitment policies (e.g., Kantar Profiles), this will affect the link that your participants return to.
Default = 'Rejected'; Participants entering this Reject Node will be marked as 'Rejected' under 'Status' on the Participants tab.
Options: 'Rejected', 'Rejected - Over Quota', or 'Rejected - Quality'
'Rejected - Over Quota': Selecting this option will result in participants entering this Reject Node to be marked as 'Rejected - Over Quota' under 'Status' on your Participants tab. Note: This option is significant if you are using Quota Nodes.
'Rejected - Quality': Selecting this option will result in participants entering this Reject Node to be marked as 'Rejected - Quality' under 'Status' on your Participants tab.
A common use case for the Reject Node is to exclude participants on the basis of some criteria, for example, if they withdraw from the experiment or fail to pass an attention check. You can achieve this by using Branch Nodes in conjunction with data saved to the Store.
Click to view an Example of an experiment where participants are branched to a Reject Node if they select 'Yes' in answer to a withdrawal question.
Click to view a Demo experiment that sends participants to a Reject node if they fail a manipulation check.
The Redirect Node is dark-grey with a icon in the top left corner.
Redirect Nodes allow you to move participants between Gorilla and an external site, questionnaire or task and return to Gorilla. This can be useful when you wish to use more than one research platform. For example: you can use the Redirect Node when you want to link to a Qualtrics Survey, Millisecond Task or a pre-hosted jsPsych or PsychoPy task.
You can even chain surveys from multiple sources together with your Gorilla Tasks and Questionnaire components, making use of Gorilla's advanced Control Nodes to, for example, randomise participants between your external tasks.
Another use case for the Redirect Node is running longitudinal studies using Prolific. Use the Redirect Node to send participants back to Prolific at the end of each session. You can then initiate each following session as a new study on Prolific, using the same Gorilla Study URL and a custom allowlist containing the Prolific IDs of the participants from the first stage. For more information, see our page on longitudinal studies.
Link the Redirect Node into your tree at the point when you wish the participant to do a task or questionnaire which is hosted outside of Gorilla, or send your participants back to the recruitment service at the end of a session.
When a Participant reaches a Redirect Node, they are sent via a URL to the external site. The participant then completes the external task, questionnaire, or reads the documentation, and then returns to Gorilla to continue your experiment via a link.
Redirect Nodes only allow a participant to return to a Gorilla task if paired with a Return URL in the external resource. Otherwise, the participant will remain on the external site they have been redirected to. The Return URL you use will depend on the recruitment policy you have chosen and how you have set up the Redirect Node - see 'Completion' section below.
When the participant follows the Return URL and returns to Gorilla, they may have to log in again, for example with a public ID. The participant would then progress to the next Node in your experiment tree, dependent upon the type of 'Completion' option you have chosen.
Please note:
You will need to use a recruitment policy which supports a participant returning into your experiment. The Simple Link recruitment policy can therefore only be used if you are using the 'Completion Token' method for the 'Completion' configuration setting.
We appreciate that the terminology is confusing, but 'Completion Tokens' are not the same as Participant tokens. Using the Redirect node will not consume any reserved participant tokens as these are only spent once the participant reaches the Finish node.
Redirecting to Prolific
Use-case: Running longitudinal/multi-part studies
In Gorilla
In the URL field, paste your Prolific study's completion URL so that participants can be redirected back to Prolific at the end of each session. The URL should be the same for each session. This will change the status of the participants' submission on Prolific to 'Awaiting Review', ready for you to approve their payment and to see which Prolific IDs need to be invited back for the next session. For details of how to set up the subsequent sessions in the same experiment tree, take a look at our Prolific recruitment policy page.
In Prolific
Each session you should use the same URL for your Gorilla experiment in Prolific's Study Link setting (make sure 'I'll use URL parameters' is selected). The automatic integration between Prolific and Gorilla means that Gorilla will always remember where in the tree a participant needs to be placed in order to resume the experiment based on their unique Prolific ID.
Redirecting to Qualtrics
In Gorilla
In the URL field, paste the anonymous link that can be found on the Qualtrics Distribution Tab. Then give the Append PublicID a memorable name, for example, subjectid. From the Completion dropdown, select Completion Token. Click Save to save the changes to the node.
In Qualtrics
In the Survey Flow Tab of the questionnaire, you will need to embed both the appended publicID and the completion token to be stored by Qualtrics. To do this, add a new element and select 'embedded data' and enter the chosen names for your data. These will need to match across Gorilla and Qualtrics, so in this example we would enter subjectid and completion_token. Then, drag this embedded data to the top of the survey flow. When data is collected, you will be able to see the recorded subjectid and completion_token in the Data & Analytics tab and the survey response within Qualtrics.
To return participants back to Gorilla, go to the Survey Option in Qualtrics and select Survey Termination box at the bottom. In the 'Return to a full URL' field, you will need to add to pieces of information. First the return Gorilla URL https://research.sc/participant/login/resume/
and the code that tells Qualitrics to look for the completion token. If you have set this up the same way as above, this will be: ${e://Field/completion_token}
. The final URL to enter in this case would be: https://research.sc/participant/login/resume/${e://Field/completion_token}
. Click Publish to save the changes to the survey.
URL
Paste here the link of the external site that you want your participants to be redirected to.
Append PublicID
If set, append the participant's PublicID to the Onward URL above, along with the prefix-value assigned here. For example, if you enter the prefix-value here as id this will result in the participant being redirected to http://www.your-onward-url-above.com?id=PUBLICID
Use this option if your onward URL will need an identifier from the participant.
Append External Session ID
If set, append the participant's External Session ID to the onward URL in the query string. Enter the variable name you would like to use. For example, the value externalID will result in the participant being redirected to http://www.your-onward-url-above.com?externalID=EXTERNALSESSIONID
Append Embedded Data
If you want to append some other data Fields from the Store, enter them here, separated by commas. By default, they will be appended with the same name. If you need to append the values, but with a different name, enter the name of the Field followed by the name to use in the URL, separated by a colon.
For example, entering val1, val2:myval will result in http://www.your-onward-url-above.com?val1=VAL1&myval=VAL2
Redirection
Select either ‘Redirect immediately’ or ‘Show a message first’. ‘Redirect immediately’ means that as your participant finishes the previous node, they will be automatically redirected. ‘Show a message first’ allows you to inform your participants of this redirection. Participants will be redirected when they press a ‘redirect’ button. When selected, the following configuration settings appear:
Enter your content as you would in the Task or Questionnaire Builders.
Completion
This controls what happens to participants when they return to Gorilla after being redirected. There are three different completion options:
Immediate is the default option. When participants return to your experiment after being redirected they will immediately move to the next Node in your Experiment Tree. You will need to use a recruitment policy which allows a participant to return under the same ID. With most integrated third-party recruitment policies, you should be able to use the Experiment URL to link the participant back to your experiment, but we cannot guarantee this will work with every recruitment policy. Be sure to test this with your specific recruitment policy before you send the experiment live. If the Experiment URL does not work for your recruitment policy, we recommend instead using the 'Completion Token' method and appending the participant's completion token to the Return URL to ensure they are recognised as the same participant on returning.
Delay prevents your participant from returning to Gorilla from the redirected site for the time period that you specify, after which they will be moved to the next Node.
If you select this option, additional configuration settings will appear:
Enter numbers into each field as required. Decimal numbers cannot be entered.
Completion Token allows you to monitor whether the participant has completed the task/questionnaire that you have redirected them to.
Link participants back to your experiment using the following base URL: https://research.sc/participant/login/resume/
You must append the participant's specific completion token to the end of this URL, or the participant will not be recognised as having completed your external task. You will most likely need to use JavaScript to extract the participant's completion token from the Redirect URL and append it to the Return URL. To see an example of how to do this, visit our Redirect Node example page, right-click and select 'View Page Source'. The relevant script is in the function generateURL() at the bottom of the HTML code.
When participants return through this uniquely generated URL, they will register as having completed the task and automatically continue your experiment starting from the next tree node. If they do not return with the completion code, they will be redirected again to your external site until they finish the task and are returned to Gorilla with the completion code.
If you select this option, another configuration setting will appear, named ‘Completion Token Name’. This is optional and allows you to change ‘completion_token’ in the Redirect URL to a name of your choice.
Click to view an Example experiment that uses the Redirect Node.
Checkpoint Nodes are dark-grey with a icon in the top left corner. There is no screen associated with the Checkpoint Node; it is invisible to the participant.
The Checkpoint Node is useful for when you want to keep track of how far your participants have gotten through your experiment. When a participant passes through a Checkpoint Node this will be recorded in the metrics. The information is also available on the Participants tab of your experiment: The name of the last checkpoint passed through by a participant will be listed under the 'Checkpoint' column.
The classic use case for the Checkpoint Node is immediately after a consent questionnaire. When used in this way you can determine how many participants left your experiment because they did not consent.
They are also useful to keep track of participants returning for subsequent sessions in longitudinal studies.
The Checkpoint Node adds 1 new data column to your metrics spreadsheet for each Checkpoint Node in your experiment:
Column Name | Description |
---|---|
Checkpoint Name | Will display the name of your checkpoint if that checkpoint has been completed. e.g. 'consent given' |
Name
Enter a name for the Checkpoint.
It is most useful if the name is meaningful. e.g. 'consent given', if used as a checkpoint after your consent questionnaire.
Reward nodes are purple with a icon in the top left corner.
Reward Nodes allow you to give a reward (e.g. a voucher or gift card) to any participant that reaches this node. Reward Nodes can be used in a number of different ways:
Currently, rewards are implemented through a partnership with BHN Rewards . In order to use rewards in Gorilla, you will need to sign up for a BHN Rewards account . Once you have done so, follow our integration guide to trigger rewards using the Reward node.
Delay Nodes are orange with a icon in the top left corner.
Tutorials that use this Node
The Delay Node allows you to 'suspend' or 'delay' a participant from continuing your experiment.
It prevents a participant from taking part in the rest of your experiment (i.e. nodes which come after the delay node) until the specified time has elapsed. The delay will be timed from when the participant first reaches the Delay Node.
This node is useful if you wish to have controlled time delays between different parts of your experiment: for example, between a teaching and testing phase, in order to measure performance at regular intervals, or longitudinally.
Note: For your Delay Node to function correctly, Gorilla needs a way to recognise your participants when they return. This is easiest to achieve by using an ID-based recruitment policy, which allows your participants to return by logging in or clicking their personalised link. If you instead choose to use an anonymous recruitment policy such as Simple Link, you must check Send Reminder and Reminder Form in the configuration settings of the Delay Node, or it will be impossible for your participants to return and complete your experiment! This will require collecting participants' email addresses, so make sure you have ethical clearance for this first.
Title
This is the title of the dialog box which will be displayed to participants when they reach this node.
Message
This is the message which will be displayed in the dialog box which the participants will read when they reach this node.
Days
Here you specify the number of Days you wish to delay your participant for. This will delay them from taking part in the rest of the experiment until 00:00 (midnight) after the specified number of days has elapsed.
A 'day' is measured as starting at 00:00 (midnight) the next day. Thus if a participant enters your experiment and hits the delay Node at 23:50, and the delay is set to 1 day, it will be possible for that participant to start their next experiment phase within 10 minutes i.e. at 00:00 (midnight). If you wish for a participant to have a minimum number of hours' delay, use the 'Hours' Setting in conjunction with this.
If you wish your delay to be less than a single Day, then leave this blank or type 0 here. Instead enter your time under the 'Hours' or 'Minutes' settings.
Hours
Here you specify the number of hours you wish to delay your participant for. This will delay them from taking part in the rest of the experiment until the specified time has elapsed.
If you wish to set a delay of 24 hours or less, then you must leave the 'Days' field empty and enter in this field the number of hours you wish for the duration of the delay.
If you are using a delay in days, then this field will specify the number of hours of delay that will be added after 00:00 (midnight) is reached. Use this combination if you wish your participant to start at a specific time of day. e.g. a delay of 1 Day + 8 hours will mean your participant will be prevented from taking part in your experiment until 08:00 the next day.
If you wish your delay to be less than a single hour then leave this blank or type 0 here. Instead enter your time under the 'Minutes' setting.
Minutes
Here you specify the number of minutes you wish to delay your participant for. This will delay them from taking part in the rest of the experiment until the specified time has elapsed.
If you have entered a delay time under the 'Hours' setting as well, then the two times will be added together.
Send Reminder
Note: This setting will only have an effect if you are using a recruitment option which uses the participant's email address, or if you also use the 'Reminder Form' Setting. If checked, a reminder email will be sent to the participant once your specified delay time has elapsed and they are able to continue.
Reminder Form
Note: The participant's email address will be visible on your participant dashboard, so you must ensure you have ethical clearance to collect this data. If checked, display a reminder form that prompts a participant to enter their email address. If they do so, they can then be sent a reminder if the 'Send Reminder' option is also enabled.
If you are using any of the anonymous recruitment policies, such as Simple Link, you must check both this setting and 'Send Reminder' above, or your participants will have no way to return and complete your experiment.
Quota Nodes are orange with a icon in the top left corner.
Tutorials that use this Node
The Quota Node allows you to specify a separate recruitment quota for a part of your experiment. Like the Start, Finish and Reject Nodes, the Quota Node is partly configured on your Experiment's Recruitment tab. Quota Nodes act like a ticket gate, only allowing participants to continue on with your experiment if there are enough spaces left in your quota.
Quota Nodes have two exit branches; 'ACCEPT' and 'REJECT'. By default, participants will continue down the 'ACCEPT' branch of your experiment until your Quota limit is reached. Once your Quota is full, participants will be sent down the 'REJECT' branch.
How to set up a Quota Node:
The Quota Node is typically used in conjunction with Branch or Randomiser Nodes when you require an exact number of complete participants per 'branch'. Usually the ACCEPT branch of the Quota Node will eventually end at a Finish Node, whereas the REJECT branch of the Quota Node will end at a Reject Node. View the image example below for a typical experiment set up using the Quota Node.
Notes:
Configuration options available on the Quota Node:
Configuration options for Quota Nodes available on your Experiment's Recruitment tab:
In the example, above you can see that only 2 (StimuliSet1 and StimuliSet2) of the 4 possible Quotas are in use. Both Quotas are set to recruit 50 participants. The two other Quotas (YesQuota and NoQuota) have been disabled.
The image below shows a typical experiment set up using the Quota Node:
The image below shows the Recruitment tab for the above experiment. Notice how the Quotas themselves have separate recruitment status and progress bars.
The Quota Node adds 1 new data column to your metrics spreadsheet for each Quota Node passed through by the participant:
Column Name | Description |
---|---|
quota-nodekey | Will display the status (ACCEPT or REJECT) of the participant passing through the Quota Node. ACCEPT means the participant was counted towards your quota and continued down the ACCEPT branch of your Quota Node. REJECT means the quota was full when the participant reached your Quota Node and continued down the REJECT branch of your experiment. If you have more than one Quota Node, and the participant can only pass through one, the column for the other Quota Node will be left empty. |
Quota
Select a name from a drop down list of possible quotas.
To create a new Quota select, 'Create New...' Option. Then type a name for your new Quota.
Recruitment Target
On the Recruitment tab of your Experiment, click 'Change Recruitment Target' to open the Recruitment Target menu. Here you will be presented with two options for each quota:
1) Quotas
Type a number to set a Recruitment Target for each named Quota.
2) Enable/Disable
Click the button to toggle the status of a quota.
By default all quotas start as Enabled. This means participants who reach your Quota Node will continue down the ACCEPT branch until your Quota is full.
Click the 'Disable' button to Disable a Quota. Participants who reach a Quota Node which has been disabled will continue down the REJECT branch of your Quota Node until they complete your experiment - regardless of how many participants were previously recruited in this quota.
Click the 'Enable' button at any time to re-Enable a disabled Quota. Recruitment for this quota will then continue from where you left off.
Note: Disabling a Quota will not remove the Quota Node from your experiment. If you wish to stop using the Quota to control recruitment to a section of your experiment you should remove the Quota Node from your experiment on your experiment's Design tab and Commit the new version of your experiment.
Repeat Nodes are orange with a icon in the top left corner. Unlike other Nodes, the Repeat Node is a dual Node system linked with arrows.
The Repeat Node allows you to specify a section of your experiment you wish your participants to repeat.
Participants who enter the bottom Repeat Node, will follow the arrow to the top Repeat Node. When linked in with the rest of your experiment tree, this enables the participant to repeat that section of your experiment.
This node is useful if you wish to have participants repeat the same task or sequence of tasks/questionnaires: for example, to repeat a sequence of training task nodes in a training study.
Notes:
The Repeat Node will add metrics to the following column when included in your experiment:
Column Name | Description |
---|---|
Repeat Key | This column will contain the key for the repeat node. This will consist of the words repeat-key, the node key for the Repeat Node, then the number of the repeat. For example, if this is the second repetition of a task/questionnaire, this will end in #2. e.g. repeat-ryfw#2 |
Repeats
Type a number for the maximum number of times a participant will see this sequence of nodes.
For example, if you type 2, then the participant will see this sequence of nodes exactly 2 times in total: once initially and then once when they repeat them.
You could combine Repeat Nodes and Branch Nodes so that only those participants who don't meet certain criteria, for example don't score highly enough, will repeat the trials until they pass the test and can move onto the next part of your experiment.
In the example above, participants will move onto another task if they fulfill the Pass branch criteria from the task, and will be directed to repeat the task if they fulfill the Fail branch criteria.
NOTE: In order for the Repeat node to work correctly in combination with the Branch node, you would need to make sure that the score is reset before each repeated time that participants complete the task. This way, for every repeat, they would have a new score based on which they will be branched - independently of their previous score. To achieve this, you would need to add a Set Field on Start component to the task that ought to be repeated. Simply set the value to zero at the beginning of your task, so that it starts from scratch every time.
Click to view an Example of the Repeat Node.
Click to view an Example of the experiment using the Repeat and Branch Nodes.
Switch Nodes are orange with a icon in the top left corner.
Tutorials that use this Node
Switching between Tasks Tutorial
The Switch Node, which has to be used in conjunction with the Switch Component, allows participants to switch between two tasks, two questionnaires, or a task and a questionnaire during your experiment.
Unlike other Nodes, the Switch Node doesn't connect directly into the overall flow of the tree; instead, you 'tether' the Switch Node between two Tasks or Questionnaires. You can do this by dragging from the lighter areas on each side of the Switch Zone to the tasks or questionnaires you want to tether. One task/questionnaire (the primary task) will be linked directly into your tree and will be the first task the participant sees. The other task/questionnaire (the secondary task) will not be linked to your tree directly and will only be seen by the participant if they switch to it via a Switch button.
The Switch Node is also special in that it always requires both tasks/questionnaires connected to the Switch Node to contain a Switch component.
The Switch component for tasks grants the participant a button within the task, which allows them to switch between the two tethered task or questionnaire nodes.
The Switch button component for questionnaires grants the participant a button within a questionnaire, which allows them to switch between the two tethered task or questionnaire nodes.
The Switch Node is useful in experiments where you wish to test a participant's task preference: e.g. see how long participants spend on a maths task compared to a word-based task. It can also be useful when you wish to test comprehension of a document, e.g. see how many times participants refer to text in a questionnaire in order to answer questions about it.
The Switch Node example below is set up to give the participant a maximum of 10 switches between the two tasks, with the completion criteria set to an overall Time Limit of 30s (30000 ms):
The Switch Node adds 5 new data columns to your metrics spreadsheet:
Column Name | Description |
---|---|
switch-nodekey-time-primary | This is the total time (in ms) the participant spends on the primary task. |
switch-nodekey-percentage-primary | This is the time the participant spent on the primary task displayed as a percentage. |
switch-nodekey-time-secondary | This is the total time (in ms) the participant spends on the secondary task. |
switch-nodekey-percentage-secondary | This is the time the participant spent on the secondary task displayed as a percentage. |
switch-nodekey-switches | This is a count of the total number of switches a participant made between the primary and secondary tasks. |
The Switch Node also adds the following rows to your metrics spreadsheet each time a Switch Button is pressed:
Column Name | Row Entry | Description |
---|---|---|
Response | SWITCH | This is the reaction time (in ms) at which the participant pressed the Switch Button. |
Response | SWITCH ELAPSED | This is the total time (in ms) that the participant has spent on the task before pressing the Switch button. |
Max Switches
Type a number to specify the maximum number of times that the participant can switch between tasks.
Default = blank; infinite. Leave blank for unlimited switches.
Completion Criteria
Select from the dropdown the criteria for completing the switching task:
Note: you must set a time (in ms) in the 'total time limit' setting for the Time Limit setting to work correctly. Do not use this setting when switching between two questionnaires. This is because questionnaire metrics are recorded upon completion of a questionnaire. The Time Limit criteria means that neither questionnaire may be finished, meaning no metrics are recorded.
Total Time Limit
Note: This setting will only be applied if using the 'Time Limit' completion criteria.
Type a numerical value for the total (maximum) amount of time (in ms) a participant may spend across the two tasks.
Randomiser Nodes are orange with a icon in the top left corner.
The Randomiser Node allows you to distribute participants at random between 2 or more different paths through your experiment tree. The most common use case is when you have a between-subjects design and want to assign participants at random to conditions of your task.
Randomiser Nodes are evaluated as soon as the participant reaches them. The participant then advances to the next node in the tree, on the branch that they are assigned to by the Randomiser Node.
There are two parts to setting up a Randomiser Node.
For example, consider a situation where you wanted to have two groups, one for an easy branch and the other for a hard branch, with a ratio of 2:1 respectively. The first group can be given the name 'easy' and a ratio of '2'. The second group can be given the name 'hard' and a ratio of '1'.
Notes:
Randomiser Nodes have no knowledge of subsequent attrition. See our Randomisation and Attrition guide for more information.
In Preview mode, a Randomiser Node set to 'Balanced' will act like a Randomiser Node set to 'Random'. The Randomiser Node has no knowledge of previous previews, as these are not recorded. This means it will act independently of any prior events.
If you use the Randomiser node in conjunction with a Repeat Node then the randomisation will only occur once and then remain the same on each repeat.
The Randomiser Node adds 1 new data column to your metrics spreadsheet for each Randomiser Node in your experiment:
Column Name | Description |
---|---|
randomiser-nodekey | This column contains the group name of the randomiser branch this participant was assigned to. e.g. ‘easy’ or ‘hard’. |
Group Allocations
Note: Group names MUST be unique and the Group field cannot be left empty.
Ratio of participants that will be assigned to this branch of the Randomiser.
The exact mathematics of how the ratio is used depends on the randomisation mode (see below), but the proportion of participants assigned to any one branch will always be equal to that branch's ratio divided by the sum of all ratios.
The following settings apply to the node as a whole:
Randomisation Mode
[Default] So for two branches with ratios 10 and 10, for every 20 participants, 10 will get the first branch and 10 will get the second. This is random without replacement.
Therefore, two branches with ratios 1 and 1 is identical to two branches with ratios 50 and 50. This is random with replacement.
Store Name
If set, store the allocated group to a Field in the Store/save it to participant data using the entered name. This means you can use a Branch Node, for example, to control what participants see based on the Randomiser Branch they were assigned to. You can view an example of how a Randomiser Node and Branch Node can be configured in this way, in this experiment.
Click to view an Example of the Randomiser Node.
Click to view an Example of the Randomiser Node used in an experiment with the Branch Node.
Check out a Gorilla Academy case study of using the Randomiser Node to allocate participants to conditions in the context of a real experiment.
The Branch Node is orange with a icon in the top left corner.
Tutorials that use this Node
Performance Branching Tutorial
Branching from a Questionnaire Tutorial
Branch Nodes allow you to direct participants down different paths (or branches!) of your experiment tree based on their responses to questionnaires or their performance in tasks. Branch Nodes are evaluated as soon as the participant reaches them. The participant then advances to the next Node in the tree, on the branch that they are assigned to by the Branch Node.
Note: Before adding a Branch Node to your experiment, you must first set up your Task or Questionnaire to save participants' responses or scores to the Store. Find out how to do this using our Binding guide.
If you wish to direct your participants down different paths of an experiment randomly, not based on performance, then you should use a Randomiser Node instead.
In the example below, the Branch Node is set up to divide participants into two groups, DogOwned and NoDogOwned. It does this by checking the Property owned_dog. owned_dog corresponds to the Key of a Questionnaire widget that asks participants if they have ever owned a dog. The Questionnaire containing this widget comes before the Branch Node in the Experiment Tree. Participants who answered 'Yes' to the question of whether they have ever owned a dog are assigned to the DogOwned group. Otherwise, participants are assigned to the group NoDogOwned, which is selected as Default.
The Branch Node adds 1 new data column to your metrics spreadsheet for each Branch Node in your experiment:
Column Name | Description |
---|---|
branch-nodekey | This column contains the group name of the branch this participant passed through. e.g. ‘Pass’ or ‘Fail’. |
Group
Enter the name of the branch that the participant will be directed down if they match its criteria.
Note: Group names MUST be unique and the Group field cannot be left empty.
Property
This is case sensitive.
Enter the name of the property from a preceding node that you want to test. This is the name of your Store Field that will be evaluated.
For both, task and questionnaires, this will be the name you gave to the Field of the Store you saved responses from your participants from.
Rule
Select a rule from the dropdown menu to apply to the data from the Store.
Value
This is case sensitive.
This is the value required to satisfy the rule. The value of the Store Field will be compared to this Value in accordance with the selected rule.
In the case of Questionnaires: this Value will be one of the corresponding answers offered in your questionnaire configuration associated with the Store Field above.
In the case of Tasks: there are several possibilities for the Value depending on for which reason you have declared a Field for the Store. For example, by using the Save Accuracy component in the Screen tab, you can make a Field for the amount correct or incorrect answers. In this case, your value would be the number saved here. You could also save text responses participants provide, in which case the answer participants give will be the 'Value'.
Default
When checked, this branch is the default branch for progression. Participants who do not match any rules in the branch node will be assigned to the default branch.
Order Nodes are orange with a icon in the top left corner.
The Order Node allows you to randomise the order of Task Nodes and Questionaire Nodes within your experiment tree. The most common use case is when you have a within-subjects design (i.e. all participants do the same series of tasks) and want to control for order effects.
Order Nodes are special in that they are not part of the overall flow of the tree. Instead, you 'tether' Task and Questionnaire Nodes to the Order Node, allowing it to control their order. You can do this by dragging from the lighter area of the Order Node to the task or questionnaire you want to tether.
Notes:
The Order Node adds 1 new data column to your metrics spreadsheet for each Order Node in your experiment:
Column Name | Description |
---|---|
order-nodekey | This column contains the order that the Order Node assigned the participant to see the nodes. Nodes are referred to by letters corresponding to their original order as laid out in the Experiment Tree. e.g. BCA would mean this participant saw the second node, followed by the third node, followed by the first node. |
Randomisation Mode
Select a Randomisation Mode from the dropdown menu:
In both cases, as far as possible, Gorilla will attempt to assign the same number of participants to each task order.
Click to view an Example of the Order Node.
Counterbalance Nodes are Orange with a icon in the top left corner.
Tutorials that use this Node
The Counterbalance Node can be used, in conjunction with either 1) the Spreadsheet Manual Override setting or 2) the source type Spreadsheet Manipulation, to assign different stimuli sets to each participant.
For example, if you have 4 stimuli sets, you could set up a Randomiser node with 4 paths, where each path goes to an instance of your task set up with a different spreadsheet, such that each task instance will show a different stimuli set. With 4 stimuli sets this is doable, but if using any more this set-up becomes tedious. Instead, a counterbalance node can be used to achieve the same end, but only needing one instance of the task.
This is particularly powerful method if you want to run large numbers of participants (1000) covering a large number of stimuli sets. If however you wish to make use of the quota node for each stimuli set, then you will need to use the Randomiser Node to individually set a quota for each option.
There are 2 possible methods of setting up the Counterbalance Node. If you need to counterbalance the contents of multiple spreadsheet columns between participants, you will need to use method 1. If you only need to counterbalance the contents of one spreadsheet column between participants, you can use either method. Which method you choose will depend on whether it is more convenient for you to make a separate spreadsheet for each of your stimuli sets (method 1), or to include all your stimuli sets in separate columns of one spreadsheet (method 2).
Note: If you use the Counterbalance node in conjunction with a Repeat Node then the counterbalancing will change between participants but within one participant's experiment tree the counterbalancing will remain the same on each repeat.
1) Image of Configuration Options of the Counterbalance Node:
2) Image of Configuration Options of the corresponding Task Node set up using Spreadsheet Manipulation (Method 2):
The Counterbalance Node adds 1 new data column to your metrics spreadsheet for each Counterbalance Node in your experiment:
Column Name | Description |
---|---|
counterbalance-nodekey | This column contains the value in the Counterbalance Node (i.e., spreadsheet or spreadsheet column) that was assigned to this participant. e.g. images1. |
Name
Set the name for your Counterbalance Node. This is the name you will enter as Store Field (i.e., inside curly brackets after two $ signs) in either the manual spreadsheet override or the spreadsheet manipulation settings of your task node.
Values
List the names of your spreadsheets (Method 1), or of the spreadsheet columns used in your spreadsheet manipulation (Method 2), separated by commas. Participants will be assigned values randomly without replacement: for example, if you have 5 values, then for every 5 participants who enter your experiment, one will be assigned each value.
Allocator Nodes are orange with a icon in the top left corner.
The Allocator Node randomly allocates participants to different branches of the node, with attrition sensitivity. You can think of an Allocator Node as a combination of the Randomiser Node and Quota Node in one.
To configure the Allocator Node, you will need to set up the different groups that you would like to randomly assign your participants to. Then, set the maximum number of participants you would like to be allocated to each group.
As Live participants get rejected via Reject Nodes, a Time Limit or manual rejection, the Allocator Node will recognise this and automatically balance the assignment of future participants that enter the experiment to ensure that the Maximum Allocation is met.
Once the different groups have been configured, the Allocator Node will automatically create an additional Overflow branch. This branch is important when the Recruitment Target is greater than the combined total of the Max Allocation in the Allocator Node branches. If the maximum allocation has been filled with live or completed participants, we need to direct any extra participants elsewhere using the Overflow branch. For example, this Overflow branch could link to a Reject Node, or to a specific condition in your experiment if you do not want to reject participants.
Note: If you use the Allocator node in conjunction with a Repeat Node then the allocation will change between participants but within one participant's experiment tree the allocation will remain the same on each repeat.
The Allocator Node adds one new data column to your metrics spreadsheet for each Allocator Node in your Experiment.
Column Name | Description |
---|---|
allocator-nodekey | This column contains the group name of the allocator branch this participant was assigned to. e.g. Group 1 or Group 2. |
Group Allocations
1. Group
Enter the name of the branch that participants will be directed down if they are assigned to this group.
Note: Group names must be unique and the Group field cannot be left empty.
2. Max Allocation
Enter the maximum number of participants you would like to be assigned to this Group.
Store Name
If set, save the allocated group to the Store/ participant data using the entered name. This means that you can use a Branch Node later in your experiment to control future group assignment, based on the Allocator group they were assigned to.
Click to view an Exampleof the Allocator Node.
The Lobby Node is used in multiplayer experiments to group together participants who are going to play together. Participants who are grouped together for multiplayer experiments are put into the same room (so everyone starts off in the lobby and then gets assigned to a room with the other players they are going to play with). The size of the room depends on how many players the task is for - so for a two-player task, we want two participants in each room, for a four-player task, we want four in each room, etc.
Participants who reach the Lobby node will wait there until they have been matched with enough other players to proceed. We call this process matchmaking:
You can read more about setting up multiplayer experiments in the Multiplayer How-To Guide
The Live Branch Node behaves similarly to a normal Branch Node (with the same set of settings). However, like the Live Gate node, you are provided with a link that allows you to edit live which branch participants should go down. So if, at some point during the experiment, you want to override the current branching and force all participants to go down a particular branch, you can use the link on the Live Branch node to do this.
Branches
Embedded Data Field
You can save the name of the branch participants were allocated to by creating a new Field in the Store.
The Live Gate Node allows you to dynamically control the progress of participants. Participants that arrive at the Gate node will initially be held at that node, behaving as though it were a Delay Node. However, the researcher can control when the Gate 'opens' via a specific URL provided to the researcher in the Experiment Tree.
Once opened, participants will be moved on to the next node in the tree automatically. An example could be if you are running a live event and want participants to be held at a certain point until you are ready for them to proceed to the next stage of the experiment. You can use a Live Gate Node to do this. Participants will be held here until you open the Gate via the link provided on the node. You could also use this as a replacement for a Delay node in the case where you want participants to be able to progress on a specific date/time, rather than a set delay from when they arrive. Once the 'Gate' has been opened, participants will automatically pass through it when they arrive there.
Title
You can display a title to participants once they reach this node and wait for the Gate to open.
Message
You can display a message to participants once they reach this node and wait for the Gate to open.