This Walkthrough is a step-by-step guide to the different ways of using spreadsheets in Gorilla.
To make the most of this guide, cross reference the descriptions with the Walkthrough: Spreadsheets sample project.
In Gorilla, the spreadsheet drives the task. Consequently, you will always need a spreadsheet even for the simplest task.
The simplest task would contain a single trial configured via a single row in a spreadsheet. In the example below, a text zone called MathsQuestion will display the text '3 + 5 ='.
To make this work, the text zone in the task structure would have the Source set to Spreadsheet. When the source is set to spreadsheet the colour of name will be green. This is a mnemonic aid; the livery for Excel is also green.
See the single trial example.
By default Gorilla always includes two additional columns: randomise_blocks and randomise_trials. If unused leave these blank. More on these later.
Once you have the flow of your task working by linking across displays, it's time to populate a block of trials.
In the single block example, we want participants to see the task instructions, followed by a block of 5 test trials, and closed out with a debrief. To acheive this, we have created 3 displays in the example task;'instructions', 'test' and 'debrief'. In our spreadsheet, we start off with one row where the display is instructions, followed by 5 rows where the display is test (meaning that the display test will be shown to the participant 5 times), and finally a row where the display is debrief.
As the text in the test display is controlled by the spreadsheet, participants will see different text every time the test display is presented.
Perhaps you want to show the trials within your block in a random order? In Gorilla this is simple: you can do this by editing the 'randomise_trials' column - just put a 1 next to trials that you want shuffled. If the rows in that column are left empty, gorilla will always run the rows in the order they are placed. If the rows in the 'randomise_trials' column have a number then gorilla will run one of the rows that share the same randomise trial number.
In the Trial Randomisation example we see that the 5 test trials will now be shown in a random order
Perhaps you want multiple block of trials with a screen for participants to rest between each block.
To do this add a Block display with text populated from the spreadsheet (see column Text) and then put 1s next to the first block and 2s next to the second block. This will shuffle each block separately.
This is shown in the Multiple Blocks example - spreadsheet consecutive.
Or perhaps you want to shuffle the trials across blocks. That is possible too. Instead of putting 2s next to the second block, leave these as 1s.
This is shown in the Multiple Blocks example - spreadsheet fixed length.
Perhaps you have two (or more) blocks and between participants you want them shown in a different order.
To achieve this, use the randomise_block column. Next to the first block put 1s and next to the 2nd block put 2s. When a participant comes to the task Gorilla will randomly with replacement pick which block to show first.
The Block Randomisation example demonstrates this. Preview it a few times to see that sometimes you get the first set of test questions first and sometimes you get the 2nd set of test questions first.
Note that the Block displays are outside the randomise_block and so will always be shown in the order 1 then 2. If they were inside the randomise block, these would change order too. This can be useful if you have different instructions for each block.
Warning: For the block randomisation to work, blocks must be the same length. If blocks are of different length, then add padding (in the form of empty rows) to make each block the same length. See this example.
Counterbalanced Order: If you want to counterbalance the block presentation, create two spreadsheets (one for each order) and use a randomiser in the experiment tree.
More than 2 blocks: You can randomise more than two blocks in the spreadsheet. Gorilla will do this based on a Latin Square randomly with replacement.
Perhaps you want to show some practice trials first. The Practice Trials example demonstrates this. In the task structure there is a new display called practice which provides participants with feedback. In the spreadsheet, there are now new rows to trigger the display of the practice trials.
An alternative approach would have been to re-use the test display with the option to turn feedback on or off based on the content of a spreadsheet column.
Gorilla requires content for all the user-defined columns that it is expecting, but you can also include additional metadata.
Metadata columns have 3 primary use cases:
The Metadata example demonstrates case 1. Notice the different values under the column heading 'metadata'. Here the metadata shows the type of question being asked. Once data has been collected, trials and responses can be grouped using this metadata. This greatly simplifys the analysis process using Excel pivot tables or other data analysis software.
Read more about analysing your Gorilla Task Data in our How To: Metrics Guide.
There is no limit to how many columns of metadata can be added. The only restriction is that they must all have different column names.
Once a Metadata columns is added, so long as there is content in at least 1 row of the Metadata column, the Metadata column headings will appear in all spreadsheets within your task.
Task Spreadsheet Tab - Metadata Walkthrough Example: Metadata columns headings appear as white in your spreadsheet.
There are times when you may require completely empty Metadata columns. This is typically only applicable in case 3 - for instance when using script to create your own scoring system.
If you require empty Metadata columns, you MUST include these metadata columns on EVERY spreadsheet you upload to the task. Even if other spreadsheets make no use of these metadata columns.
If you do not include the empty columns on every spreadsheet upload, these empty metadata columns will disappear when you upload the new spreadsheet. This can create create problems for your scripts - as these required metadata columns will not exist neither while running the task nor in the task metrics downloaded from the task.
Remember check your Tasks Spreadsheet Tab to view all the known columns for your Task. If you can't see a required column reupload your full spreadsheet. Please read our Troubleshooting Guide for more detailed information on this.
Trials can also be interleaved. The Interleaving example demonstrates this.
The participant will alternate between digit trials (1) and text trials (2). Nevertheless, both the digit and text trials will be shown in a random order.
Advance Technique: In the example above we use the same display for both trials types. This is not mandatory; different displays could also be interleaved.
Within a block, you can present a mixture of trial types. The Block Interleaving example demonstrates this.
In this example, each block will first show three digit trials (picked randomly from all 6 digit trials) and then show 2 text trials (picked randomly from all 4 text trials).
Advance Technique: In the example above we use the same display for both trials types. This is not mandatory; different displays could also be included in the same block.
If you want to add a level of control to your randomisation, you can pseudo-randomise your trials. Pseudo-randomisation is a randomisation within certain parameters, e.g. you can control the number of trials that participant should go through before they reach the randomised trial. You can set up your pseudo-randomisation in the Spreadsheet - see the example below:
E.g. If you have two conditions (A and B) and want to have some variation in the way they are displayed, but would want to have no more than 2 consecutive trials of each condition, you would interleave the trials in the spreadsheet as shown below and then each dyad (made of one of each type) would get a different number in the randomise trials column: