MAP Features Demonstration

This document details the features of MAP - a cross-platform framework for managing workflows. MAP is a plugin-based application that can be used to create workflows from a collection of workflow steps.

This demonstration is based on version 0.16.0 of the MAP Client, available from project downloads. Directions for installing MAP and getting the MAP plugins are available in the MAP Client Installation and Setup Guide.

In this demonstration we will cover the features of the MAP Client. We will start with a quick tour and then create a new workflow that will help us segment a region of interest from a stack of images.

Quick Tour

When you first load MAP, it will look something like this:

../_images/map_client_gui.png

In the main window we can see three distinct areas that make up the workflow management side of the software. These three areas are the menu bar (at the top), the step box (on the left) that contains the steps that you can use to create your workflow and the workflow canvas (on the right) an area for constructing a workflow.

When you first run the MAP Client, you will notice that there aren’t any plugins in the step box area. This is because we haven’t yet loaded any external plugins for the MAP Client to use.

Step Box

The Step box provides a selection of steps that are available for the user to construct a workflow from. The first time we run the MAP Client, the Step Box area of the application will be empty. To add plugins to the application, we must download the desired plugins to our system and use the Plugin Manager tool to import them. For more details on importing new plugins, please follow the setup instructions here.

Workflow Canvas

The workflow canvas is where we construct and edit our workflow. We can add new steps to the workflow by simply dragging the desired plugins from the step box and dropping them on the workflow canvas. Finally, we add connections between each step to complete the workflow.

When a step is added to the workflow the icon which is visible in the Step box is augmented with visualisations of the Steps ports and the steps configured status. A description of each step’s port will show when the mouse is hovered over them. The image below shows the Image Source step with the annotation for the port displayed.

../_images/step_with_port_info_displayed_1.png

Tools

MAP currently has a number of tools that may be used to aide the management of the workflow. This includes a Plugin Manager, Package Manager, Plugin Wizard, Physiome Model Repository (PMR) tool, Rename Plugin tool, and an Update Plugin tool.

The Plugin Manager, Physiome Model Repository (PMR) tool, Update Workflow tool and Update Plugin tool are described in detail below. The Plugin Wizard is explained in its own section later in this manual.

Plugin Manager Tool

The plugin tool is a simple tool that enables the user to add or remove additional plugin directories. When first opened, the MAP Client will not have any plugins installed and the plugin directories list (2) will be empty. New plugin directories can be added with the Add Directory button (1). Directories are removed by selecting the desired directory in the plugin directories list (2) and clicking the Remove Directory button (3). After making any changes to the plugin directories list (2), you can apply these changes by choosing either Apply (4) or OK (5). If you make any changes to the directory list (2) but click Close before choosing Apply or OK, the changes will not be saved. Outdated plugins can also be updated using the Advanced dialog (6).

Note

The Apply button (4) does not apply directory removals (3). You will need to restart the MAP Client to ensure that the plugins are completely removed from the MAP Step Box. This behaviour is a side-effect of the Python programming language.

../_images/plugin_manager_2.png

Advanced Dialog

As a result of forward compatibility issues between Python 2 and Python 3 a number of updates may be required for older plugins to work properly in MAP Client. The Advanced dialog provides a means of analysing the plugins in the directories listed in the Plugin Manager dialog (1) and applying a range of fixers for syntax, indentation and missing plugin information (2). Once updates have been successfully applied to plugins the Step Box will update automatically and any plugins requiring additional dependencies will be displayed. It is recommended that you analyse and update all plugins before continuing with workflow creation. We have updated all known plugins, those that we have access to on GitHub. For example, we have updated all the plugins available from the mapclient-plugins GitHub organisation to ensure that these compatibility issues are resolved.

Settings related to the Plugin Updater are located under the Options tab (3). You can toggle which updates you would like to apply to the plugins in your plugin directory (4), examine ignored plugin error notifications (5), add and remove plugin resource filenames from the updater (6) and locate the 2to3.py script in your system (7).

Dependency settings and information can be accessed under the Dependencies tab in the Advanced dialog (8). Here you can examine the list of installed packages in your system (9), update or uninstall these packages (10), view a list of recommended packages for plugin development (11), setup and modify the MAP Client virtual environment (12), view a list of packages that failed to install on your system (13) and modify setttings associated with package documentation and syntax analysis of dependencies (14).

Plugin Updates:

../_images/advanced_dialog.png

Options tab:

../_images/options_advanced_dialog.png

Dependencies tab:

manual/images/dependencies_tab.png

Update Workflow Tool

MAP Client workflows that have been saved in an earlier version of MAP Client to that which the user is currently running, may need to be updated. The Update Workflow tool is intended to simplify the updating process. To use the update workflow tool, the user need only identify the local directory, use (1) for choosing a workflow directory, of the workflow configuration and click Update (2).

Rename Plugin Tool

The Rename Plugin tool can be used to rename MAP Client plugin step-names or package-names without the user having to edit the plugin’s source code. The user can identify the desired plugin by supplying its root (top-most) directory in the location text box (1), or by using the tool’s directory chooser (2). In the to step name box (3) set the new name of the step and in the to step package name box (4) set the new package name of the step. To rename the plugin press the rename button (5).

Physiome Model Repository (PMR) Tool

The PMR tool uses webservices and OAuth to communicate between itself (the consumer) and the PMR website (the server). Using this tool we can search for and find suitable resources on PMR.

The PMR website uses OAuth to authenticate a consumer and determine consumer access privileges. Here we will discuss the parts of OAuth that are relevant to getting you (the user) able to access resources on PMR. Please read the section Simplified OAuth Primer for a quick overview of OAuth authentication.

If you want the PMR tool to have access to privileged information (your non-public workspaces stored on PMR) you will need to register the PMR tool with the PMR website. We do this by clicking on the register link as shown in the figure below. This does two things: it shows the Application Authorisation dialog; opens a webbrowser at the PMR website. [If you are not logged on at the PMR website you will need to do so now to continue, instructions on obtaining a PMR account are available here XXXXX]. On the PMR website you are asked to either accept or deny access to the PMR tool. If you allow access then the website will display a temporary access token that you will need to copy and paste into the Application Authorisation dialog so that the PMR tool can get the permanent access token.

../_images/pmr_tool_1.png

Simplified OAuth Primer

In OAuth we have three players the server, the consumer and the user. The server is providing a service that the consumer wishes to use. It is up to the user to allow the consumer access to the servers resources and set the level of access to the resource. For the the consumer to access privileged information of the user stored on the server the user must register the consumer with the server, this is done by the user giving the consumer a temporary access token. This temporary access token is then used by the consumer to finalise the transaction and acquire a permanent access token. The user can deny the consumer access at anytime by logging into the server and revoking the permanent access token.

Annotation Tool

Note

Please note that the annotation tool is currently under development, this tool in it’s current form as documented here does not integrate well with the latest version of PMR. This version of the annotation tool has been marked as deprecated and is currently disabled.

The Annotation tool is a very simple tool to help a user annotate the Workflow itself and the Step data directories that are linked to PMR. At this stage there is a limited vocabulary that the Annotation tool knows about, but this is intended to be extended in coming releases. The vocabulary that the annotation is aware of is available in the three combo-boxes near the top of the dialog.

../_images/top_annotation_1.png

The main part of the Annotation tool shows the current annotation from the current target.

../_images/main_annotation_1.png

In the above image we can see the list of annotations that have been added to the current target. This is a simplified view of the annotation with the prefix of the terms removed for clarity.

Additional Features

Log Information Window

The Log Information window displays the application logs for the current session. This includes information about plugin loading, plugin updates, http requests and general successful or failed processes executed by the program. Each log is defined by a level (DEBUG, INFO, WARNING, ERROR or CRITICAL) and contains a description and a recorded time. Logs are displayed in chronological order and can be sorted according to Level, Time or Description (3). If you wish to access more detailed information about an individual log simply double-click on a log entry or click the Details button (2). This displays the file from which the log was made in addition to the information described previously. It is also possible to load the log information from a previous MAP Client session using the Load button (1). The Log Information window provides useful debugging information and should be accessed on a regular basis.

../_images/log_information.png

Plugin Dependencies and Package Installation

Plugin developers may use additional packages in their plugins which are not available within the native python environment. These packages may however be installed using pip (Pip Installs Packages). If your system does not have a package required to run a plugin (and hence any workflow that uses the plugin) it can be installed with pip in the MAP Client virtual python environment. This virtual environment can be set up manually (from the Advanced dialog (2)) or automatically when a package is first required (3). By default the virtual environment will be set up in the same system location as the MAP Client log files, however this may be changed using the Modify button under the Dependencies tab in the Advanced dialog (1).

../_images/dependencies_tab_ve.png
manual/images/modify-ve.png
manual/images/setup-ve.png
manual/images/automatic-ve-setup.png