Introduction
The following figure shows the @b TOPPAS main window and a pipeline which is just being created.
The user has added some tools by drag&dropping them from the TOPP tool list on the left
onto the central window. Additionally, the user has added nodes
for input and output files.
Next, the user has drawn some connections between the tools
which determine the data flow of the pipeline. Connections can be drawn by first @em deselecting the
desired source node (by clicking anywhere but not on another node)
and then dragging the mouse from the source to the target node (if
a @em selected node is dragged, it is moved on the canvas instead).
When a connection is created and the source (the target) has more than one output (input) parameter,
an input/output parameter
mapping dialog shows up and let's the user select the output parameter of the source node and the
input parameter of the target node for this data flow.
If the file types of the selected input and output parameters are not compatible with each other,
@b TOPPAS will refuse to add the connection. It will also refuse to add a connection if it
would create a cycle in the workflow, or if it just would not make sense, e.g., if
its target is an input file node. The connection between the input file node and the BaselineFilter
tool is painted yellow which means it is not ready yet, because no input files have been
specified yet.
The input/output mapping of connections can be changed at any time during the editing process by double-clicking
an connections or by selecting @a Edit @a I/O @a mapping from the context menu which appears when a connection is right-clicked.
All visible items (i.e. connections and the different kinds of nodes) have such a context menu. For a detailed list
of the different menus and their entries, see @ref TOPPAS_interface_menus .
The following figure shows a possible next step: the user has double-clicked one of the tool nodes in order
to configure its parameters. By default, the standard parameters are used for each tool. Again, this can also
be done by selecting @a Edit @a parameters from the context menu of the tool.
Once the pipeline has been set up, the input files have to be specified before the pipeline can be executed.
This is done by double-clicking an input node and selecting the desired files in the dialog that appears.
Input nodes have a special mode named "recycling mode", i.e., if the input node has fewer files than the following node has rounds (as it might have two incoming connections)
then the files are recycled until all rounds are satisfied. This might be useful if one input node specifies a single database file (for a Search-Adapter like Mascot) and another
input node has the actual MS2 experiments (which is usually more than one). Then the database input node would be set to "recycle" the database file, i.e. use it for every
run of the MascotAdapter node. The input list can be recycled an arbitrary number of times, but the recycling has to be @em complete, i.e. the number of rounds of the
downstream node have to be a multiple of the number of input files. Recycling mode can be actived by right-clicking the input node and selecting the according entry from the context menu.
Finally, if you have
input and output nodes at every end of your pipeline and all connections are green,
you can select @a Pipeline @a > @a Run in the menu bar or just press @a F5.
You will be asked for an output file directory where
a sub-directory, @a TOPPAS_out, will be created. This directory will contain your output files.
You can also specify the number of jobs TOPPAS is allowed to run in parallel. If a number greater than 1
is selected, TOPPAS will parallelize the pipeline execution in the following scenarios:
- A tool has to process more than one file. In this case, multiple files can be processed in parallel.
- The pipeline contains multiple branches that are independent of each other. In this case, multiple tools can run in parallel.
Be careful with this setting, however, as some of the TOPP tools require large amounts of RAM (depending
on the size of your dataset). Running too many parallel jobs on a machine with not enough memory will cause problems.
Also, do not confuse this setting with the @em threads parameter of the individual TOPP tools: every TOPP tool has this
parameter specifying the maximum number of threads the tool is allowed to use (although only a subset of the TOPP tools make use
of this parameter, since there are tasks that cannot be computed in parallel). Be especially careful with combinations
of both parameters! If you have a pipeline containing the @em FeatureFinderCentroided, for example, and set its @em threads parameter
to 8, and you additionally set the number of parallel jobs in @b TOPPAS to 8, then you end up using 64 threads in parallel, which
might not be what you intended to do.
In addition to @a TOPPAS_out, a @a TOPPAS_tmp directory will be created in the OpenMS temp path (call the @em OpenMSInfo tool to see where exactly).
It will contain all
temporary files that are passed from tool to tool within the pipeline.
Both folders contain further sub-directories which are named after the number in the top-left corner of the node they
belong to (plus the name of the tool for temporary files). During pipeline execution, the status lights in the top-right corner of the
tools indicate if the tool has finished successfully (green), is currently running (yellow), has not done anything so far (gray), or has crashed (red).
The numbers in the bottom-right corner of every tool show how many files have already been processed and
the overall number of files to be processed by this tool.
When the execution has finished, you can check the generated output files of every node quickly by selecting
@a Open @a files @a in @a TOPPView from its context menu (right click on the node).
Mouse and keyboard
Using the mouse, you can
- drag&drop tools from the TOPP tool list onto the workflow window (you can also double-click them instead)
- select items (by clicking)
- select multiple items (by holding down @a CTRL while clicking)
- select multiple items (by holding down @a CTRL and dragging the mouse in order to "catch" items with a selection rectangle)
- move all selected items (by dragging one of them)
- draw a new connection from one node to another (by dragging; source must be deselected first)
- specify input files (by double-clicking an input node)
- configure parameters of tools (by double-clicking a tool node)
- specify the input/output mapping of connections (by double-clicking a connection)
- translate the view (by dragging anywhere but on an item)
- zoom in and out (using the mousewheel)
- make the context menu of an item appear (by right-clicking it)
@n
Using the keyboard, you can
- delete all selected items (@a DEL or @a BACKSPACE)
- zoom in and out (@a + / @a -)
- run the pipeline (@a F5)
- open this tutorial (@a F1)
Menus
@b Menu @b bar:
@n @n
In the @a File menu, you can
- create a new, empty workflow (@a New)
- open an existing one (@a Open)
- open an example file (@a Open @a example @a file)
- include an existing workflow to the current workflow (@a Include)
- visit the online workflow repository (@a Online @a repository)
- save a workflow (@a Save / @a Save @a as)
- export the workflow as image (@a Export @a as @a image)
- refresh the parameter definitions of all tools contained in the workflow (@a Refresh @a parameters)
- close the current window (@a Close)
- load and save TOPPAS resource files (.trf) (@a Load / @a Save @a TOPPAS @a resource @a file)
@n
In the @a Pipeline menu, you can
- run a pipeline (@a Run)
- abort a currently running pipeline (@a Abort)
@n
In the @a Windows menu, you can
- make the TOPP tool list window on the left, the description window on the right, and the log message at the bottom (in)visible.
@n
In the @a Help menu, you can
- go to the OpenMS website (@a OpenMS @a website)
- open this tutorial (@a TOPPAS @a tutorial)
@n @n
@b Context @b menus:
@n @n
In the context menu of an @a input @a node, you can
- specify the input files
- open the specified files in TOPPView
- open the input files' folder in the window manager (explorer)
- toggle the "recycling" mode
- copy, cut, and remove the node
@n
In the context menu of a @a tool, you can
- configure the parameters of the tool
- resume the pipeline at this node
- open its temporary output files in TOPPView
- open the temporary output folder in the file manager (explorer)
- toggle the "recycling" mode
- copy, cut, and remove the node
@n
In the context menu of a @a Merger or @a Collector, you can
- toggle the "recycling" mode
- copy, cut, and remove the node
@n
In the context menu of an @a output @a node, you can
- open the output files in TOPPView
- open the output files' folder in the window manager (explorer)
- copy, cut, and remove the node