## Getting Started with DAVE

Introduction

The Main Application Window

Loading Data

Manipulating and Visualizing Data

Printing or Exporting Graphics

Saving Datasets and/or Project

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

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:

- Menus and toolbar providing access to common tasks. Some of the entries in the menus and toolbar are context sensitive, depending on the selected item(s) within the main window.
- Data and Visualization browsers are located in the top left part of the main window. The data browser provides a tree view representation of the datasets that are currently loaded into DAVE. Similarly, the visualization browser displays a tree view of all existing visualizations. Tabs are used to switch between the data browser and the visualization browser.
- A Data/Visualization Property area at the top right quadrant is used for displaying the properties and values of selected items from the data or visualization browser.
- A Visualization Editor is placed just below the data and visualization browsers and enables a user to quickly associate data and visualization parameters when creating or modifying a visualization.
- A Parameter details component, located to the left of the Visualization Editor, displays the IDL data types that are accepted by the visualization parameter that is currently selected in the Visualization Editor.
- Visualization Tasks are a set of buttons near the bottom of the window that are used for initiating actions that create new visualizations or alter existing ones.
- Finally, the Status bar at the bottom is used for displaying hints, progress information, warning or error messages, etc to the user.

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: 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 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:

- From the main window select the Data Input/Output => Read Dataset From => ASCII (txt,spe,...) menu option. A file selection dialog that is operating system dependent is displayed in response. The default search path for the file selection dialog should be the working directory that was selected earlier.

  File selection dialog

  If the steps outlined earlier were followed, then the two ASCII files he34_x05.dat and he34_bkgd.dat should be visible in the file selection dialog. If they are not, then browse to the location where they were saved in.

- Select he34_x05.dat and press Open button (OKbutton on UNIX). Since ASCII files usually do not contain sufficient information (e.g. axes labels), a dialog wizard is typically displayed help you through the remainder of the data loading. The dialog depends on the type of ASCII file being loaded. For an ASCII file containing columnar data, a 3 step wizard is initiated with the following dialog:

  Wizard for reading ASCII column data: step 1 of 3

  The dialog shows the data columns read from the file with options to specify how the columns are separated, comments to ignore and the line number where the real data starts. The first line in the data file contains comments/axes labels so we want to start reading data from line 2. So enter 2 in the Data Starts at Line: field - the comment line should disappear from the data shown. Click on the Next>> button at the bottom right of the dialog to continue to step 2.

  Wizard for reading ASCII column data: step 2 of 3

  The step 2 dialog allows you to indicate the number of valid data columns and the delimiter used between the columns. The default values for both are correct so click on the Next>> button to proceed.

  Wizard for reading ASCII column data: step 3 of 3

  In step 3, you should assign sensible labels to the data columns which will be used later in plotting. Also you can alter the data type for any column that appears incorrect on inspection. The default column names are shown on the left screedshot. Use the mouse to select each of the 3 fields from the top left of the dialog. For each field, enter a column name in the Name field located slightly to the right and press the Enter when complete. Note that non-alphanumeric and special characters (space, comma, brackets etc) are not allowed to be used in column names!. When done, the three fields should have the labels shown in the right screenshot. Click on the Finish button to complete the wizard. An entry will be created in the Data Browser tree in the main window (see below).

- Repeat the above steps to load the second ASCII data file he34_bkgd.dat.
- Load a third data file, dcs_example.dave. This is a DAVE format file so use the Data Input/Output => Read Dataset From => DAVE menu option. Note that no additional wizard is used in the reading of *.dave files since they contain metadata in addition to the plottable data.

  New dataset entries in the Data Browser tree

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:

- the dependent data - JQY leaf node
- the error in the dependent data - Error leaf node and
- the independent data - Y leaf node.

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:

- the dependent data - S(Q,omega) leaf node
- two independent data - Energy Transfer and mean Q leaves
- the error in the dependent data - Error leaf node.

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 (if 1D - one independent variable) or (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 property | Meaning in a visualization
X | First independent axis data (x-axis)
Y | Second independent axis data (y-axis)
Data | Dependent axis data (z-axis)
Error | Error 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:

- Choose the type of visualization to create (Plot, Contour, Surface, etc).
- Each visualization has parameters that are required to create it such as the dependent and independent axes data. The user must make these assignments. However, for a plottable dataset the data items it contains are already tagged so their association with visualization parameters can be done automatically for you.
- Click on a button to create the visualization.

#### 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:

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.

- Ensure the appropriate visualization type is selected - choose Plot for this tutorial.
- From the Data Browser, select the plottable dataset (should have an associated or icon) to visualize. Select the he34_x05 node as shown in the screenshot below. The button located between the Data Browser and the Visualization Editor should now be active (clickable).
- Click on the button to automatically associate data items within the dataset with parameters of the Plot visualization as shown in the right screedshot below. The Axis Type property of the data items discussed earlier enables this automatic assignment to be possible. It is also possble to manually assign a data item with a visualization parameter and this is described in Introduction to Visualization

Before (left) and after (right) assigning data to visualization parameters by clicking the 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 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.

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:

- Select the Modify visualization task option as shown in this next shot.

  Modify visualization parameters option

- Select the visualization to be modified by clicking on the appropriate visualization window followed by a selection of the actual visualization (e.g. line plot, contours, etc) from the embedded graphics window. The visualization editor parameters will be updated with the details of the selection.
- In the main DAVE window, modify the data assigned to the visualization parameters using the procedure described earlier.
- Finally, click on the Modify Visualization button to commit the change(s).

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.

- Select the Add visualization task option as shown.

  Options to add visualization to an existing visualization window

- Select a visualization by clicking on the graphics region of the visualization window that was created previously under "Create a new visualization".
- In the visualization editor (main DAVE window), the Plot visualization type should have been selected due to the previous step. Assign data to visualization parameters:
  - Select the he34_bkgd folder from the data browser.
  - Click on the button to assign data in the he34_bkgd folder to the visualization parameters in the property sheet below.
- If the data assignment was successful, the Add Visualization button should become clickable. Click on it to proceed. DAVE responds by creating a new plot in the previously selected visualization window as shown next.

  New plot added to existing visualization - both share a common dataspace

#### 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.

- In the main application window, ensure that the Visualization Browser tab is selected. The Visualization Browser shows a tree view of all existing visualizations. Based on what has been done so far, the contents of the Visualization Browser should looked like this:

  The Visualization Browser provides a hierarchical tree view of all existing visualizations

  For each Visualization Window (containing graphics), there will be a corresponding node of the same name in the Visualization Browser. Currently, we should have one Visualization Window to match the he34_x05 node in the Visualization Browser tree. The branches and leaves underneath the node represent the main components of the visualization. Each visualization contains at least one view (View_1 in this case) and the view contains a visualization layer in which all the visual components of the visualization are located. The Data Space and Annotation Layer are located within the visualization layer. The entries in the Data Space represent the standard visual components in the Visualization Window view. Plot represents the first line plot that was created and Plot 1 the second line plot that was added.

- In the Visualization Browser, select the Plot item. Whenever any item is selected in the tree, two things happen. 1) If the item is a visual component, it would be highlighted in the Visualization Window. 2) The properties of the item will be displayed in the Visualization Properties sheet to the left of the Visualization Browser in the main application window. The value of any editable property can be easily changed from the Visualization Properties sheet. To demonstrate this, locate the Line style property (use the scroll bar if necessary). Click on its value. This should result in a droplist of possible linestyles to select from (note: on UNIX, it may be necessary to click on the downarrow tab that appears on the extreme right of the value field to activate the droplist). Select the "No line" option from the list. The Visualization Window should be updated immediately. Also add a symbol by locating the Symbol property and selecting a suitable symbol from the droplist - I selected a triangle. Next locate and change the Error bar color and Color properties by choosing a suitable color from the pop-up color palette - I selected blue. Finally, change the Name property from "Plot" to "Sample + Bkgd"

  Note it is good practice to use the return key after you finish entering text into any text field widget.

- In the Visualization Browser, select the Plot 1 item. From the property sheet, locate the Y error bars property and switch its value from "Show" to "Hide". Change the Color property from the default black to red and the Thickness (refers to line thickness) from 1 to 2. Also change Name from "Plot 1" to "Bkgd". The Visualization Window should now look like this:

  Modified plot using visualization property sheet

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:

- Ensure that the Data Space is selected. This can be done by selecting it from the Visualization Browser tree or by clicking on any free space within the plot axes in the Visualization Window.

  Note In general, a visual component within a visualization can be selected by either selecting it from the display directly or from the visualization browser tree.

- In the Visualization Window, select the Insert => New Legend menu option. A new legend will be created and added to the visualization somewhere near the top right hand corner of the graphics window. You can use the mouse to select it and move it to any desired location, while holding down the left mouse button. Note that a new entry for the legend is also created in the visualization browser tree underneath the Annotation Layer. Select the Legend item from the visualization browser and then change its Text font size property from the default 12 to 9. Also modify its Transparency from 0 to 50% and the Line style to "No line". Your visualization should now look something similar to this:

  Plot with legend

#### 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:

- Right-click on an item (branch or leaf) from the the data browser tree and then select an action from the context-sensitive menu that is displayed. Useful tasks such as deleting and duplicating datasets can be achieved in this way.
- Select one or more data items from the data browser tree and then select an action from the Analysis top-level menu to operate on the selected data. The menu entries within Analysis are context-sensitive and so are only availabe if they can operate on the current selection(s) in the data browser tree. Various data operations such as scaling, rebinning, summing, etc can be launched using this method.

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

- Select the Data Browser tab in the main application window.
- Expand the he34_bkgd node, if necessary.
- Select the JQY item - this is the intensity axis for the background dataset.
- Select the Analysis => Data Transform => Scale menu from the main application window.
- The following input parameter dialog for the Scale operation should pop up.

  Scale operation dialog

  Dialog simply displays a property sheet showing the properties that can be used to modify the operation. Change the Scalefactor property value to 0.38. Select the OK button to accept and execute the operation. The background intensity should now be scaled by 0.38 and this would be reflected in any visualization using the bakground intensity after an automatic update. Your Visualization Window should now look like this:

  Backgroung intensity has been scaled by 0.38

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

- From the Data Browser, select both the he34_x05 and he34_bkgd items.

  Note Use the Ctrl or Shift keys together with the left mouse button to select multiple items in a tree widget.

- Select the Analysis => Data Transform => Subtract menu from the main application window.
- The following Subtract operation dialog will be displayed

  Subtract operation dialog

  Ensure that the Dataset 1 (input/output) field is asigned the value "he34_x05" and that Dataset 2 (input) is asigned the value "he34_bkgd". This is important because the subtraction is performed and the results saved using
  Dataset 1 = Dataset 1 - Dataset 2
  Click the OK button to accept and execute the operation.

  Note If you do not wish to proceed with an operation, use the Cancel button to dismiss the operation dialog.

  The visualization should be updated to reflect the subtracted background dataset from the sample and background dataset. Note that the uncertainty in the subtracted dataset is properly propagated during the process.
- Update the plot legend. Choose the Visualization Browser tab. Expand the Legend item and select the first Plot Legend Item in the list. From the property sheet, modify the Text property and change it from "Sample + Bkgd" to "Sample, bkgd sub".
- Delete the background plot from the visualization. From the Visualization Window, select the background plot by clicking on it - it should appear highlighted. Right-click on it to display a context-sensitive menu and then select the Delete option. The background plot should be removed from the visualization and every where else that it was being referenced. Note that if you accidentally deleted something else, simply use the button from the toolbar section of the Visualization Window to undo the change. Your visualization should currently look like:

  After background subtraction

### 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 Preview dialog.

These tasks will typically be performed using the dialog:

- Page orientation using the droplist at the bottom.
- The size and location of the plot on the display. Use the mouse to adjust the size of the plot by dragging on the filled square at the top right corner of the plot outline. Click and drag within the outline to position the plot.
- Check the Center box to center the plot on the page.
- Use the Setup... button to select from a list of installed printers.
- Finally, print by clicking on the Print button.

#### 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. |
| 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. |
| 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. |
| Graphics export wizard

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

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.

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:

- From the main application window, select the File => Save Project menu or the button to launch the save project action. |

- In the file dialog that is displayed, type or select a suitable project name - the default name is "Untitled" and the default extension for DAVE project files is ".disv". Select the Save button to save the project. I typed in "He34" as the project name.

  Note If the current project's name is anything other than "Untitled", the file dialog will not be displayed unless the Save Project As menu was used.

- The project file will be created and the new project name will be reflected in the main window and all open visualization windows in the current session.

  The saved project name "He34.disv" is reflected in any DAVE application window title, replacing "Untitled".

- Since the project is now created, it is safe to go ahead and exit DAVE. Use File => Exit from the main application window to accomplish this.
- Restart DAVE again.
- Select the File => Open Project menu or the button to load a project file.
- From the file dialog navigate to the location where the project was saved to in the step above. Select "He34.disv" (or the whatever name you used) and click on Open to load the project.
- You should find that DAVE should be in the same state as it was when the project file was last saved.

  Note All datasets and visualizations are saved with a project. However, the undo/redo buffer is not maintained between DAVE sessions.

  You should be able to continue working with your project just as you were before the session was closed!