02-14-2022, 10:57 AM
Summary
Using lists in Experiment Builder can be helpful in several scenarios, including randomization and recording multiple responses in a single variable. Experiment Builder is able to use and manipulate lists (and lists of lists), containing all of the data types detailed below. This short summary will outline 1. The list variable’s format, 2. Selecting an item from a list, 3. Taking an item from a list, and 4. Appending (adding) items to a list, and 5. Some Experiment Builder specific considerations.
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 of a list are arranged in a sequential order separated by a comma. To access each item, you need to identify the position of the item in the list, this is called indexing the item. In Experiment Builder (and other Python programs), the index values start at 0. The first item of the list is index 0, the second is 1 etc. In the above example, the apples.jpg image would be accessed with =Image_list[0]. The “=” is essential, as accessing an indexed item from a list is an evaluation (not dissimilar to Excel). Here the square brackets demonstrate the list index number of that list variable.
When you have a list of lists (like that shown above), you index both the list and then the sublist. For example, to get the second item from the third list you would use =List_of_Lists[2][1], where ‘[2]’ indexes the third list, and the ‘[1]’ indexes the second item of that third list (this would return the number 22).
Removing an Item From a List
In some situations, you may need to remove an item from the list once used, for example, if you wanted to randomize the list and select items without replacement (no repetitions). This is easily achieved with the Python command .pop() in an update attribute action.
In this example, the Current_Item variable is updated with the first item from the Image_List list variable using ‘.pop(0)’ - note the 0 denotes the list index value - taking from the list the first value, i.e. ‘apples.jpg’ based on the previous image_list example above. It is important to note that if you attempt to .pop from an empty list you will face an error that will end your task ‘Error pop from an empty list’, so it is important to ensure your list is long enough to allow for each iteration of this command.
Adding an Item to a List
There are two approaches to adding items to a list. One simply adds the new item at the end of the existing list values with *.append(value), and the other allows you to select where in the list (the index) to add the value with *.insert(index, value). In both cases, it is the list itself that is being updated and not another variable, so the Attribute value in the Update Attribute action requires a placeholder empty list variable (in the below example dummy, which simply contains a [] value - an empty list) to act on the list in the Value cell.
In the first example, the Number_List is updated with the number value ‘10’, which is added to the end of the existing numbers in the list. In the second example, the Fruit_List variable (a list of string/text values), the list is updated with the item ‘Apples’ at index 0 - the first item of the list. This will shift the index of all other list items by 1 (the previous index 0 item is now at index position 1 etc.).
Using Lists in Data Sources
While Experiment Builder can include a list variable in the Data Source, to access an item (index) from a data source list or to act on its contents (e.g. to randomize it), the list must first be transferred to a variable. All operations are performed on the variable rather than the list in the actual data source. To do this, use an Update Attribute to update the value of a list variable to the contents of the list in the data source. You can then act on the list variable, e.g. to pop, insert, randomize etc. The data source in Experiment Builder is an immutable object, so this small step maintains the data source and allows full list functionality.
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.
Using lists in Experiment Builder can be helpful in several scenarios, including randomization and recording multiple responses in a single variable. Experiment Builder is able to use and manipulate lists (and lists of lists), containing all of the data types detailed below. This short summary will outline 1. The list variable’s format, 2. Selecting an item from a list, 3. Taking an item from a list, and 4. Appending (adding) items to a list, and 5. Some Experiment Builder specific considerations.
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 of a list are arranged in a sequential order separated by a comma. To access each item, you need to identify the position of the item in the list, this is called indexing the item. In Experiment Builder (and other Python programs), the index values start at 0. The first item of the list is index 0, the second is 1 etc. In the above example, the apples.jpg image would be accessed with =Image_list[0]. The “=” is essential, as accessing an indexed item from a list is an evaluation (not dissimilar to Excel). Here the square brackets demonstrate the list index number of that list variable.
When you have a list of lists (like that shown above), you index both the list and then the sublist. For example, to get the second item from the third list you would use =List_of_Lists[2][1], where ‘[2]’ indexes the third list, and the ‘[1]’ indexes the second item of that third list (this would return the number 22).
Removing an Item From a List
In some situations, you may need to remove an item from the list once used, for example, if you wanted to randomize the list and select items without replacement (no repetitions). This is easily achieved with the Python command .pop() in an update attribute action.
In this example, the Current_Item variable is updated with the first item from the Image_List list variable using ‘.pop(0)’ - note the 0 denotes the list index value - taking from the list the first value, i.e. ‘apples.jpg’ based on the previous image_list example above. It is important to note that if you attempt to .pop from an empty list you will face an error that will end your task ‘Error pop from an empty list’, so it is important to ensure your list is long enough to allow for each iteration of this command.
Adding an Item to a List
There are two approaches to adding items to a list. One simply adds the new item at the end of the existing list values with *.append(value), and the other allows you to select where in the list (the index) to add the value with *.insert(index, value). In both cases, it is the list itself that is being updated and not another variable, so the Attribute value in the Update Attribute action requires a placeholder empty list variable (in the below example dummy, which simply contains a [] value - an empty list) to act on the list in the Value cell.
In the first example, the Number_List is updated with the number value ‘10’, which is added to the end of the existing numbers in the list. In the second example, the Fruit_List variable (a list of string/text values), the list is updated with the item ‘Apples’ at index 0 - the first item of the list. This will shift the index of all other list items by 1 (the previous index 0 item is now at index position 1 etc.).
Using Lists in Data Sources
While Experiment Builder can include a list variable in the Data Source, to access an item (index) from a data source list or to act on its contents (e.g. to randomize it), the list must first be transferred to a variable. All operations are performed on the variable rather than the list in the actual data source. To do this, use an Update Attribute to update the value of a list variable to the contents of the list in the data source. You can then act on the list variable, e.g. to pop, insert, randomize etc. The data source in Experiment Builder is an immutable object, so this small step maintains the data source and allows full list functionality.
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.