Groups and Subworkflows

Grouping Modules

As the number of modules in a pipeline increases, the pipeline can grow quite large and cumbersome. This also makes the pipeline more difficult to understand and maintain. With any large system, it can be helpful to cluster related pieces together and represent them as a single unit. This idea, called encapsulation, is commonly used in computer programming as a way of controlling complexity. VisTrails likewise supports the grouping of multiple modules together so that they can be treated as a single module. This “group” module can be thought of as a monolithic entity that performs all the same functions as its individual parts, but shields its inner details from everyone else. As such, a group module inherits all the input and output ports of the modules inside it, but only displays those ports that have connections to another module outside of the group. To borrow another term from programming languages, these visible ports might be considered the public interface of the group module.

Multiple modules are grouped together by first selecting them, and then choosing the Group option from the Edit menu. Alternatively, you can use the keyboard shortcut ‘Ctrl-G’.

An example may clarify how this works.

Try it now!

Open “vtk_book_3rd_p189.vt”. Select the vtkOutlineFilter, vtkPolyDataMapper, vtkProperty, and vtkActor modules on the left side of the pipeline, as shown in Figure Box selection of four modules. Type ‘Ctrl-G’ to group these modules. Notice how the pipeline changes, as shown in Figure The modules represented as a single group module. Since the label “Group” isn’t very descriptive, you can change this by selecting the Group module, and entering a name in the Name box of the Module Information panel. Type a more descriptive name, such as “BoundingBox,” into the text field and click OK. The new label is reflected in the pipeline (Figure Renaming the group).

Box selection of four modules.

The modules represented as a single group module.

Renaming the group.

Just as any number of modules may be clustered into a group, any number of groups may be combined with other groups or modules to form still larger groups. This is done in the same way as described above.

Further, the contents of the groups or combinations of groups are revealed through the Show Pipeline option. First select the group module in the pipeline and then select Show Pipeline from the Workflow menu. The group’s contents will be shown in a new tab. If there is a group within a group, selecting the interior group module and then selecting Show Pipeline will show the interior group’s pipeline in an additional tab.

In addition to viewing the group’s contents, any group may be also un-grouped; that is, restored to its individual modules. This is done by selecting the group module in the pipeline, and then choosing the Edit Ungroup menu option or by pressing ‘Ctrl-Shift-G’. A group’s pipeline may not be used to ungroup interior groups, however. The tabs opened by the Show Pipeline command are read only.

Subworkflows and Group Modules

A subworkflow is similar to a group, but has some differences. Here, we will explain the differences to make it easier to understand which one to use when:

• A subworklow is a VisTrail, and a history of changes to a subworkflow is kept, whereas a group is part of a vistrail. So, if you copy and paste a group, the pasted group won’t necessarily be linked to the group’s history.
• When a subworkflow is created, it is listed in the My Subworkflows portion of the Modules panel. It is saved and will be accessible from any vistrail. A group, on the other hand can be named and copied and pasted within a file, or even across files. However, it will not be placed in the modules panel.
• Subworkflows can be edited and saved without needing to ungroup and regroup the modules. To edit anything within a group, it first needs to be ungrouped, and then regrouped.

Subworkflows

To create a subworkflow, select the modules to include and select Create Subworkflow from the Workflow menu. See Figure Creating a subworkflow. You will be prompted to name the subworkflow. The subworkflow will appear in the modules list under My Subworkflows. Groups can be converted to subworkflows by selecting the Convert to Subworkflow option.

To edit a subworkflow, select a module of the corresponding subworkflow and select Edit Subworkflow from the Workflow menu. This will open the subworkflow’s file. If you make changes to the subworkflow and save them, the modules that correspond to the old subworkflow will be marked with a ‘!’, meaning that it is not the latest version. To upgrade to the latest version, either select the triangle in the module’s upper right corner and choose Upgrade Module, or delete the old module and replace it with a new one. See Figure Upgrading a subworkflow module that had been edited.

Creating a subworkflow.

Upgrading a subworkflow module that has been edited.

Importing and Exporting Subworkflows

Since subworkflows are saved locally, the Import Subworkflow and Export Subworkflow options can be used for sharing. For example, to add a subworkflow from an open VisTrail to your local list of My Subworkflows modules, you would select the subworkflow and select Import Subworkflow from the Workflows menu. Alternatively, you can save any number of subworkflows to a package by dragging the subworkflow modules to the canvas, selecting them, selecting Export Subworkflow, and following the prompts to name/create the appropriate folders/files. The subworkflows will be exported to a folder which can be added to the userpackages directory. The package should contain a __init__.py, and an init.py file. The importing of the individual subworkflows will be handled in the init.py file. See the Writing Vistrails Packages chapter of the Developer’s Guide for more information on packages.