Getting Started

The VisTrails system is distributed both as source code and pre-built binaries, and instructions for obtaining either can be found at our website: http://www.vistrails.org. Because the system is written in Python using a Qt interface, it can be run on most architectures that support these two components, even if a pre-built binary is not available for your system. Section Installation provides instructions to guide you through installation procedures, and Section Quick Start gives a quick orientation and serves as a springboard for exploring the different features of VisTrails.

Installation

There are two types of VisTrails installations. The first is a binary installation that lets you use VisTrails by running the precompiled executable. The second is a full source code installation that requires you to install and compile VisTrails and all of its dependencies. Of the two types of installations, the binary version is much easier, and we encourage first-time users to use this option whenever possible. Precompiled binaries are currently available for Microsoft Windows (XP and Vista) and Mac OS X (10.5.x or higher). To obtain either a binary or source copy of VisTrails, please see our website: http://www.vistrails.org.

Installing VisTrails on Windows XP/Vista

To install VisTrails on Windows, download the installation bundle for Windows from the VisTrails website: http://www.vistrails.org. Unzip the file using the decompression program of your choice, then double-click the executable to begin installation (Figure Installation wizard for Microsoft Windows XP/Vista). Follow the prompts in the installation wizard to complete the installation process.

Installation wizard for Microsoft Windows XP/Vista.

Installing VisTrails on Mac OS X

To install VisTrails on Mac OS X, download the installation bundle for Mac from the VisTrails website: http://www.vistrails.org. The precompiled binary currently only supports Mac OS X 10.5.x or higher. The disk image should be mounted automatically (Figure Installing VisTrails on Mac OS X). Once the disk image is mounted, drag the VisTrails folder to the Applications folder to install the software.

Installing VisTrails on Mac OS X.

Installing VisTrails on Ubuntu Linux

Although not a binary installation per se, installing VisTrails on Ubuntu Linux is nonetheless quite straightforward. VisTrails now interfaces with “apt” directly via a Python API. This allows dynamic installation of necessary packages. As a result, you do not need to manually install any of the dependent packages. Just download the VisTrails source code and execute it with:

python vistrails/run.py

and VisTrails should detect all necessary software and, if necessary, ask for your permission to install it.

Installing VisTrails from source

Installing VisTrails from source code is a non-trivial task. Rather than listing full compilation instructions in this manual, we instead provide a list of software packages upon which VisTrails is dependent, and refer you to the VisTrails website for additional details.

• Python 2.6 or higher
• Qt 4.4 or higher
• PyQt4
• SciPy
• VTK (needed to run the examples in this book)

There may also be additional dependencies, depending on which optional features of VisTrails you plan to use.

Please refer to http://www.vistrails.org/index.php/Mac_Intel_Instructions for more details.

Quick Start

On Windows and Mac OS X, you can launch VisTrails by double-clicking on the VisTrails application icon. In general, however, it is possible to start VisTrails on any system by navigating to the directory where the file run.py is located (usually the root directory of your installation) and executing the command:

python run.py

Depending on a number of factors, it can take a few seconds for the system to start up. As VisTrails loads, you may see some messages that detail the packages being loaded and initialized. This is normal operation, but if the system fails to load, these messages will provide information that may help you understand why.

Installing additional packages

VisTrails releases come with a number of packages already installed. In addition to these, you can write your own packages or install packages from third-party developers. To do that, just drop the Python module (single file) or package (i.e. directory) in $HOME/.vistrails/userpackages/ (VisTrails should automatically create this folder on the first run).

You can then enable and disable standard or user packages from the preferences dialog, under the module packages tab.

The Vistrails Builder Window

After everything has loaded, you will see the VisTrails Builder window as shown in Figure VisTrails Builder Window. If you have enabled the VisTrails Spreadsheet (Packages VisTrails Spreadsheet Show Spreadsheet), you will also see a second window like that in Figure VisTrails Spreadsheet Window. Note that if the spreadsheet window is not visible, it will open upon execution of a workflow that uses it.

VisTrails Builder Window

VisTrails Spreadsheet Window

The VisTrails Toolbar

VisTrails Toolbar

The VisTrails toolbar both allows you to execute the current workflow or function, and switch between various modes. A brief description of each member of the toolbar follows:

Pipeline This view shows the current workflow. See Chapter Creating and Modifying Workflows for information about creating a workflow.

History This view shows different versions of the workflow(s) as it has progressed over time. See Chapter Interacting with the Version Tree.

Search Use this mode to search for modules or subpipeline within the current version, the current vistrail, or all vistrails. See Chapter Querying the Version Tree.

Explore This option allows you to select one or more parameter(s) for which a set of values is created. The workflow is then executed once for each value in the set and displayed in the spreadsheet for comparison purposes. See Chapter Parameter Exploration.

Provenance The Provenance mode shows the user a given vistrail’s execution history. When a particular execution is selected, its pipeline view with modules colored according to its associated execution result is shown. See Chapter Provenance Browser.

Mashup The Mashup mode allows you to create a small application that allows you to explore different values for a selected set of parameters. See Chapter Mashups for more information.

Execute Execute will either execute the current pipeline when the Pipeline, History, or Provenance views are selected, or perform the search or exploration when in Search or Exploration mode. This button is disabled for Mashup mode, or when there is not a current workflow to execute.

The New, Open, and Save buttons will create, open, and save a vistrail, as expected.

Palettes and Associated Views

Palettes

As you can see, the builder window has a center widget with a palette on each side. There are a number of views (listed in the 4th group of the views menu) that when made visible, will be opened in these palettes. In this section, we will discuss how the views are arranged.

Notice that when VisTrails first launches the builder window, both palettes contain two views. The left palette is split so both views are visible, whereas the right palette uses tabs to display one view at a time. By default, additional views will be shown in the right, and lower left panels when they are made visible. To make a view visible, either switch to a mode that requires it, or select it from the views menu. For example, the Mashup mode will add the Mashup Pipeline and Mashups Inspector views to the panels. When the mode is changed from Mashup, these two views will be removed (hidden).

Buttons

Notice that there is a button with a pin icon in the upper right corner of each view (see Figure Buttons - Close, Detach, and Pin). If you don’t want a view to disappear when you change modes, make sure it is pinned. When the pin points up, it is unpinned and the view is likely to disappear when you change modes.

The other two buttons, the one with the ‘X’ and the one with the rectangular outlines (see Figure Buttons - Close, Detach, and Pin), will either close the view, or undock the view, depending on which one you push. Alternatively, you may undock a view by clicking on the view’s title bar and pulling it out of the palette. The view can then either remain in its own window, or can be docked by placing it in either palette.

Buttons - Close, Detach, and Pin

View Locations

The following table gives the view that is visible in each palette for each of the main views/modes:

		Lower Left Palette	Right Palette
Pipeline		Modules	Module Information
History		Modules	Properties
Explore		Explore Properties	Set Methods
Provenance		Modules	Log Details
Mashup		Mashups Inspector	Mashup Pipeline

Notice that the Workspace, Diff Properties, and Vistrail Variables views are not in the table. That is because, the Workspace view is always visible, the Diff Properties view opens in the right palette when a visual diff is performed in the History view, and the Vistrail Variables view is opened from the Views menu. Note: with the Vistrail Variables view especially, if you don’t want it to disappear, you should make sure it is pinned.

The Center Widget

The center widget is somewhat larger than the side panels as it is intended to be the main workspace. It displays the following views: Pipeline, History, Search- query and results, Visual Diff results, Explore, Provenance, and Mashup. By default, one view is shown. To open an additional view, type CTRL-t to create a new tab. The new tab starts out in the Pipeline view, but you are free to change it to any of the other views. Note that the tabs from only one vistrail are displayed at a time. When you switch to a different vistrail, the other vistrail’s set of open tabs are displayed.

If you would like to see views from more than one vistrail at a time, you may do this by right-clicking on the vistrail (listed in Current Vistrails of the Workspace view), and selecting the option to open in a new window. The side palettes will stay with the original window, but can be moved to the current window by selecting Dock Palettes from the Views menu.

If you would like to see multiple views from the same vistrail, double-click the title of the view to detach it. It is not possible to reattach the view, so once you are finished with the detached view, you may close it. If you would like the view to be reattached, you should close it and open it again in a new tab.

Manipulating VisTrails Files

To open a VisTrails file, or vistrail, you can either click the Open button in the toolbar or select Open from the File menu. This brings up a standard file dialog where you can select a vistrail to open. Vistrails are identified by the .vt file extension. Alternatively, if the vistrail is listed under My Vistrails in the Workspace Panel, double clicking its name will open it. When a vistrail is opened, it is listed in the Workspace (upper left panel) under Current Vistrails. Since only one open vistrail is displayed at a time, the Workspace allows you to select which one to display. Vistrails can also be stored in a database, enabling a central repository for workflows. See Chapter Connecting to a Database for more details about this feature.

To close a vistrail, you can either choose the Close option from the File menu or type Ctrl-w. If the vistrail has not been saved, you will be asked if you wish to save your work. To save a vistrail, there is both a button and a menu item in the File menu. If you would like to save the vistrail with a different name or in a different location, you can use the Save As option.

VisTrails Basics

In general, a workflow is a way to structure a complex computational process that may involve a variety of different resources and services. Instead of trying to keep track of multiple programs, scripts, and their dependencies, workflows abstract the details of computations and dependencies into a graph consisting of computational modules and connections between these modules.

The Pipeline button on the VisTrails toolbar accesses VisTrails’ interface for building workflows. Similar to many existing workflow systems, it allows you to interactively create workflows using an extensible library of modules and a connection protocol that helps you determine how to connect modules. To add a module to a workflow, simply drag the module’s name from the list of available modules to the workflow canvas. Each module has a set of input and output ports, and outputs from one module can be connected to inputs of another module, provided that the types match. For more information on building workflows in VisTrails, see Chapter Creating and Modifying Workflows.

In addition to VisTrail’s Pipeline interface for manipulating individual workflows, the History interface (accessed through the History button on the toolbar) contains a number of features that function on a collection of workflows. A vistrail is a collection of related workflows. As you explore different computational approaches or visualization techniques, a workflow may evolve in a lot of directions. VisTrails captures all of these changes automatically and transparently. Thus, you can revisit a previous version of a workflow and modify it without worrying about saving intermediate versions. This history is displayed by the VisTrails Version Tree, and different ways of interacting with this tree are discussed in Chapter Interacting with the Version Tree.

With a collection of workflows, one of the necessary tasks is to search for specific workflows. VisTrail’s search functionality is accessed by clicking the Query button on the toolbar. The criteria for these searches may vary from finding workflows modified within a specific time frame to finding workflows that contain a specific module. Because of the version history that VisTrails captures, these tasks are natural to implement and query. VisTrails has two methods for querying workflows, a simple text-based query language and a query-by-example canvas that lets you build exactly the workflow structure you are looking for. Both of these techniques are described in Chapter Querying the Version Tree.

The Exploration button allows you to explore workflows by running the same workflow with different parameters. Parameter Exploration provides an intuitive interface for computing workflows with parameters that vary in multiple dimensions. When coupled with the VisTrails Spreadsheet, parameter exploration allows you to quickly compare results and discover optimal parameter settings. See Chapter Parameter Exploration for specific information on using Parameter Exploration.

VisTrails Interaction

Workflow Execution

The Execute button on the toolbar serves as the “play” button for each of the modes described above. In both the Builder and Version Tree modes, it executes the current workflow. In Query mode, it executes the query, and in Parameter Exploration mode, it executes the workflow for each of the possible parameter settings.

When a workflow is executed, the module color is determined as follows:

• lilac: module was not executed
• yellow: module is currently being executed
• green: module was successfully executed
• orange: module was cached
• red: module execution failed

A popup is shown when executing workflows from the pipeline or history view. The popup shows overall progress, the type of module being executed, and a cancel button. Pressing cancel will show a dialog where you can choose to abort or continue the execution. Note that the cancel button may appear frozen while a module is being executed. This is due to limitations in python.

Note

VisTrails caches by default, so after a workflow is executed, if none of its parameters change, it won’t be executed again.

If a workflow reads a file using the basic module File, VisTrails does check whether the file was modified since the last run. It does so by keeping a signature that is based on the modification time of the file. And if the file was modified, the File module and all downstream modules (the ones which depend on File) will be executed.

If you do not want VisTrails to cache executions, you can turn off caching: go to Menu Edit Preferences and in the General Configuration tab, change Cache execution results to Never.

If you would like your input and output data to be versioned, you can use the Persistence package.

Additional Interactions

From the Edit menu, Undo and Redo function in the standard way, but note that these actions are implicitly switching between different versions of a workflow. Thus, you will notice that as you undo or redo a change to a workflow, the selected version in the version tree changes.

For all modes except Parameter Exploration, the center pane of VisTrails is a canvas where you can manipulate the current workflow, version tree, or query. The buttons on the right side of the toolbar allow you to change the default behavior of the primary mouse button (the left button for most multiple button mice) within this canvas. You can choose the behavior to select items in the scene, pan around the scene, or zoom in and out of the scene by selecting the given button. In addition, if you are using a 3-button mouse, the right button will zoom, and the middle button will pan. To use the zoom functionality, click and drag up to zoom out and drag down to zoom in.

Note

Pressing Ctrl-R will recenter the window.