Support Home Experiment Builder Experiment Tree Nodes

Experiment Tree Nodes

  • Overview
  • Study Nodes:
  • Questionnaire
  • Task
  • Core Nodes:
  • Start
  • Finish
  • Reject
  • Redirect
  • Checkpoint
  • Reward
  • Control Nodes:
  • Delay
  • Quota
  • Repeat
  • Switch
  • Randomiser
  • Branch
  • Order
  • Counterbalance
  • Allocator
  • Lobby
  • Live Tree Nodes:
  • Live Branch
  • Live Gate

Overview


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'.


Tooling Reference Guide Format:


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 Node


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.

Image of a questionnaire node when added to the Experiment Tree

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.



Questionnaire Node configuration pop-up window in the Experiment Tree

Configuration Settings

Randomise questionnaire elements? (Questionnaire Builder 1 only)

Default = No

Whether to randomise the order of questionnaire elements. Options: Yes / No / Yes (except first) - for randomising everything except instructions / (Manual Override) - allows you to set the value of this dropdown based on embedded data.

This setting only appears for questionnaires built in the legacy Questionnaire Builder. For questionnaires built in Questionnaire Builder 2, you can control randomisation within the questionnaire itself using the randomisation settings.


Task Node


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.

Image of a task node when added to the Experiment Tree

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.



Task Node configuration pop-up window in the Experiment Tree

Configuration Settings

Manipulations

See image example of the configuration settings above.

  1. 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.

  2. 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 Node


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.

Image of a Start node when added to the Experiment Tree

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.

Pro Tip

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.



Start Node configuration pop-up window in the Experiment Tree

Configuration Settings

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 Node


Finish Nodes are dark-grey with a icon in the top left corner.

The Finish Node marks the end-point(s) of your experiment.

Image of a Finish node when added to the Experiment Tree

Once participants reach a Finish Node, they can perform no further tasks or questionnaires. At this point the participant:

  • Will be sent to Gorilla's finish screen and are marked as 'Completed' on the Participants tab.
  • Will be counted towards your recruitment progress.
  • Will be included in your downloadable data.
  • Their reserved Token will be consumed.

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.



Finish Node configuration pop-up window in the Experiment Tree

Configuration Settings

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 Node


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.

Image of a Reject node when added to the Experiment Tree

Reject Nodes differ from the Finish Node in four ways: Participants who end at a Reject Node are by Default;

  • Marked as 'Rejected' on your Participants page.
  • Not counted towards you Recruitment Progress.
  • Not Included in your downloadable data.
  • Their reserved token is Returned.

Samples that use this node

Reject Node Demo (Manipulation Check)

Reject Node Example (Participant Withdrawal)


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.



Reject Node configuration pop-up window in the Experiment Tree

Configuration Settings

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:

  1. Exclude: Default

    • When a participant reaches the Reject Node, their reserved token is Returned.
    • Participant not included in your experiment's downloadable data.
  2. Include:

    • When a participant reaches the Reject Node, their reserved token is Consumed.
    • Participant is included in your downloadable data.
    • Participant counts towards your Recruitment Progress.

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.


Using the Reject Node in combination with the Branch Node

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.


Redirect Node


The Redirect Node is dark-grey with a icon in the top left corner.

Image of a Redirect node when added to the Experiment Tree

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 should initiate each following session as a new study on Prolific, using the same Gorilla recruitment URL and a custom allowlist containing the Prolific IDs of the participants from the first stage. It's easiest if you set up all the studies (one per session) on Prolific in advance. Create a study for the first session, then duplicate this study to create the subsequent sessions - this should ensure that the completion URL that goes in each Redirect Node stays the same. If you instead create a new study on Prolific for each session, you will need to ensure that the completion URL entered in each Redirect Node of your Gorilla experiment is correct for the Prolific study that corresponds to that session. 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.


Samples that use this node

Redirect Node Example


Please note:

  1. 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.

  2. 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.



Redirect Node configuration pop-up window in the Experiment Tree

Pro Tip

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 may be different each session, so you should set all your studies up on Prolific in advance. Often, duplicating your studies in Prolific helps to keep the completion URL the same. When participants are redirected back to Prolific, it will change the status of the participants' submission 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.

Configuration Settings

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:

  1. Title
  2. Message
  3. Button Text

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:

  1. Default = ‘Immediate’
  2. ‘Delay’
  3. ‘Completion Token’.

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:

  • Days
  • Hours
  • Minutes

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 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.

Image of a Checkpoint node when added to the Experiment Tree

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.



Checkpoint Node configuration pop-up window in the Experiment Tree

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'

Configuration Settings

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 Node


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:

  1. They are useful for triggering participant payment based on how far through the experiment your participant has got.
  2. They can be used in conjunction with 3rd party recruitment services to implement variable rewards.
  3. They can be implemented on their own in order to provide rewards to participants on any recruitment policy.

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 Node


Delay Nodes are orange with a icon in the top left corner.

Image of a Delay node when added to the Experiment Tree

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.


Tutorials that use this Node

Delay Node Tutorial



Screenshot of the Delay Node configuration settings in the Experiment Tree

If the 'Send Reminder' and 'Reminder Form' settings are ticked, the following will display to participants when they reach the Delay Node:

Screenshot of the reminder form seen by participants if Reminder Form setting is ticked, with a box to enter their email

Once the participant has entered their email address, they will see the following:

Screenshot of message seen by participants after entering their email: 'You will be sent an email when it is time to resume'

Configuration Settings

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 Node


Quota Nodes are orange with a icon in the top left corner.

Image of a Quota node when added to the Experiment Tree

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:

  1. Add a Quota Node into your Experiment Tree flow
  2. Using the dropdown, either select a Quota name from the list or select 'Create New...' to add a new quota.
  3. On your experiment's Recruitment tab, set a recruitment target for each of your Quotas.

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.


Tutorials that use this Node

Quota Node Tutorial


Notes:

  1. Quota Nodes are used to control recruitment numbers for your experiment and therefore have the same effect on recruitment state as the overall Recruitment Target. For example, if all the Quotas for your experiment are full, participants will be prevented from entering your experiment, helpfully stopping you from over-recruiting participants! To allow more participants in your experiment, simply increase your Quota size, or else manually reject 'Live' Participants who have not completed to free up space in your Quotas.
  2. Quota Nodes will not work in Preview mode. No record of Previews are made, so previews do not contribute towards any Quota.

Configuration options available on the Quota Node:

Screenshot of the Quota Node configuration settings in the Experiment Tree

Configuration options for Quota Nodes available on your Experiment's Recruitment tab:

Screenshot of the Quota Node configuration settings in the Recruitment Target section of the 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:

Screenshot of the Experiment Tree set up using a 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.

Screenshot of the Recruitment tab for an experiment in progress using the Quota Node, showing separate recruitment status and progress bars for each quota as well as the experiment overall

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.

Configuration Settings

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.


Settings on the Recruitment Tab:

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 Node


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.

Image of a Repeat node when added to the Experiment Tree

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.


Samples that use this node

Repeat Node Example


Notes:

  1. If you use the Randomiser, Order, Counterbalance, or Allocator Node within a Repeat, each of these nodes will only perform their desire function once and then keep the same settings through each repeat.
  2. Make sure your Repeat Nodes are in the correct order - use the arrow as a guide - trace the path a participant will take through your nodes.


Screenshot of the Repeat Node configuration settings in the Experiment Tree

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

Configuration Settings

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.


Using the Repeat Node in combination with the Branch Node


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.

Experiment Tree where a Repeat node is used in combination with a Branch node

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 Node


Switch Nodes are orange with a icon in the top left corner.

Image of a Switch node when added to the Experiment Tree

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.


Tutorials that use this Node

Switching between Tasks Tutorial



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):

Screenshot of the Switch Node configuration settings in the Experiment Tree

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.

Configuration Settings

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:

  1. Complete Both Tasks [Default]: regardless of number of switches, the participant will be made to complete both tasks fully.
  2. Complete Primary Task: the participant will be made to complete the Primary Task.
  3. Complete Primary Task: the participant will be made to complete the Secondary Task.
  4. Time Limit: Once a set time limit is reached, regardless of the participant's progress in either task, the participant will be advanced to the next node after the primary task in the experiment tree.

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 Node


Randomiser Nodes are orange with a icon in the top left corner.

Image of a Switch node when added to the Experiment Tree

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.

  1. The Group Allocations allows you to give a name to each group and assign a ratio to the group. Additional groups can be added using the 'plus' button.
  2. The Randomisation Mode allows you to decide how the randomisation will occur.

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'.


Samples that use this node

Example: Randomiser and Manipulations


Notes:

  1. Randomiser Nodes have no knowledge of subsequent attrition. See our Randomisation and Attrition guide for more information.

  2. 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.

  3. 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.



Screenshot of the Randomiser Node configuration settings in the Experiment Tree

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’.

Configuration Settings

Group Allocations

  1. Group Enter the name of the branch that the participant 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.

  1. Ratio

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

  1. Balanced means that participants are allocated in the above ratios in sets of the total ratios.

[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.

  1. Random means completely random, with each branch having the probability of its ratio divided by the total ratio.

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.

Pro Tip

Check out a Gorilla Academy case study of using the Randomiser Node to allocate participants to conditions in the context of a real experiment.


Branch Node


The Branch Node is orange with a icon in the top left corner.

Image of a Branch node when added to the Experiment Tree

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.


Tutorials that use this Node

Performance Branching Tutorial

Branching from a Questionnaire Tutorial



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.

Screenshot of the Branch Node configuration settings in the Experiment Tree

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’.

Configuration Settings

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 Node


Order Nodes are orange with a icon in the top left corner.

Image of an Order node when added to the Experiment Tree

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.


Samples that use this node

Example: Order Node


Notes:

  1. The Order Node can only randomise the order of individual nodes. To randomise the order of groups of nodes, lay out the possible orders in your Experiment Tree and use a Randomiser Node to assign participants to each order.
  2. If you use the Order node in conjunction with a Repeat Node, then the order will change between participants but within one participant's experiment tree the order will remain the same on each repeat.
  3. Order nodes will not work in Preview. No record of Previews are made, meaning the node will display the same order irrespective of earlier previews.


Screenshot of the Order Node configuration settings in the Experiment Tree

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.

Configuration Settings

Randomisation Mode

Select a Randomisation Mode from the dropdown menu:

  • Latin Square uses a standard Latin Square design to create a subset of all possible permutations of task order. In this subset, each task will appear an equal number of times at each position in the order.
  • Balanced uses all possible permutations of task order. Note that this quickly gets large (N factorial). For any order nodes connected to 6 or more task nodes, Latin Square will always be used.

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 Node


Counterbalance Nodes are Orange with a icon in the top left corner.

Image of a Counterbalance node when added to the Experiment Tree

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 the elements you need to counterbalance are drawn from multiple spreadsheet columns for each participant -- for example, stimuli and correct answers -- you will need to use method 1. If the elements you need to counterbalance are drawn from a single spreadsheet column for each participant -- e.g., a single stimulus per trial -- you can use either method. Which method you choose in this case 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).

Method 1: Multiple Spreadsheets

  1. Set up your Task. When adding your stimuli or any other task elements you want to counterbalance, bind them to the Spreadsheet.
  2. Upload multiple spreadsheets, each one containing one of your stimuli sets (and any other task elements you want to counterbalance, e.g. corresponding correct answers).
  3. Add a Counterbalance Node to your Experiment Tree. Enter a name in the Name box, e.g. MyCounterbalance.
  4. In the Experiment Tree, in the Task Node following your Counterbalance Node, select 'Manual Override' from the Spreadsheet dropdown menu. In the text box below, enter the name you just entered in the Name field of the Counterbalance Node, enclosed in curly brackets and preceded by two dollar signs. For example, if your Counterbalance Node is named MyCounterbalance, you would enter $${MyCounterbalance}.
  5. Finally, in your Counterbalance Node, list your spreadsheet names in the Values box. Spreadsheet names should be separated with commas. Remember that names are case-sensitive. This will assign different participants to different spreadsheets.

Method 2: Single Spreadsheet with Spreadsheet Manipulation

  1. Set up your Task by binding your stimuli to a Spreadsheet Manipulation. To do this in Task Builder 1, select Spreadsheet Manipulation in Zone Source. To do this in Task Builder 2, select Manipulation, toggle on Advanced Settings, and select 'Look for a spreadsheet column with that name'.
  2. Upload a single spreadsheet containing each of your stimuli sets as separate columns.
  3. Add a Counterbalance Node to your Experiment Tree. Enter a name in the Name box, e.g. MyCounterbalance.
  4. In the Experiment Tree, in the Task Node following your Counterbalance Node, find the settings box for the Spreadsheet Manipulation you set up earlier. In this box, enter the name you just entered in the Name field of the Counterbalance Node, enclosed in curly brackets and preceded by two dollar signs. For example, if your Counterbalance Node is named MyCounterbalance, you would enter $${MyCounterbalance}.
  5. Finally, in your Counterbalance Node, list the column names containing each of your stimuli sets in the Values box. Column names should be separated with commas. Remember that names are case-sensitive. This will assign different participants to stimuli sets drawn from different columns of the spreadsheet.

Tutorials that use this Node

Counterbalance Node Tutorial (uses Method 1)


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:

Screenshot of the Counterbalance Node configuration settings in the Experiment Tree

2) Image of Configuration Options of the corresponding Task Node set up using Spreadsheet Manipulation (Method 2):

Screenshot of a Task Node set up to have the values of the Spreadsheet Manipulation TestList controlled by the Counterbalance Node with name ListVar

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.

Configuration Settings

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 Node

Allocator Nodes are orange with a icon in the top left corner.

A screenshot of the Allocator within the Experiment Tree. The default Overflow branch can be seen.

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.


Samples that use this node

Example: Allocator Node


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.


Image of an Allocator node when added to the Experiment Tree

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.

Configuration Settings

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.


Lobby Node


Image of a Lobby node when added to the Experiment Tree

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 - 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:

Participants enter the lobby individually and leave when assigned to a room with the right number of players

You can read more about running multiplayer experiments in the Multiplayer How-To Guide.


Configuration Settings

Players

This is the number of players that should be assigned to each room. This must match the number of players specified in your multiplayer task.


Title

This is the title which will be displayed at the top of the dialog box which the participants will read 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.


Mode

The Mode setting determines how participants are matched into rooms (i.e., groups that will take part in the multiplayer task together). You can find more information on player matching in the Multiplayer How To Guide.

  1. Automatic means that Gorilla will match participants into rooms for you.

[Default] You can decide whether you want automatic assignment to be completely random, or according to rules that you define. If you want automatic assignment to be completely random, ensure the Matchmaking setting below is unchecked. If you want to define rules for automatic assignment (e.g., to match players with particular characteristics together), ensure the Matchmaking setting below is checked and define your criteria using the Player Criteria settings below.

  1. Manual means that you will manually match players into rooms. Manual assignment happens in the matchmaking room, which can be accessed using the URL that appears at the top of the Lobby node when the experiment is live.

Matchmaking

If this setting is checked, you can define criteria that determine how players should be matched into rooms. Set up these criteria using the Fixed Order and Player Criteria settings below.


Fixed Order

[Only available if Enable Matchmaking is checked]

Once you have set up your Player Criteria (see final setting below), you can use Fixed Order to determine how these criteria relate to player positions. For example, if you want Player 1 to always be male and Player 2 to always be female, enter Player 1 and Player 2 criteria accordingly and then ensure Fixed Order is checked. If you want each room to contain a male player and a female player, but want their player positions to be assigned at random, set up the same criteria but leave Fixed Order unchecked.


Time Limit (ms)

Set the maximum time you want participants to have to wait to be matched. Adding a Time Limit will create a 'Timed Out' branch from the Lobby node which you can connect to another node in your Experiment Tree. Participants who have not been matched after the time limit is reached will proceed down the Timed Out branch instead of the Matched branch.


Mingle Time (ms)

Set the time you want to wait before starting to match participants into rooms. This can allow time for other participants to enter the lobby and create more potential matches.


Mingle Player Count

Set the number of players that need to be in the lobby to trigger matchmaking to start. This setting takes precedence over the Mingle Time setting: for example, if you set Mingle Time to 30000 ms (30 seconds) and Mingle Player Count to 6, then matchmaking will start as soon as 6 players are in the lobby, even if this is before 30 seconds have elapsed.


Player Criteria

[Only available if Enable Matchmaking is checked]

Set up the criteria you want Gorilla to use to automatically match players into rooms. To use a value as a criterion for player matching, it must be saved in the participant's Store. Find out more about saving to the Store in our Store guide.


Field

The name of the Store Field that contains the criterion you want to use for this player. For an example, see the Multiplayer How To Guide.


Value

The value in the Store Field that you want to use as the criterion for this player. For an example, see the Multiplayer How To Guide.


Live Branch


Warning

This feature is currently only available on Early Access - please contact us if you're interested in trying it out!

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.

Image of a live branch node when added to the Experiment Tree
Configuration Settings

Branches

  • Group: Enter the name for the first branch (and any subsequent ones) you want to use. Make sure to choose one group as the default branch.

Embedded Data Field

You can save the name of the branch participants were allocated to by creating a new Field in the Store.


Live Gate


Warning

This feature is currently only available on Early Access - please contact us if you're interested in trying it out!

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.

Image of a Live Gate node when added to 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. The Live Gate Node is also particularly useful for Multiplayer studies - use a Live Gate node before each Lobby node in your study to control the flow of participants through the experiment.

Once the 'Gate' has been opened, participants will automatically pass through it when they arrive there.

Configuration Settings

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.