Getting Started with DAVE

DAVE is an integrated environment for the reduction, visualization and analysis of inelastic neutron scattering data. It is built using IDL (Interactive Data Language) from ITT Visual Information Solutions (formally Research Systems, Inc.) which is a cross-platform application development tool with built-in graphics. All efforts have been made to ensure that DAVE is supported on Linux, Windows and MacOS X. It is available at no cost to users in two forms. The first is as a binary executable with an embedded IDL runtime license which can be used by anyone running on any of the three supported operating systems. In addition, for those who have an IDL development license, the complete source code for DAVE is also available.



A Brief Introduction

This chapter is intended to present a gentle introduction to some of the key features in DAVE by running through an illustrative tutorial session. The tutorial will touch on some of the basic functionality that will be encountered during a typical use of the software. In most cases a user would normally need to load one or more datasets, whether raw or reduced, from a data file. Then they may wish to view the data, perform basic arithmetic operations on them or more advanced analysis. At some point, it may be necessary to: save a dataset after it has been modified in some way, generate an exported image in one of the many supported image formats, print a visualization, save the entire session into a project file and return to it at a later time. This tutorial will briefly describe how to quickly perform these tasks.

The Main Application Window

Follow the instructions outlined in Obtaining and Installing DAVE to install and launch DAVE for your specific platform. After launch, the following main application window will be displayed.

DAVE Main Application Window
DAVE: main application window

The main window is a standard widget application with menus. It has a simple layout that is designed to provide easy access to the datasets that are currently loaded into the program, a means of quickly visualizing the data and a list of existing visualizations that have been created. The main interface can therefore be viewed in terms of the following components:

DAVE uses project files to store data and visualizations that are created during a session. When a new session is started, a new "Untitled" project is used until it is renamed. The first task that a user will typically perform after starting DAVE would be to open an existing project or, if starting a new project, load data into the application. The next section demonstrate how to quickly load data.

First, the DAVE Working directory needs to be introduced. The working directory is used by DAVE to read or write processed or reduced data. By default, the working directory would be set to your home directory as defined by your operating system. For example, if your computer username is "myUserName" then on Linux your working directory would typically default to "/home/myUserName" and on Windows to "C:\Documents and Settings\myUserName". However, you can alter the default working directory by modifying your application preferences. Use the
File => Preferences...
menu option to initiate the action. The Preferences dialog is displayed which contains a tree widget to the left and a property sheet to the right.

Preferences dialog before Preferences dialog after
Preferences dialog: default values Preferences dialog: modified

In the tree widget, make sure the General DAVE Settings option is selected in the left pane tree widget. In the property sheet, various properties and their current settings are shown. To change the default value for the working directory, click on the Working directory field. A button with a right arrow bitmap should appear to the right of the field. Clicking on this button should bring up a floating Edit... button - click on it as well to launch a directory browser from which you can select a new working directory. In my case, I selected the directory as indicated in the modified Preferences dialog above. Click on the OK button in the directory browser and then in the Preferences dialog to accept the change. A full description of the other configurable preferences are described later.

Loading Data

Data to be loaded into DAVE fall into one of two general categories - raw or reduced data. Raw data is typically instrument specific and is best handled by the data reduction module for that instrument, if available. Reduced or processed data can be loaded as long as it is exist in one of the file formats that is supported. Supported file formats include ASCII (column, group, SPE) and DAVE (.dave).

For the purposes of this tutorial, we will make use of examples data files that are included as part of DAVE. These files are also available from the DAVE download page. Download he34_x05.dat and he34_bkgd.dat or copy them from the auxiliary directory located in your DAVE installation directory. These files should be placed in your DAVE working directory as defined in the preferences dialog described above.

To load a supported data from a supported file format, you have to use the appropriate menu entry underneath the Data Input/Output top-level menu. To load data from an ASCII (column, group or SPE) file, use the following procedure:

The data browser should now have three entries for he34_x05, he34_bkgd and dcs_example representing the files that were read as shown in the screenshot above.

Manipulating and Visualizing Data

Once data is loaded, it is possible to examining the contents of the datasets. In general, a dataset may consist of metadata as well as the plottable data. These are stored hierarchically using a tree structure with nodes. The nodes are either branches or leaves - branches act like folders and contain other nodes. In the data browser area, the dataset name is a top-level node which can be expanded to reveal the contents of the dataset. The dataset may or may not contain other nodes.

ASCII datasets usually contain a plottable dataset only so expanding he34_x05 or he34_bkgd should reveal the 3 columns of data each represented by a leaf node. The plottable data consists of:

Reduced data generated by the data reduction modules in DAVE and stored using the internal DAVE format (*.dave) contain additional information such as treatment history and instrument specific details. Expanding the dcs_example node should reveal a slightly more complicated structure consisting of other branches. The plottable dataset within dcs_example is stored in the folder Experimental Data and expanding this should reveal four entries:

Data browser
Dataset tree hierarchy. Properties of selected item shown in data property area in the right

Note that nodes containing plottable datasets (dependent + independent data) usually have an associated plot.bmp (if 1D - one independent variable) or surface.bmp (if 2D - two independent vriables) icon. Therefore, it can be easily determined from the screenshot that he34_bkgd contains a 1D dataset whereas the Experimental Data container within dcs_example contains a 2D dataset.

Selection of any node within the data browser tree will cause the property sheet to be updated with the properties of that item as shown in the screenshot above where the Energy Transfer item is selected. One property worth noting for the selected item is the data's Axis Type property which has the value "X". The Axis Type property specifies how any data should be treated in a visualization and has the following values and meanings:

Value of Axis Type propertyMeaning in a visualization
XFirst independent axis data (x-axis)
YSecond independent axis data (y-axis)
DataDependent axis data (z-axis)
ErrorError in dependent axis data

Thus, the Energy Transfer data is intended to be used as the first independent or x-axis in a plot of the dataset. Explore with other data items in the plottable data container to see what their Axis Types are.

Another very useful property is the data's Type which is very useful in matching the data with a visualization parameter as discussed below. The Energy Trasnfer data has Type "IDLVECTOR".

Creating a basic visualization from a plottable dataset is quite straightfoward in DAVE. The general procedure involves a few steps:


Set visualization type

The Visualization Editor, which occupies the lower left part of the main window, is a property sheet containing a visualization type selection field followed by additional fields that are collectively known as visualization parameters. The visialization selection is done using the droplist widget, the first item in the editor property sheet labeled Select a visualization. This property is used to specify the type of visualization to be created and is changed by selecting from the droplist as shown in the following screenshot:

Visualization type
Selecting visualization type

Make sure you select the Plot visualization.

When a visualization type is selected, the editor property sheet is updated to reflect the choice - visualization parameters appropriate for the chosen visualization are displayed. For example, if you select the Plot visualization type, a total of seven visualization parameters will be displayed - three of these are specified in normal fonts while the remaining four are grayed out. The normal font parameters indicate those parameters that are typically used in the creation of the selected visualization. In addition, some normal font parameters have an asterix (*) next to their names - these are required parameters. Thus, for the Plot visualization the Y parameter - the dependent variable - is required.

Note also that the Parameter Details section is updated with the list of parameters for the selected visualization and the types of data that are acceptable to each parameter.

Associating data with visualization parameters

To create a visualization, you have to associate data to be visualized with visualization parameters. At minimum, data MUST be associated with required parameters otherwise you will be unable to proceed with the creation of the visualization. For plottable datasets, it is quite straightfoward to assign data to visualization parameters.

Data-Vis1 Data-Vis1
Before (left) and after (right) assigning data to visualization parameters by clicking the down arrow button


Creating a new visualization

To create a new visualization, ensure the New visualization task option is selected prior to making the data-parameter association above, as shown in the next shot.

New vis
New visualization option

Once data is assigned to the visualization parameters, it is possible to create a new visualization by clicking on the New Visualization button. (Note that if one or more required parameters are not assigned, this button will be inactive.) DAVE responds by creating the specified visualization in a new window. In the example, the following Plot visualization is created in its own window.

Plot1
Newly created Plot visualization

The visualization window has a simple layout that consists of a menu and toolbar section, a graphics window and a status area at the bottom.

Modify visualization - change data

After a visualization has been created, it is possible to modify the data that is being visualized. We will not demonstrate this for this tutorial but here are the steps you need: The visualization window should be automatically updated to reflect the changes made.

Adding to existing visualization (overplotting)

This feature is useful for:
  1. creating multi-plots (sharing the same axes)
  2. multiple views, each with a separate axes/dataspace, within the same graphics window. You have complete control over the layout of the views which can be gridded or with a floating inset.
For this tutorial we will be showing how to create a multi-plot by adding a new visualization to an existing one.

Modifying visualization properties

The two visualizations that have been created so far are given default properties values - they are line plots with errorbars are no symbols. The visualization properties can be easily changed. In the next few steps we will quickly alter the first (signal) plot that was created from a black line with errors to blue symbols with errors and the second (background) plot from a black line with errors to a thicker black line without errors. It is obviously clear that many aspects of the visualization can be easily customized using the visualization property sheet. In addition, annotations such as text and drawn shapes can be quickly added. For example, to add a legend, do the following:

Basic data manipulations - operations

There are two main ways of initiating actions that can modify or maniplate data from the Data Browser container in DAVE:

For this tutorial we will go through a simple exercise of scaling the background data and then subtracting it from the sample + background. As a result of self-shielding, the level of background in the sample run is much reduced. To a first approximation this can be corrected using a self-shielding correction factor. It has been determined that a self-shielding correction factor of 0.38 is required to scale the background intensity. To scale the background data, do the following

To subtract the background data from the sample and background data, follow these steps:

Printing or Exporting Graphics

DAVE visualizations can be sent directly to a printer for printing or exported into an image file. Almost all standard image formats are supported including postscript, JPEG and PNG.

Printing

To print to a printer, it is probably wise to make use of the print preview option. This allows you to set options such as page orientation, size of the plot on the page, etc. Activate the print preview from the Visualization Window's File => Print Preview... menu. A print preview dialog will be displayed showing a preview of the contents of the graphics window. Use it to customize the way you want the printed output to look like. The following screenshot shows the print preview dialog in action:

print_prev1
Print Preview dialog.

These tasks will typically be performed using the dialog:


Exporting Graphics

Exporting graphics into image file in DAVE is as easy as running through the build-in IDL data export wizard. Initiate the action by selecting the File => Export... menu from the Visualization Window. The 3 part export wizard will be activated.

In step 1 of the export wizard, choose the option to export to a file. exportgraphwizard1.png
Graphics export wizard

In step 2 of the export wizard, you have to select the component of the visualization to export. The tree representation here is identical to that shown in the Visualization Browser. Usually, you would want to export the entire scene so you select the top-level node (he34_x05 in this case) as indicated in the screenshot. exportgraphwizard2.png
Graphics export wizard

In the final step of the export wizard,
  • Specify the output filename to save to.
  • Select the file type or graphics format to use from the droplist. All major image formats are supported. In this example JPEG has been selected.
  • Decide whether to scale the image relative to its dafault size in the Visualizing Window.
  • Modify the properties of the image as necessary in the property sheet - this would be format dependent.
  • Finally, click on the Finish button to export the graphics.
exportgraphwizard3.png
Graphics export wizard

The exported image can be viewed with an external program and should look like this:

exportgraph_plot1.jpg
Exported JPEG image



Saving Datasets and/or Project

Saving Datasets

At any point during a DAVE session, it is possible to save any loaded dataset into any supported output data format. Currently supported output formats include ASCII (3 columns, group and SPE) and the DAVE binary format. The saved dataset will include all the changes that have been made to any of its components.
Note
It is not possible to independently save a component of a dataset - the entire dataset has to be saved. DAVE will pop-up an error dialog if an attempt is made to select and save a component.

To save a dataset, first select it from the Data Browser in the main application window. Then activate the save action by selecting one of the supported output format options listed under the Data Input/Output => Write Dataset As menu. In the following screenshot, the DAVE option has been selected which uses IDL's build in binary sav file format.

save_dataset_menu1.png
Menu item to activate saving a dataset. Since the he34_x05 dataset is selected, it would be saved as a DAVE dataset once the highlighted menu is activated.


Saving and opening Projects

With the introduction of project files in DAVE, it is now possible to save the end results of a session and to return to it later when the application is restarted. This is a very convenient feature that will elliminates a lot of wasted effort in repeating the same tasks whenever you are forced to close and restart the application.
To demonstrate the functionality, follow through these steps: