This note is about an old version of this program.
Please see HDF5 Explorer - Old for current version.

Introduction

In analysis of experimental data it is useful to test content of the data files. To perform this task LCLS users need in flexible interactive tool. We have evaluated a couple of currently available generic tools which present HDF5 data, HDFView and ViTables. Both of these tools have numerous pros and cons, but, definitely, as is they can not cover all LCLS-specific graphical demands; HDFView has very primitive graphics and can not plot LCLS camera images, ViTables does not have any graphics at all, except for GUI. Extension of these packages for LCLS needs is possible, but requires significant intervention in the code of these quite specific applications. In order to keep flexibility in implementation of graphical algorithms we decided to develop our own Event displays for XTC and HDF5 file formats. After discussion of the platform for the Event display we came to conclusion that most clean and compact code can be written on Python with broad exploitation of standard libraries for HDF5 access, graphics, and GUIs, such as h5py, matplotlib, and PyQt4, respectively. In this note we overview features, functionality, and status of the Event display which works with HDF5 files. XTC Explorer - Old has its own documentation.

Event display features

This program is designed to access LCLS data in HDF5 files and present them in printable and graphical forms. Event display can perform many tasks, as follows.

Select the input HDF5 file
Display entire HDF5 file structure
Print attributes and data structure of each HDF5 item (group or data set)
Select the data-records for graphical presentation
Select type of figures and plot
- Image and spectra for any camera
- Image and spectra for CSpad detector
- X, Y, R, and Phi projections of any 2-D images
- Waveforms
- Correlations between scalar parameters
Event averaging
Apply the event selection using amplitude thresholds in specified regions of images
Save and retrieve the configuration parameters

How to get a copy and run this program

We assume that everything is set up to work on LCLS analysis farm, otherwise see Computing (including Analysis) and Account Setup.

Being on psana0### one may get a source code and build executable:

cd <your-favorite-directory>
newrel ana-current myVersionOfTheEventDisplay
cd myVersionOfTheEventDisplay
sit_setup
addpkg EventDisplay       (at this stage you need to have access to yakut.slac.stanford.edu)
scons

When these stages are passed successfully, the Event display can be started by the command

evtdisplay

This command lunches the graphical user interface (GUI) beginning from the Main GUI. All other GUIs and plots can be lunched by clicking on mouse starting from the Main GUI.

If you are going to use the HDF5 files from Lustre file system, this program should be run on psana0###.

Event Display GUIs

System of GUIs provides a convenient uniform control on execution of the Event display program.
This section explains a functionality of the system of GUIs.

Main GUI

Main GUI is a central control unit of the Event display. Each button or field in this or any other Event display GUI can be activated by clicking on mouse left button. Meaning and functionality of the Main GUI buttons and fields can be listed as follows.

File:

- is used to indicate the HDF5 file path and name. This is a fast method to change the file name, but this is not a recommended way as an error prone due to possible typos at edition of this field.

- opens standard menu to navigate over file system and to select the HDF5 file path and name. This is a recommended way to choose the data file.

- open / close the HDF5 tree and item selection GUI.

- open / close the What to display GUI.

- open / close the Selection GUI.

- open / close the Configuration GUI, and saves current configuration in the configuration file.

- closes all windows and exits program. The same operation is defined for the

button in the top-right corner of the GUI window.

Middle section of the Main GUI, contained in the rectangular frame, is intended for operation with a few event drawing modes. Meaning and functionality of these buttons and fields are quite intuitive;

Apply selection - check box defines if the selection condition set in the Selection GUI are applied. Selection algorithm works for the "Draw", "Slide show", and "Average" modes.

Current event:

- sets the current event number, which is used in "Drawing", "Slide show", and "Average" modes.

Span:

- sets the number of events for span interval. This number is used in "Drawing", "Slide show", and "Average" modes. Left and right arrow-buttons decrements and increments the span value by one unit, respectively.

- button resets current event and span to 0 and 1, respectively.

Draw:

Unknown macro: {html} <INPUT type="button" value="Previous"></INPUT> <INPUT type="button" value="Current"></INPUT> <INPUT type="button" value="Next"></INPUT>

- draws previous, current, or next event, respectively. In case of the "next" and "previous" button, an increment and decrement is defined by the span field. If the "Apply selection" check box is checked, this procedure is repeated recursively until the selection condition is fulfilled.

Slide show:

Unknown macro: {html} <INPUT type="button" value="Start"></INPUT> <INPUT type="button" value="Stop"></INPUT>

- buttons starts or stops the slide show, beginning from current event with interval defined by the span field. If the "Apply selection" check box is checked, this procedure shows events with fulfilled selection condition.

Unknown macro: {html} <INPUT mce_style="background-color: #e6ffe6;" style="background-color: rgb(230, 255, 230);" type="button" value="Average"></INPUT>

over

Unknown macro: {html} <INPUT align="middle" size="14" type="text" value="number of events"></INPUT>

events

- this procedure loops over "number of events" beginning from current and calculate the per-event average images and waveforms. If the "Apply selection" check box is checked, this procedure accounts only for events with fulfilled selection condition. In this case the "number of events" actually means the number of selected event.

- draw the correlation plots correlation plots.

HDF5 tree and item selection GUI

HDF5 tree and item selection GUI shows the HDF5 file tree structure, which resembles the file system tree. Control buttons of this GUI are presented by the icons on tool bar and repeated in the menu bar. Their meaning and functionality from left to right on tool bar are presented as follows.

Exit - closes the GUI window, the same as

button in the top-right corner of this window.

Check - saves all currently checked items for current configuration.

Reset - resets all check boxes in unchecked state.

Retrieve - restores checked items from current configuration.

Expand / collapse - expands / collapses folders from root to the final data items.

Expand / collapse checked - expands / collapses the folders for currently checked data items only.

Print - prints the structure of the HDF5 file tree (does not add too much to the graphical presentation of the HDF5 tree).

This GUI by itself gives an excellent opportunity to explore and check a structure of the HDF5 file. Clicking on any item of this tree, prints associated information for this item and its additional attributes, if available.

All datasets, which you plan to use in graphical presentations, have to be checked in their individual check boxes. When a desired list of datasets is chosen, it needs to be passed to the current configuration by clicking on the Check button.

What to display GUI

What to display GUI is intended to select plots for drawing and to set specific plot parameters. Desired plots can be selected by marking the check boxes in the top part of this GUI. When the check-mark is set, the relevant plot parameters appear in the bottom part of the GUI. Tab bar in the middle also allows to switch between the parameter definition GUIs. Check boxes for plots are grouped in a few sections as follows.

CSpad

These plots present the CSpad image datasets, for example
/Configure:0000/Run:0000/CalibCycle:0000/CsPad::ElementV2/CxiDs1.0:Cspad.0/data,
which should be checked in the HDF5 tree and item selection GUI.

Images: