02-14-2022, 10:57 AM
Using lists in Experiment Builder is a powerful way to handle randomization, record multiple responses into a single variable, and manage complex trial sequences. You can create and manipulate lists (and even lists of lists) containing various data types
Data types
Experiment Builder recognizes various data types, which are important when they are inputs for a function - they are:
List Variable Format
To turn a variable into a list variable (the data type is called an ‘EBList’), alter the variable’s value so that its contents are contained in square brackets []. A variable containing [] is an empty list.
As mentioned in the Data Types section, a list can contain any of the data types (including lists). A simple example list below contains image files names (of data type string, within ""), e.g.the three images of fruit below:
Selecting an Item From a List
The items in a list are arranged in a specific order. To access an individual item, you must refer to its position in that order, a process known as indexing.
Experiment Builder, like Python, uses zero-based indexing. This means the first item is at index 0, the second is at index 1, the third is at index 2, and so on.To get an item, you use the list's variable name followed by the index number in square brackets []. For example, to access the first image from a list named Image_list, you would write:
Note: The leading equals sign (=) is essential in Experiment Builder. It tells the software to evaluate the expression and retrieve the value, similar to how formulas work in a spreadsheet.
Selecting an Item From a List within a list
For nested lists (a list that contains other lists), you simply extend the indexing by adding a second set of brackets. The first index selects the inner list, and the second index selects the item from within that inner list. The format is =List_of_Lists[outer_index][inner_index].
For example, to get the second item (22) from the third inner list, you would use:
Here, [2] selects the third list ([21, 22, 23]), and [1] selects the second item from within that list (22).
Removing an Item From a List
To remove an item from a list after it has been used, you can use Python's .pop() method. This is essential for tasks like randomization without replacement, as it ensures an item cannot be selected more than once.
In an UPDATE_ATTRIBUTE action, you can retrieve an item and simultaneously remove it from the list. For example, to take the first item from a list called Image_List and assign it to a Current_Item variable, you would use:
The 0 inside the parentheses is the index of the item you want to take. After this action runs, Current_Item will hold the value 'apples.jpg', and the Image_List will no longer contain that item.
Warning: Attempting to .pop() an item from an empty list will cause a fatal error (Error: pop from an empty list) and immediately stop your experiment. Always ensure your code logic prevents this from happening, for example, by checking that the list is not empty before calling .pop().
Adding an Item to a List
You can add new items to a list in two different ways: by appending them to the end or by inserting them at a specific position. Both methods modify the list in-place (meaning they alter the original list directly). Because of this, setting them up in an UPDATE_ATTRIBUTE action in Experiment Builder requires a special approach:
Using Lists in Data Sources
While Experiment Builder can include a list variable in the Data Source, you cannot directly modify a list while it resides in the Data Source during run-time. This is because the Data Source in Experiment Builder is immutable, meaning it's treated as a read-only object during the experiment to ensure the original trial information is always preserved.
To work with a list from your Data Source (e.g., to randomize it or .pop() an item), you must first copy its contents into a separate list variable. All operations are then performed on this new variable. For example:
Final Comments
This is far from an exhaustive list of what Experiment Builder lists can do. Experiment Builder is able to execute many Python commands, so the possibilities are plentiful.
Data types
Experiment Builder recognizes various data types, which are important when they are inputs for a function - they are:
- String - text, any value provided within “ “ marks and any keyboard key-value, e.g. Hello, “1”, and Esc
- Number - either integer (1,2,3) or float values (0.5, 5.23, 10.2)
- Boolean - True or False
- Color - RGB values (Red, Green, Blue) on a scale from 0-255, eg. (1,1,2) or (255,255,255)
- Point - Location values given as x,y coordinates, e.g. (100,200) or (540,960)
- List - A list, defined within [], can be formed of any of the above, eg. [(255,255,255), (0,0,0)] is a list of two colors (black and white); [(960, 540), (660, 540), (1260, 540)] is a list of three point values. *the first item in the list is indexed to 0, the second to 1 etc
List Variable Format
To turn a variable into a list variable (the data type is called an ‘EBList’), alter the variable’s value so that its contents are contained in square brackets []. A variable containing [] is an empty list.
As mentioned in the Data Types section, a list can contain any of the data types (including lists). A simple example list below contains image files names (of data type string, within ""), e.g.the three images of fruit below:
Selecting an Item From a List
The items in a list are arranged in a specific order. To access an individual item, you must refer to its position in that order, a process known as indexing.
Experiment Builder, like Python, uses zero-based indexing. This means the first item is at index 0, the second is at index 1, the third is at index 2, and so on.To get an item, you use the list's variable name followed by the index number in square brackets []. For example, to access the first image from a list named Image_list, you would write:
Code:
=Image_list[0]Selecting an Item From a List within a list
For nested lists (a list that contains other lists), you simply extend the indexing by adding a second set of brackets. The first index selects the inner list, and the second index selects the item from within that inner list. The format is =List_of_Lists[outer_index][inner_index].
For example, to get the second item (22) from the third inner list, you would use:
Code:
=List_of_Lists[2][1]Removing an Item From a List
To remove an item from a list after it has been used, you can use Python's .pop() method. This is essential for tasks like randomization without replacement, as it ensures an item cannot be selected more than once.
In an UPDATE_ATTRIBUTE action, you can retrieve an item and simultaneously remove it from the list. For example, to take the first item from a list called Image_List and assign it to a Current_Item variable, you would use:
Code:
=Image_List.pop(0)The 0 inside the parentheses is the index of the item you want to take. After this action runs, Current_Item will hold the value 'apples.jpg', and the Image_List will no longer contain that item.
Warning: Attempting to .pop() an item from an empty list will cause a fatal error (Error: pop from an empty list) and immediately stop your experiment. Always ensure your code logic prevents this from happening, for example, by checking that the list is not empty before calling .pop().
Adding an Item to a List
You can add new items to a list in two different ways: by appending them to the end or by inserting them at a specific position. Both methods modify the list in-place (meaning they alter the original list directly). Because of this, setting them up in an UPDATE_ATTRIBUTE action in Experiment Builder requires a special approach:
- In the Attribute field, you must enter a placeholder variable (e.g., a variable named dummy that contains an empty list []).
- In the Value field, you write the expression that modifies your actual list.
- Add to the End (.append())
The .append(value) method is the simplest way to add an item. It takes a single value and adds it to the very end of the list. For example, to add the number 10 to a list called Number_List:
So, If Number_List was [5, 8, 3], it will become [5, 8, 3, 10].Code:Number_List.append(10)
- Insert at a Specific Position (.insert())
The .insert(index, value) method gives you more control, allowing you to add an item at a specific index. All existing items at and after that index will be shifted one position to the right. For example, to add the string 'Apples' to the beginning of a list called Fruit_List:
So, If Fruit_List was ['Oranges', 'Bananas'], it will become ['Apples', 'Oranges', 'Bananas']. The original item at index 0 ('Oranges') is now at index 1.Code:Fruit_List.insert(0, 'Apples')
Using Lists in Data Sources
While Experiment Builder can include a list variable in the Data Source, you cannot directly modify a list while it resides in the Data Source during run-time. This is because the Data Source in Experiment Builder is immutable, meaning it's treated as a read-only object during the experiment to ensure the original trial information is always preserved.
To work with a list from your Data Source (e.g., to randomize it or .pop() an item), you must first copy its contents into a separate list variable. All operations are then performed on this new variable. For example:
- Create a new list variable in your sequence (e.g., current_list).
- At the start of your trial, use an UPDATE_ATTRIBUTE action to set current_list to the value of the list from your Data Source.
- Once the list's contents are in the current_list variable, you can freely manipulate it using methods like .pop(), .insert(), or .random() without affecting the original data for subsequent trials.
Final Comments
This is far from an exhaustive list of what Experiment Builder lists can do. Experiment Builder is able to execute many Python commands, so the possibilities are plentiful.