Introduction
In analysis of any experimental data it is useful to test content of the data files. To perform this task LCLS users need in flexible interactive tool. PSDM group have evaluated a couple of currently available generic tools which work with HDF5 data presentation, [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 camera images, ViTables does not have any graphics at all. 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 flexebility in implementation of graphical algorithms we desided to develop our own Event display. After [discussion of the platform for Event display] we came to conclusion that the most clean and compact code can be written on Python with broad exploitation of standard libraries for graphics and GUIs, such as matplotlib and PyQt4, respectively. Below we overview features and status of the Event display which works with HDF5 files.
Event display features
This program is designed to access LCLS data in HDF5 files and present them in printable or graphical formats. Currently the 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 2D images
- Waveforms
- Correlations between scalar parameters
- Event averaging
- Apply the event selection using amplitude thresholds in specified regions of images
- Save and retreive 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 [PCDS:Computing] and [Account Setup].
Being on psana0### one may get 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
If you are going to use the HDF5 files from Lustre file system, this program should be run on psana0###.
Event Display GUIs
Execution of this program begins with displaying of the Main GUI. All other GUIs and plots can be lunched
by clicking on mouse starting from the Main GUI. Next section explains what can be done through the Event display system of GUIs.
Main GUI
Main GUI is a central control unit of the Event display.
Each button or field in this 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:
<INPUT size="12" type="text" value="path-and-name"></INPUT>
- 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.
<INPUT type="button" value="Browse"></INPUT>
- 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.
<INPUT type="button" value="Open HDF5 tree"></INPUT>
- open / close the [*HDF5 tree and item selection GUI*].
<INPUT type="button" value="What to display"></INPUT>
- open / close the [*What to display GUI*].
<INPUT type="button" value="Selection"></INPUT>
- open / close the [*Selection GUI*].
<INPUT type="button" value="Configuration"></INPUT><INPUT type="button" value="Save"></INPUT>
- open / close the [*Configuration GUI*], and saves current configuration in the configuration file.
<INPUT type="button" value="Exit"></INPUT>
- closes all windows and exits program. The same operation is defined for the
<INPUT type="button" value="×"></INPUT>
button in the top-right corner.
The middle section of the Main GUI, contained in the rectangular frame, is intended for several event drawing modes. Meaning and functionality of these buttons and fields is quite intuitive;
<INPUT checked="checked" type="checkbox"></INPUT>
Apply selection - checkbox 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:
<INPUT size="12" type="text" value="event number"></INPUT>
- sets the current event number, which is used in "Drawing", "Slide show", and "Average" modes.
Span:
<INPUT type="button" value="?"></INPUT><INPUT size="14" type="text" value="number of events"></INPUT><INPUT type="button" value="?"></INPUT>
- sets the number of events for span interval. This number is used in "Drawing", "Slide show", and "Average" modes.
<INPUT type="button" value="Reset"></INPUT>
- button resets current event and span to 0 and 1, respectively.
Draw:
Slide show:
<INPUT type="button" value="Average"></INPUT>
over
events
- this procedure loop over "number of events" beginning from current and calculate the average images and waveforms. If the "Apply selection" checkbox is checked, this procedure only accounts for events with fulfilled selection condition. In this case the "number of events" actually means the number of selected event.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 for this GUI are presented by icons on tool-bar and repeated in the menu-bar. Their meaning and functionality from left to right on tool-bar is presented as follows.
Exit - close GUI window, the same as
<INPUT type="button" value="×"></INPUT>
button in the top-right corner.
Check - save all currently checked items for current configuration.
Reset - resets all check boxes in unchecked state.
Retreive - restore 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 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 excelent oportunity to explore and check the structure of the HDF5 file.
Clicking on any item of this tree, prints useful information about 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 the desired list of datasets is choosen, 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 checkbox is checked, the relevant plot parameters appears in the bottom part of the GUI. Tabbar in the middle also allows to switch between parameter definition GUIs.
Currently implemented plots are grouped in groups as follows.
CSpad
These plots present the CSpad image dataset, 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:
<INPUT checked="checked" type="checkbox"></INPUT>
[8 of 2x1 ]
<INPUT checked="checked" type="checkbox"></INPUT>
[Quad]
<INPUT checked="checked" type="checkbox"></INPUT>
[Detector ]
Spectra:
<INPUT checked="checked" type="checkbox"></INPUT>
[8 of 2x1]
<INPUT checked="checked" type="checkbox"></INPUT>
[16 ASICs]
Projections:
<INPUT checked="checked" type="checkbox"></INPUT>
[X ]
<INPUT checked="checked" type="checkbox"></INPUT>
[Y ]
<INPUT checked="checked" type="checkbox"></INPUT>
[R ]
<INPUT checked="checked" type="checkbox"></INPUT>
[Phi]
Image & Spectrum:
<INPUT checked="checked" type="checkbox"></INPUT>
[1 of 2x1]
Images
These plots present the Camera image dataset, for example
/Configure:0000/Run:0000/CalibCycle:0000/Camera::FrameV1/CxiSc1.0:Tm6740.0/image,
which should be checked in the [*HDF5 tree and item selection GUI*].
<INPUT checked="checked" type="checkbox"></INPUT>
[Image ]
<INPUT checked="checked" type="checkbox"></INPUT>
[Spectrum ]
<INPUT checked="checked" type="checkbox"></INPUT>
[Image and Spectrum ]
and projections:
<INPUT checked="checked" type="checkbox"></INPUT>
[X ]
<INPUT checked="checked" type="checkbox"></INPUT>
[Y ]
<INPUT checked="checked" type="checkbox"></INPUT>
[R ]
<INPUT checked="checked" type="checkbox"></INPUT>
[Phi]
Other
These plots present different other datasets.
<INPUT checked="checked" type="checkbox"></INPUT>
[Waveform]
is intended for the "waveform"-like datasets, for example
/Configure:0000/Run:0000/CalibCycle:0000/Acqiris::DataDescV1/AmoETOF.0:Acqiris.0/waveforms
<INPUT checked="checked" type="checkbox"></INPUT>
[Correlations]
is intended for multidimensional datasets, for example
/Configure:0000/Run:0000/CalibCycle:0000/Ipimb::DataV1/CxiDg1.0:Ipimb.0/data (channel0, channel1, ...)
/Configure:0000/Run:0000/CalibCycle:0000/Ipimb::DataV1/CxiDg1.0:Ipimb.0/time (seconds, nanoseconds)
The bottom part of the [*What to display GUI*] is intended to set parameters for different plots.
These sub-GUIs can be switched by clicking on the tubbar buttons
<INPUT type="button" style="color:red" value="CSpad"></INPUT> <INPUT type="button" style="color:blue" value="Image"></INPUT> <INPUT type="button" style="color:green" value="Waveform"></INPUT> <INPUT type="button" style="color:magenta" value="Proj."></INPUT> <INPUT type="button" style="color:black" value="Corr."></INPUT>
or selecting appropriate check boxes.
CSpad, Image, Wave, Correlation GUIs
and projection plots, which can be also selected by the tab bar for
X, Y, R, and Phi projection GUIs
Projection plot parameters
<INPUT type="button" style="color:magenta" value="Proj."></INPUT>
can be selected by clicking on the tabbar for
<INPUT type="button" style="color:red" value="X"></INPUT> <INPUT type="button" style="color:magenta" value="Y"></INPUT> <INPUT type="button" style="color:blue" value="R"></INPUT> <INPUT type="button" style="color:green" value="Phi"></INPUT>
projections,
All these sub-GUIs have uniform layout of fields for monitoring and editing parameters as follows.
Configuration GUI
Selection GUI
Image of the detector
Zoomed-in CSpad image with selection window and averaged image
Image of the quad
Spectra of ASICs and 2x1 pairs, image and spectrum of pair
X, Y, R, and Phi projections of CSpad
Plots for camera images
Entire camera image (white box shows the selection window), zoomed-in camera image, spectrum of amplitudes and combined plot for image and spectrum
Camera image and X, Y, R, and Phi projections
Plots for waveforms
For auto and manual adjustment of the range parameters