Loop Examples (RapidMiner Studio Core)

Synopsis

This operator iterates over its subprocess for all the examples of the given ExampleSet. The subprocess can access the index of the example of the current iteration by a macro.

Description

The subprocess of the Loop Examples operator executes n number of times where n is the total number of examples in the given ExampleSet. In all iterations, the index of the example of the current iteration can be accessed using the macro specified in the iteration macro parameter. You need to have a basic understanding of macros in order to apply this operator. Please study the documentation of the Extract Macro operator for a basic understanding of macros. The Extract Macro operator is also used in the attached Example Process. For more information regarding subprocesses please study the Subprocess operator.

One important thing to note about this operator is the behavior of the example set output port of its subprocess. The subprocess is given the ExampleSet provided at the outer example set input port in the first iteration. If the example set output port of the subprocess is connected the ExampleSet delivered here in the last iteration will be used as input for the following iteration. If it is not connected the original ExampleSet will be delivered in all iterations.

It is important to note that the subprocess of the Loop Examples operator is executed for all examples of the given ExampleSet. If you want to iterate for possible values of a particular attribute please use the Loop Values operator. The subprocess of the Loop Values operator is executed for all possible values of the selected attribute. Suppose the selected attribute has three possible values and the ExampleSet has 100 examples. The Loop Values operator will iterate only three times (not 100 times); once for each possible value of the selected attribute. The Loop Examples operator, on the other hand, will iterate 100 times on this ExampleSet.

Input

example set (Data Table)
This input port expects an ExampleSet. It is the output of the Extract Macro operator in the attached Example Process. The output of other operators can also be used as input.

Output

example set (Data Table)
The ExampleSet that is connected at the example set output port of the inner subprocess is delivered through this port. If no ExampleSet is connected then the original ExampleSet is delivered.
output (IOObject)
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_macroThis parameter specifies the name of the macro which holds the index of the example of the current iteration in each iteration. Range: string

Tutorial Processes

Subtracting the average of an attribute from all examples

The 'Golf' data set is loaded using the Retrieve operator. A breakpoint is inserted here so that you can have a look at the ExampleSet. The Extract Macro operator is applied on it. The Extract Macro operator generates a macro named 'avg_temp' which stores the average value of the Temperature attribute of the 'Golf' data set. The Loop Examples operator is applied next. The Loop Examples operator iterates over all the examples of the 'Golf' data set and sets the value of the Temperature attribute in each example to the difference of the average value (stored in 'avg_temp' macro) from the existing value of the Temperature attribute. The iteration macro parameter of the Loop Examples operator is set to 'example'. Thus in each iteration of the subprocess the index of the current example can be accessed by the 'example' macro.

Have a look at the subprocess of the Loop Examples operator. The Extract Macro operator is applied first to store the value of the Temperature attribute of the example of the current iteration in a macro named 'temp'. Then the Generate Macro operator is applied to generate a new macro from the 'temp' macro. The name of the new macro is 'new_temp' and it stores the difference of the current temperature value (stored in 'temp' macro) and the average temperature value (stored in 'avg_temp' macro). 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 value of the Temperature attribute of the example of that iteration with the value of 'new_temp' macro. The resultant ExampleSet can be seen in the Results Workspace. You can see that all values of the Temperature attribute have been replaced with new values.