Loop Examples
(AI Studio Core)
Synopsis
This Operator executes a subprocess once for each of the Examples in an ExampleSet.Description
If there are N Examples in the ExampleSet, the loop is executed N times. The index of the current iteration is provided by the macro named in iteration macro. See the Extract Macro operator for more details about macros.
Whereas other loop operators, such as Loop or Loop Attributes, include an option called "reuse results" that determines whether the result of one iteration is reused in the next, Loop Examples uses a different mechanism.
- If the result of the Loop Examples inner subprocess is sent to the exa port, the result is reused in the next iteration.
- If the result of the Loop Examples inner subprocess is sent to the out port, the result is NOT reused. Each iteration of the loop will then create its own independent result.
For details, see the second Tutorial Process.
Differentiation
Loop
Much like a conventional programming loop, the Loop Operator iterates a user-specified number of times.
Loop Values
The Loop Values Operator iterates once for each of the possible values of a selected Attribute.
Input
example set (Data table)This input port expects an ExampleSet.
- input (IOObject)
The Loop Examples operator can have multiple additional inputs. When one input is connected, another input port becomes available which is ready to accept another input (if any). The order of inputs remains the same. The Object supplied at the first input port of the subprocess is available at the first input port of the nested chain (inside the subprocess). Make sure that you have connected the right number of ports at all levels of the chain.
Output
- example set (Data table)
If the exa port of the inner subprocess is not connected, then the original ExampleSet is delivered. Otherwise, if the inner subprocess is connected to the exa port, this port delivers the final result, after all the iterations have been completed.
- output (Data table)
The Loop Examples operator can have multiple output ports. When one output is connected, another output port becomes available which is ready to deliver another output (if any). The order of outputs remains the same. The Object delivered at the first output port of the subprocess is delivered at the first output of the outer process. Don't forget to connect all outputs in correct order. Make sure that you have connected the right number of ports at all levels of the chain.
Parameters
- iteration_macro The index of the current iteration is provided by the macro named in iteration macro. Range:
Tutorial Processes
Subtracting the average of an attribute from all Examples
In this tutorial, the value of Temperature in the 'Golf' data set is replaced by the difference between the Temperature and the average temperature for each Example in the ExampleSet.
First, the 'Golf' data set is loaded using the Retrieve operator, and a breakpoint is inserted so that you can look at the ExampleSet. Next, the Extract Macro operator generates a macro named 'avg_temp', which stores the average value of the Temperature in the 'Golf' data set. The Loop Examples operator then iterates over all the Examples in the 'Golf' data set and resets the value of the Temperature to the difference between the existing value and the average value (stored in 'avg_temp' macro). In each iteration of the subprocess, the index of the current Example is given by the macro named 'example'.
Have a look at the subprocess of the Loop Examples operator. The Extract Macro operator stores the value of the Temperature for the current Example in a macro named 'temp'. Then the Generate Macro operator is applied to generate a new macro. The name of the new macro is 'new_temp', and it stores the difference between 'temp' and 'avg_temp'. Finally the Set Data operator is applied. The Example index parameter is set to '%{example}' to access the Example of the current iteration. The value parameter is set to '%{new_temp}' to store the value of the 'new_temp' macro in the current Example.
This subprocess is executed once for each Example, and in every iteration it replaces the value of the Temperature with the value of the 'new_temp' macro. The resultant ExampleSet can be seen in the Results Workspace. You can see that all values of the Temperature have been replaced with new values, which are positive or negative depending on their deviation from the average.
Reusing or not reusing the the result of one iteration
This second Tutorial Process illustrates how the final result changes depending on whether the result of the inner subprocess is sent to the exa port or to the out port. If the result of the Loop Examples inner subprocess is sent to the exa port, the result is reused in the next iteration. If the result of the Loop Examples inner subprocess is sent to the out port, the result is NOT reused. Each iteration of the loop will then create its own independent result.
In the Tutorial Process, the values of the Play attribute are changed to "Out of town". There are two separate processes, differing only in the reuse of results. Make sure to double-click on both of the Loop Examples subprocesses, to see how the two subprocesses have different port connections -- both inside and outside. Then run the process. The top process results in a single ExampleSet, where every value of Play has been changed to "Out of town". The bottom process results in 14 ExampleSets, where in each of the ExampleSets, only one Example has been changed.
