Iterations in EasyMorph are used to arrange loops (cycles) — i.e. when part of a calculation is executed multiple times, each time with a new set of input parameters (data). Using iterations you can transform multiple files in a similar fashion, process daily data for a given range of dates, send emails to multiple recepients, and arrange other repetitive workflows. Understanding iterations may require a bit of effort. However, once learned, iterations become a very powerful technique that can be used in many real-life scenarios. From a programming perspective, iterations in EasyMorph allow aranging FOR...EACH, FOR..NEXT, and DO..WHILE/UNTIL types of loops.
This article requires a good understanding of parameters and modules/subprojects explained earlier in this tutorial.
In EasyMorph, iterating means calling (executing) another module (or project) multiple times. In this chapter we will be talking mainly about iterating modules. However, it all is equally applicable to iterating projects.
The "Iterate" action
FOR..EACH type of loops in EasyMorph are arranged using the "Iterate" action. The action is very similar to the "Call" action (described in the previous chapter) with two major differences:
- Parameters of the called module can be assigned using column values.
- The called module is called not once, but as many times as there are rows in the table with the "Iterate" action.
The diagram below shows how Module A iterates Module B using a list of file names. Module B has a parameter named Param1. This parameter is assigned by Module A with a new file name every time it runs Module B. Because the input dataset (Table 1) in Module A has 3 rows, the "Iterate" action calls (iterates) Module B exactly 3 times — once per each file name in column [File Name].
Frequently, iterations are performed against a list of files, or a list of dates. Such lists can be generated using the "Calendar" action (generates a sequence of dates) or "List of files" (generates a list of files in a folder). Alternatively, they can be imported from a database or a text file.
Hint: To quickly obtain a list of files in a folder simply drag the folder into EasyMorph.
The "Iterate" action runs another module (or project) once for each row of the action's input dataset. Parameters of the iterated module can be assigned using field values of the dataset. If a module parameter is not assigned, it keeps the last saved value (the default value).
The "Iterate" action can run in one of the two modes:
- Iterate — do not return anything from the iterated module, i.e. just run it one or several times.
- Iterate and append results — run the module one or several times, return a table (the result dataset) from each iteration, and append all result datasets into one, which becomes the output of the "Iterate" action. Appending the result datasets is similar to the "Append" action — columns with the same name are concatenated into one column, columns with unique names are extended with empty cells.
To create a FOR..NEXT type of loop, generate a sequence of numbers from 1 to N using the "Generate sequence" action, then iterate across the sequence using the "Iterate" action.
All calling actions ("Call", "Iterate", "Iterate table", and "Repeat") can run modules in the current project as well as external projects. When designing iteration of a module, it may be confusing to see that the module's parameters that are visible in EasyMorph don't change after a call from another module. That's because during calls/iterations, under the hood, EasyMorph creates an invisible clone of the iterated module and assigns parameters to that invisible clone and runs it. The module that you see remains intact, calls don’t modify it. This is done in order to avoid ambiguity and conflicts because the same module can be called from multiple places simultaneously.
In order to understand how a module would be calculated when called/iterated from another module, set the called module's parameters manually and run it (if Auto-run is off).
See iterations explained
We've prepared a pack of 5 iteration examples. Each example has an illustrated description and annotations in project tables and actions.
- Example 1 – load multiple files
- Example 2 – split one file into many files
- Example 3 – batch processing of several files
- Example 4 – iterate and append data into one table
- Example 5 – iterate another table