Page tree

iint is a program developed by Sonia Francoual at P09 beamline for the analysis of resonant scattering data.

iint-gui is an application within the ADAPT framework that combines a graphical user interface with the implementation of the processing steps.


Purpose

iint-gui is designed to facilitate direct and interactive analysis of data collected at P09.

The data is usually stored in SPEC files, usually containing several scans of different types. iint-gui can be used to analyze single scans or series of scans of the same type.

Installation and Start

The program is available as Debian package, just send a mail to fs-ec@desy.de 

There is also the distribution as docker container (see the end of the page).

Once installed just type iint-gui in a shell, or create a desktop shortcut.

The GUI

The program will start up as a GUI:

The left hand side is dedicated for the steering of the processing steps, and displaying the current status of the processing.

At the bottom of the left side, the log message window is present.

The entire right hand side is for displaying the data and the graphical representation of the processing results, as available.


In a working session, the GUI might then look something like:

The log section

The lowermost part of the left side is dedicated for message about the actions that are performed with the data.

Most of the time it will just show what is being done.

Sometimes warning may appear in red text, informing the user that something has not worked as expected.

Most of the time a reason can be hinted at, why the action could not be performed successfully.

Menu items

File menu

Contains all interactions with files.

These are the "Open" actions for the data files, either SPEC or FIO files.

This also can be the "Open" (keyboard shortcut <Ctrl+o> ) or "Save" (keyboard shortcut <Ctrl+s> ) options for the configuration file.

For more information on configuration files see the corresponding section below.

Also the reset of all current settings can be initiated (keyboard shortcut <Ctrl+n> ) 

Information menu

If the respective information is available (check the log message window), different files and processing information can directly be accessed from the GUI.

Options are the config file, the data file(s), the results of the fitting and the actually saved results file.

Help

The help contains a copy of the documentation here and a little information ("about") iint-gui.

Actions to perform on data

Reading data

To select the input spec file, chose from the File menu: "Open SPEC file".

A dialog will open:

Click on "Choose file" to open a file dialog and select a file.

In the "selection" field enter a scan or a scan series. The syntax is similar to a print dialog. Chose individual scans by typing the scan number. A list of scans can be entered by entering the numbers with comma separation, or providing a range with a hyphen.

It is also possible to chose a stride in a scan series by appending a double colon ":" followed by the stride.

Examples:

 series: "699,700, 701, 702, 703, 704" or "699-704"

 with stride: "699-740:2"

 several series: "699-704, 705-710, 711-740"

The selected choice will be displayed in the main window as an entry at the top. In addition the scan type and the motor(s) used in the scan will be displayed.

Note: the selection can only be used if all scans in this selection are of the same type, using the same motor(s)! E.g. a dscan or a scan.


An alternative to reading spec files is using FIO files by selecting "Open FIO file(s)" in the File menu.

The dialog is similar, but since it is based on one scan per file, a list of files needs to be selected.

Note: differing scan ranges

During loading the selected scans as a scan series, the ranges of the given scan command are inspected.

If the ranges are different in the selected motor/s, a dialog will appear that has to be accepted:

If the background integral is calculated, it will only use the smallest common range of all scans in the series.

If several motors have different ranges, as in the example dialog, the first motor will be used by default.

In general, the chosen x-axis/motor will be used; as explained in the following section "Defining the intensity".

Selecting an output directory

The current output directory is shown in the second line of the main window.

iint-gui automatically creates a configuration file, as well as several other files on demand; all of which will be stored at that given location.

By default the output directory is the home directory of the user that started the program.

To change the directory, click the "Select" button and chose a directory in the appearing dialog.

Defining the intensity

In order to define the intensity, the different elements from the expression have to be selected from the available data in the SPEC file.

They are listed in the drop down selection boxes.

obs_i = detector_i\cdot \frac{\overline{monitor}}{monitor_i\cdot time_i}

Initially the setting dialog is folded, click on the triangle to unfold.

Unfolded, the widget with some settings might look like:

As soon as a valid and complete selection for all needed input boxes is available, the selection will be plotted in the plot view window.

In addition an attenuation factor can be added by first activating it with the check box and then selecting an entry from the drop down list.

Also a smoothing filter can be applied to de-spike the data by activating the check box.


The "raw" data, without filtering is displayed as black plus "+" signs. If activated, the de-spiked data points are plotted as dark green "x".

In the display part of the gui, the display of the elements can be toggled by un/selecting the check boxes at the bottom.


The buttons on the bottom of the widget are:

"Select data to track"

From the input file the column data (per point) or header data can be selected.

Either mark an element by clicking on it and use the ">>" or "<<" buttons to transfer them from "untracked" (left hand side) to "tracked" (right hand side) and vice versa.

Optionally double-clicking an element will transfer it.


The program then keeps track of the chosen elements for the following purposes.

It enables storing these values (averaged for column data) in the output file.

In addition the selected data elements can be plotted against each other by clicking the button "2D plot of tracked data" (see description below).

And if subsequently a fit is performed, the parameter values will be displayed  in dependence of the values of the chosen tracked data.

"Plot scan profiles"

Plots the scan idea versus the motor position (from the scan command); first the colour encoding for the z-values has to be chosen.

The intensity would be a natural choice to gain an overview of the complete scan series.

After accepting a setting, a pdf file will be created in the output directory and it will be shown automatically.

"2D plot of tracked data"

Creates a scatter plot of the pair of tracked data that can be chosen in a first step:

Accepting it by choosing "Display" will display it in a new tab in the data display part.

"Overlay"

Different scans can be superimposed to compare them visually by creating an overlay.

First select the list of scans that are to be displayed together.

Either mark the scan ids in the list on the left by mouse or e.g. choosing all by typing <Ctrl-a> and click on the '>>' button (de-selecting works the same in the other direction).

Accepting the choice by clicking on "Done" will display the overlaid spectra in the display part.

The view can be switched to use logarithmic scale, and to display the different processed data (if available).

To change the current selection of scan ids, there is a button "Select Scans" to return to the selection dialog.

Background approximation

If background is to be approximated and subtracted from the raw data, first activate the setting by checking the check box.

First:

then

The current choice will be automatically calculated and displayed in the display part.

Three different types of background approximation are available, selected with the radio buttons.

The background will the be approximated from the given number of points in the beginning and the end of the scan.

Signal fitting

The signal spectrum can be fitted next.

Basis for the fit is the data that is most processed; which can range between the unprocessed raw spectrum to the despiked, background subtracted signal spectrum.

Two different modes of fitting are supported.

Initially the fitting dialog will look like:

Mode 1: "auto Gauss"

By activating the check box next to the label "auto Gauss" a very common use case is activated.

Here a gaussian curve will be fitted to the data; all initialization of the fit parameters is extracted from the data itself.

This is particularly favourable if the fit ranges (e.g. motor positions) of the scan series are very different.

By clicking on the "Fit" button, the fit will be run and displayed in the display part.

Also the results for the fit parameters are shown in a new tab of the display part, giving a complete overview of the scan series.

Mode 2: custom model

In a second procedure the model to be fit can be set up.

First select a function/model from the drop down list and add it to the current model by clicking on "Add".

As an example, after adding two gaussian models the widget will look like:

Since the fit procedure needs start parameters, click on "Configure" to open the configuration dialog.

Here the individual values for the model parameters can be chosen.

For the current parameter values the curves will be superimposed to the data display, as well as the total sum.

As shown in the example image, the colours can be chosen by clicking on "Colour".

Once everything is approximately set up, the "Test" button can be pressed to check on the current spectrum how the fit will look like.

To allow fitting of the series close the dialog with "Done".

The actual fit of the series is then executed by clicking on "Fit".

Automatic calculation of trapezoid integral

As an unseen side effect the trapezoidal sum is always calculated when performing the fit.

Results and further analysis

The last interactive section of the GUI is the part of "Inspection and Analysis".

In total four different actions are available by buttons.

"Show Inspection Plots"

This will create and show a pdf file containing scatter plots of the final fit parameter vs. the values of the chosen tracked data (see above).

It will always include a scatter plot showing the values of the integrated intensities of the scans by the fit and the trapezoidal sum.

"Polarization analysis"

In case the processing of the scan series contains all necessary information, the procedure for the polarization analysis is performed.

A ".stokes" results file is then created in the output directory.

Also a pdf of the fit result plots will be created and shown in a pdf viewer.

"Show fitted scans"

Create and displays a pdf file of all the scans with the superimposed fit curve; e.g. for checking the fits of the whole series.

"Save results"

This will create all pdfs (inspection plots, fitted scans), as well as a text output file containing all fitted and tracked data.

Closing the program

To quit the program either use <ALT+F4>, <Crtl+Q> or the close button of the window manager.

At exit the program will ask if the current configuration should be stored or discarded.


Configuration files

In order to facilitate working with the program, as well as storing processing and analysis settings, iint-gui uses configuration files.

These are automatically created and stored whenever the program is

Naming conventions

The central distinguishing elements in the data processing are the data input file and the selection of scans.

Thus both elements serve as basis in the automatic naming scheme of output files.

An input filename like "MnCo15.spc" with the scan selection "699-740" will create output files with names starting with "MnCo15_S699E740".

Extensions to this are the system time of processing and some declarative name. E.g.:

  MnCo15_S699E740__20190110-17h27_scanControlPlots.pdf for the control plots containing the fits,

  MnCo15_S699E740_20190117-16h22_polarizationAnalysis.pdf for the plots concerning the polarization analysis,

  MnCo15_S699E740_20190117-16h22.stokes for the stokes parameters,

  MnCo15_S699E740_20181205-16h57.icfg for a particular config file.

Hint about configuration file

In case the configuration is saved (e.g. by the shortcut <Ctrl-S> or by choosing the respective File menu item), there will always be a single file with the standard name.

For example in the above case: "MnCo15_S699E740.icfg".

This will be overwritten the next time something is changed, but it is a good way to restart a new session from the last session of the program.

But at saving time, there will always be a second config file written. This has the same base name, but has the system time added to the name.

E.g.: MnCo15_S699E740_20181205-16h57.icfg


The plotting section

The right hand part of the GUI is dedicated to showing the data. It features several options to inspect the data more closely.

If a scan (series) has been defined, and the observable declared, the "Scan display" is the main part.

Top part

Above the plotting part, the Scan ID is shown, as read from the SPEC file.

Also in the top part there is the possibility to browse through the scan series by clicking on the "Prev" and "Next" buttons.

For display purposes only a scan can be removed from being displayed in the fit overview plots.

For this click on the green "Remove from display" button.

If the scan has already been excluded from display, the same button will appear as red and be named "Add to display again".

Main display

Here the data points are plotted.

The raw observable (as defined in the observable section) will be displayed as black plus "+" signs.

In case de-spiking was applied, the de-spiked data points will be shown as dark green "x".

Background will be shown as filled red diamonds, the background subtracted signal is then shown as filled blue circles.

The temporary fit during the configuration is shown as a solid red line; the final fit result is shown as solid blue line.

Bottom part

A few things about the main display can be configured directly.

To display the data in logarithmic ordinate, the check box "logScale" can be toggled.

Since negative values or zero cannot be an argument to the logarithm, there is a lower cutoff of 0.01.

To show the position of the mouse click on the main display, the x and y values are displayed.

If the respective data is present, the check boxes can be toggled to display the raw, de-spiked, background, signal and fit data.


Running in a Docker instance

For Windows 10: install and verify that docker is running, e.g. refer: Docker for Windows 10.

Current status is from Friday, 12 June 2020.

[Optional – will be downloaded also by the run command] Open a (power) shell and download the image:

docker pull christophrosemann/iintgui:v0.16.4

Run the docker image and mount the correct directory. For linux use something like:

docker run -ti --rm  -v /tmp/.X11-unix:/tmp/.X11-unix --user $(id -u):$(id -g) -e QT_X11_NO_MITSHM=1 -e DISPLAY=:1 -v ${datadirectory}:/home/iintuser christophrosemann/iintgui:v0.16.4

For Windows the command has to be slightly changed:

docker run -ti --rm -e QT_X11_NO_MITSHM=1 -e DISPLAY=${DISPLAYNAME} -v ${datadirectory}:/home/iintuser christophrosemann/iintgui:v0.16.4

Note that you need the address of the running X server, and that you need to have opened connections to that server.


Note also that only local directories can be mapped into Docker containers; it is not possible to do this with network drives.



  • No labels