User Manual

Updated for release version: 1.1.0-beta

This is the start page for the ModelGUI user manual. The proposed beta release (1.1.0-beta) for the mgui project is currently set for summer, 2013. This manual will (in theory) be updated to provide support for the latest release. However, as a general policy all user manual entries will specify, at the top of the page, the release version for which they were written or updated. While there is no current official release, an unofficial alpha release 1.0.18-alpha is already available (see Getting Started).

The "user manual" series is intended for end users of the ModelGUI application. Developers should refer to the "developer manual".

NOTE: ModelGUI is currently in an alpha phase, and a number of organization changes are planned for its beta release. This manual is likewise in an alpha phase, and subject to change. While the general overview should remain the same, a few conceptual alterations should be expected - something to keep in mind!

Introduction

The ModelGUI project (which will be referred to synonymously as "mgui") was conceived and is being developed as a broad-spectrum modelling environment. That is to say, the application is not designed to perform any specialized function in particular, but rather to provide a core implementation for model-user interfaces which can serve as a foundation for more specialized extensions. At the present, very fetal stage of development, this concept is illustrated by (1) the mgui-core series, which implements all the generic classes for geometry, graphics, data source connectivity, I/O, and modelling; and (2) the mgui-neuro series, which implements classes specialized to deal with neuroscientific datasets and tasks. A magnetic resonance image, for instance, is represented in ModelGUI by the generic shape interface Volume3DInt, which is designed to represent any regular 3D array of values in R3 space (of which medical images are only a subset).

With this in mind, the next question is how you would like to use ModelGUI . This manual deals with its core functionality; other manuals will be designed specifically for its offshoot projects such as mgui-neuro.

Tutorials

While it is quite useful to acquaint yourself with the concepts underlying ModelGUI , as are described below, learning how to use the application for accomplishing specific tasks is often best achieved through tutorials, which walk you through the process step-by-step. Accordingly, we have designed a number of tutorials covering various common tasks in ModelGUI , from loading and visualizing simple shapes, to setting up data sources, to designing and analyzing complex dynamic models. A complete list of available tutorials can be found here (this is also available from the "quick links" menu).

Organization

Below is a (tentative) object model diagram for ModelGUI . The concepts are explained in more detail in the next section. In general, a ModelGUI Session is a particular instance of program execution; every time you run the application, you are instantiating a Session. Each Session contains an Environment (or possibly a number of specialized Environments), which specifies all of the underlying details of the Session (which panels and I/O types are loaded, how the GUI looks and feels, which maps and queries are available, etc.). Also within a Session is a Workspace object, which holds your data in the form of Shape Models, Dynamic Models, Data Sources, Graphs, and Variables. The Workspace also acts as a container for (1) Projects, which specify organizational metadata for the storage and retrieval of models; (2) the Display Panel, which determines the graphical display and layout of data as 2D or 3D graphics, data tables, plots, graphs, etc.; and (3) Pipelines, which specify serial or parallel chains of computational tasks, and are useful for processing large data sets.

Core Concepts

Here it's useful to resort to analogy: let's consider the painter. A typical session for a painter takes place in a studio of some sort, containing all the necessary tools: brushes, palettes, canvases, easels, paint, and often some kind of muse or model. The studio and the tools it contains fall into the general category of the artist's environment. We can imagine the artist as he enters the studio environment and commences a session, perhaps forming an idea of the type of medium he wants to use, and gets to work mixing up colours, selecting a canvas, or arranging the model in a certain pose. He is, in essence, initializing his workspace; after he's happy he sits down before the canvas and starts to create. The model herself is the essence of his workspace, without which the entire endeavour is meaningless. But the other ingredients are equally as critical: the tools, the media, the room, and all the other aspects of the environment and the workspace upon which the process of artistic painting depends.

This is the sort of conceptualization that underlies the ModelGUI project. It is easy to extend this analogy to the scientist and his data, seeing as the whole process is a matter of observing, cognitively processing, and communicating the outcome. The basic concepts, with some expansions such as projects and pipelines, are described more directly below:

Session

A Session represents an execution instance. When a painter sits down to paint, or a scientist sits down to manipulate his/her data set, they are both initiating a session. In ModelGUI, a session is defined by an environment (defining the available tools) and a workspace (defining specific model instances, data sources, graphics windows, and organizational aids such as projects and pipelines). Sessions can be saved in XML format and thus specific sessions can be recycled across different execution instances. The XML encoding of sessions and their components is described here.

Environment

An Environment is the current setting for all models and their objects. Environments define the functionality of a given mgui session; they specify:

• data source drivers
• colour maps
• name maps
• I/O types
• interface panels
• graphic panel types
• object queries
• GUI look-and-feel
• pipeline process libraries
• tool kits

An environment is initiated by an init file, which is a command-based text file. This arrangement allows for very customized versions of the application to be run, which specify only a specific subset of the available objects and drivers.

Workspace

A Workspace acts as the top-level container for all data, projects, and GUI objects. You can think of the workspace as the (meta)physical space in which a session is enacted, much like an artist's studio. The limits of a workspace are determined by its corresponding environment, much as an artist's workspace is limited by the materials, tools, and skills at his disposal. The workspace specifies both the GUI layout which allows the user to interact with the underlying data models, and these data models themselves. Like a session, a workspace and its GUI layouts, projects, and data models are XML-encodable, and thus can persist across sessions, or in many cases (depending on the file organization) be shared as archives, allowing other users to reproduce your sessions for themselves with little effort.

Project

A ModelGUI Project is a collection of metadata which describes how persistent data are organized. Any data set which is organized in a recurrent, hierarchical manner can potentially be represented as a ModelGUI project. A simple example of this is a file directory structure, specifying how subjects are to be organized into separate directories, and each subject directory is to contain a number of sub-directories which contain specific types of data. As a concrete neuroscience example: if you have 10 subjects, each having fMRI, sMRI, DTI, and cognitive scores data, the project will specify that each subject directory must contain four sub-directories for each data modality. Given this structure, it is then easy to query the project for the fMRI data from subject 5. Projects in modelGUI are intended to be highly extensible so as to allow a organizational structure for any sort of data set, of arbitrary complexity.

Interface Object

ModelGUI makes liberal use of the term "interface"; but in general it refers to any object which acts as a bridge between the underlying data model (e.g., geometry information) and the user. In this sense, tree nodes, graphics panels, shape objects, and data tables are all Interface Objects (and, accordingly, they all inherit the InterfaceObject Java interface). To avoid confusion, a distinction must be drawn between a Java interface - which is a class that has no body but instead specifies a set of methods which an implementing class must declare - and an interface in the modelGUI sense. If your only intention is to use the end product, then this shouldn't be an issue.

Here is a list of some important Interface Objects:

Object	Description
Graphic	Represents a particular type of graphic window, which can be used to display underlying model data in some way. Examples are the 2D and 3D windows which display shapes.
Panel	Provides an interface for some specific set of user-interactive functions; a panel can be used, for instance, to display a tree of workspace objects, allow file input and output, or enable object querying.
Tool	A tool provides a different user interaction, typically providing mouse- or dialog-based interactions with graphic windows. Some examples are the 2D and 3D dynamic zoom tools, or the query tool.
Shape Model	A Shape Model is a top-level container for geometric shapes. It allows shapes to be organized into subsets, specifies default spatial and temporal units, and acts as the data source for 2D and 3D rendering.
Shape	Provides an interface (attributes, rendering capability, tree nodes) into some underlying set of geometry (instances of Shape).
Data Source	Specifies a JDBC connection to some relational database, and provides a set of tables and queries which can be used to interrogate or modify it.
Variable	Provides an interface for a vector or matrix of either numeric or character data, which can be used as input or output for various processes.
Graph	Allows graph representations of data to be stored using the Jung graph library. Provides the capability to visualize and analyze these graphs.
Dynamic Model	Represents a dynamic (forward) model, specified by model objects with ordinary differential equations (ODEs) which can be evaluated using numerical methods.
Project	Specifies an organizational structure for a set of project "instances" (e.g., subjects in an experimental design), which have identical subdirectory structures. A project can be used to organize parallel processing of a large data set.
Pipeline	Provides a interface for executing a fixed set of serial processes. Can be used in conjunction with a project, for instance, to process individual project instances in an identical (and trivially parallelizable) fashion.

Attribute

Many interface objects include a list of Attributes which specify some aspect of that object, such as its graphical appearance. Attributes for all objects are editable via the object tree as well as the Attribute Dialog Editor.

Display Panel

A Display Panel acts as a container for interface graphic windows, controlling their appearance and layout. Display panels can be selected with the tabs in the main part of the ModelGUI window. Display panels are organized with two container types in mgui. Firstly, multiple display panels can be organized into Tabs, which can be selectively viewed in the same way as most web browsers now support. Secondly, individual tabs can be organized into multiple windows using Split Panels. A split panel can be created via the context (right-click) menu, which allows the user to split the current window horizontally or vertically; it is also possible to flip the current split orientation.

Interface Panel

An Interface Panel provides a set of GUI components which allow the user to directly interact with interface objects. The Tree Panel, discussed below, is one example of this. Other panels currently provided with mgui-core include:

Panel	Description
File Panel	Provides an interface for loading and writing persistent data using all loaded I/O types.
Section Set Panel	Allows user to create or modify section sets, assign them to particular 2D graphics windows, and select or scroll through individual sections.
Windows Panel	Specifies the current set of windows, how they are laid out, and what their data sources are. Also provides interfaces for storing and loading 3D views, and creating, scripting, and writing 3D videos.
Shapes Panel	Provides interfaces for displaying, modifying, and interrogating geometrical shapes.
Data Sources Panel	Allows the user to browse and modify the structure of a particular data source, or to create new data sources.
Mesh Functions Panel	Provides a means of modifying, querying, and performing calculations on triangular meshes. Also provides an interface for displaying vertex-wise data with colour maps, and for establishing links with existing Data Sources.
Volume 3D Panel	Provides an interface for loading and visualizing 3D volumes. Also allows for the specification of volume masks.

Data Source

A Data Source is a connection to an external data source such as MySQL or MS Access databases. ModelGUI uses the Java Database Connectivity framework (JDBC) to make such connections. In order for the application to be able to connect to a data source, it must have access to an appropriate JDBC driver (which does the actual work of reading and writing to the data source and provides a JDBC-compliant interface for processing requests), as well as a data source configuration file (which specifies the URL to the data source as well as which driver to use, and login and password information). ModelGUI can load JDBC drivers and specific data sources upon initialization, and these will show up as Data Source objects in the Object Tree.

Interface Objects

This section introduces you to the number of Interface Objects implemented in mgui-core.

Graphics Interface

A Graphics Interface is an internal window in mgui, which displays underlying data models in some way. mgui-core currently offers the following graphic types:

Type	Description
Graphic2D	Renders 2D shapes associated with particular sections of particular section sets. Also displays 3D shapes from the same shape model, as they intersect or are projected onto the section plane, within specific projection limits. A Graphic2D window can be easily zoomed or translated to display any part of the available shape model. The display of 2D shapes is determined by their attributes, or by the attributes of overriding shape sets. The 2D window also provides picking capabilities that allow for easy interaction with displayed shapes through mouse tools.
Graphic3D	Renders 3D shapes from a particular shape model, or 3D versions of 2D objects associated with a particular section set. The view of a 3D window can be dynamically rotated, zoomed, or translated to visualize specific parts of the shape model; the center of rotation can also be modified. The display of 3D shapes is determined by their attributes, or by the attributes of overriding shape sets. The 3D window also provides picking capabilities that allow for easy interaction with displayed shapes through mouse tools.
Data Table	Displays a data set in tabular form; the source of a data table can be either a table or query from a Data Source object, or a matrix or vector from a Variable object. A data table can be easily browsed with scroll bars, and sorted by column.
Graph Display	Displays a graph using the Jung visualization library. Graph edges and vertices can be modified or labelled according to the graph's attributes. The graph display also provides user interaction through mouse tools.
Console Display	Allows you to view the console output produced by the application, or by pipeline processes. While console output is not currently systematic, this is still a useful feature to monitor progress of pipeline processes, or view exceptions when they occur.
Plot2D	Allows you to create and modify 2D data plots (bar graphs, scatterplots, histograms, etc.).

Shape Interface

A Shape Interface, as its name subtly suggests, provides an interface for 2D and 3D geometric shapes. This includes providing a set of attributes which determine how (and if) the shape is to be rendered, as well as the code for rendering them and responding to add, remove, or modification events. Shape interfaces can also store node-wise data (i.e., arrays of values which are associated with shape vertices), and methods to render this data. Shape interfaces provide a number of additional functions, such as the construction and handling of tree nodes, XML encoding, bounds calculations, etc. mgui-core currently offers interfaces for the following shape types:

• Polygons and polylines
• Triangular mesh surfaces
• Volume grids
• Vector sets
• Boxes
• Point sets

In addition, the following are special shape interfaces providing set functionality:

• Shape sets
• Section sets
• Selection sets

Data Source

A Data Source object stores a Data Connection, which specifies how to connect to a JDBC data source (i.e., which JDBC driver to use, which data source to access, and authentication parameters). Using this connection, the data source object can send requests via SQL statements to the driver, which then returns or modifies data accordingly. A data source is organized into a set of data tables, which is in turn a set of data fields which specify the type of data stored. Data sources are powerful tools for accessing arbitrarily large data sets, and their functionality is a core part of the mgui environment.

Variable

A Variable refers to a named vector or matrix of values which can be loaded into memory and used as input or output for various functions.

Graph

A Graph is an abstract mathematical representation of entities (nodes) and their relationships (edges). Graph theory is a powerful framework for analyzing systems, and mgui allows its models to be represented, analyzed, and visualized using the Jung Java API. Below are some examples of graphs:

A: An undirected graph; B: A directed graph; C: A directed, weighted graph (where edge weights are represented by line width); and D: A directed path, from vertex i to vertex j.

Tools

A Tool is an object which provides direct interaction between the user and some interface object. For example, a 3D Dynamic Orbit/Zoom/Pan tool allows the user to rotate, zoom, and pan within a 3D graphic window, in order to visually inspect the shape model it contains. Other tools might provide the ability to query, select, or edit a shape.

Interface Panels

This section introduces the common interface panels currently available with mgui-core. Each panel has its own page which describes its functionality it further detail.

Tree Panel

The Tree Panel is a tree-based GUI panel which displays all the current interface objects in a particular session. The object tree has the session's workspace as its root node; all interface objects are children of it. The object tree is a useful way to examine and interact with the state of a particular session, including its windows, shape models, data sources, colour maps, name maps, graphs, and variables. The tree's context (right-click) menus provide a means of creating, moving, or deleting interface objects; those which specify attributes can also have these attributes changed via the object tree.

File Panel

The File Panel provides a generic interface for loading and writing interface objects or environment objects. These include shape loaders and writers, as well as name maps, colour maps, or workspaces, shape models, etc.

Windows Panel

The Windows Panel provides an interface through which the user can create or destroy windows (instances of InterfaceGraphic), and set their sources. This panel also provides categories for setting and saving particular window Views, as well as for creating, running, and saving a Video sequence.

Tools Panel

The Tools Panel provides an interface through which the user can select and use 2D and 3D tools by pressing the appropriate. The tools are categorized by function.

Maps Panel

The Maps Panel implements an interface for a number of "maps"; i.e., mappings of some type of value to some other type of value. The three types of map currently available in modelGUI are:

• Continuous Colour Maps - which map decimal values (doubles) from 0.0 to 1.0, to colours, using a set of "anchor points" between which the colours are interpolated
• Discrete Colour Maps - which map integer values to colours
• Name Maps - which map integer values to character strings (text)

Data Source Panel

The Data Source Panel provides an interface into loaded data sources, or allows the user to define new sources. The interface also allows the user to make changes to the data source structure (if authorized and supported by the JDBC driver); i.e., add/remove/rename tables and fields. An interface is also provided for creating and editing SQL queries.

Shapes Panel

The Shapes Panel allows the user to perform a number of functions on shapes or selection sets. This includes, for instance, creating a convex hull, mapping data from a volume, displaying vertex-wise data, and linking to a data source.

Mesh Functions Panel

The Mesh Functions Panel provides functions which are specific for 3D meshes. This includes mesh cutting, surface calculations such as the discrete Laplacian, resampling, smoothing, etc.

Volume Panel

The Volume 3D Panel is an interface for 3D volume grids, which allows a rich interaction with colour mapping, masking, overlays, and time-series data.

Section Set Panel

The Section Set Panel allows users to create and modify section sets, assign them to Graphic 2D windows, and scroll through sections in these windows.

Pipelines

A pipeline is a specification for a set of commands to be run in series, with each subsequent process usually taking as input the output of the previous process. Data can be thought of as being piped between processes. ModelGUI provides a simple pipeline interface which allows such series to be defined and executed, with appropriate processes and parameters, which can all be saved and loaded in XML formats. The pipeline implementation in ModelGUI is illustrated below:

Directory structure

The ModelGUI source directory is comprised of executable scripts, a JAR file containing the core ModelGUI Java bytecode, and several subdirectories containing Java dependencies, binary dependencies, initiation files, and other resources. This organization is explained below:

Files

1. Executable scripts: these contain operating-system-dependent executable files which start the execution of the application. These files are:

• mgui-i586 - Script to be run from the Linux terminal (32-bit machines).
• mgui-i586.bat - Script to be run from the Windows command line (or by double-clicking in Windows Explorer) (32-bit machines).
• mgui-amd64 - Script to be run from the Linux terminal (64-bit machines).
• mgui-amd64.bat - Script to be run from the Windows command line (or by double-clicking in Windows Explorer) (64-bit machines).
• mgui-mac - Script to be run from the Mac terminal

2. README - Text file containing instructions on how to run or customize the application
3. mgui_logo_30.png - 30x30 image used as an icon for the application
4. mgui.ico - Windows icon file
5. mgui-x.x.x.jar - JAR file containing the Java bytecode which comprises the application
6. generate_db_key - Script allowing the user to generate a 40-character key for password encryption

Subdirectories

1. bin - Native OS-specific binary libraries, including Java3D and HDF5
2. cmaps - Colour maps to be loaded into the Environment
3. data - Data files for general use (e.g., common section sets)
4. data_sources - Specifications for data source drivers and data sources to be loaded on startup
5. init - Initiation files, specifying how the environment is to be set up on startup (the preferred init file can be specified as a command line argument)
6. lib - Java dependencies for the application, as JAR files
7. logs - Directory where log files (all application output, depending on the logging type specified in the init file) are written
8. mgui - Contains Java class files for executing the application
9. node_shapes - Specifies the vertex shapes available to the 2D renderer
10. pipeline_process_libraries - Set of pipeline process libraries which will be loaded on startup
11. scripts - Contains scripts which allow ModelGUI functions to be run as command-line functions

Logging

ModelGUI makes extensive use of logging (also called tracing), to aid with the inevitable issues which may arise during execution, to allow a user to recall previous mgui sessions, and to aid developers in debugging and testing their changes. By default, logs are saved in the "logs" subdirectory of the mgui folder. A unique log is created for each new date, and multiple sessions from the same date will be written to the same log file.

Logging types

Logging activity can be controlled by the user, by specifying in the init files used to run a session. This is done with the following commands:

setLogFile

Write logging events to the log file only, and not the console

setLogConsole

Write logging events to the console only, and not the log file

setLogFileAndConsole

Write logging events to both the log file and the console

setLogNone

No logging is performed

Both "file" commands take an additional argument (separated by a space) which specifies the prefix for the logging file. The file will then have the form "{prefix}_{yyyymmdd}.log".

Additionally, the command setLoggingType controls how verbose the logging is. The options are:

errors

Logs only events flagged as "errors"

warnings

Logs events flagged as either "errors" or "warnings"

concise

Logs events flagged as either "concise" or "errors"

verbose

Logs all events except those flagged as "debug"

debug

Logs everything