peaksearch

Peaksearch

Fable peaksearch is the graphical user interface (GUI) for peaksearch written in python.
As describes in the python part, peaksearch takes place in imageD11. Peaksearch GUI has been developed to offer a user friendly interface and to display output in a grid.
GUI offers the possibilities:
- Searches peaks on several directories with image files, called "Samples" via Sample chooser view (on the left in the perspective),
- Displays 3D peaks file, called peaks_t###.flt in a grid view,
- Displays 2D peaks file, called peaks.spt by default, in a grid view,
- Plots z vs x found in 3D peaks output file, and offers the possibility to plot others values,
- Displays peaks 2D in the image view (from imageviewer).

1. User guide (menu help/Help contents - peaksearch)

Remark : screen shots have been captured on windows xp OS.

1. 1 Peaksearch perspective

In menu "Peaksearch", select "Open Peaksearch Perspective". By default if you have a screen height < 1000 pixels, peaksearch small perspective opens. You can change this either in menu Window/Preferences/Configuration to open only small/normal perspective, or switch to a normal/small perspective in menu Window/ Open Perspective/Other.
Below is peaksearch perspective (normal perspective) :

Fig1 : Peaksearch perspective and Options view : On the left side, Options view, behind is a Image navigator if you want to search for peaks on several directories with shared options (*). The rigth pane is dedicated to Editors : Filtered peaks file and Spot files. On the bottom of the perspective is fable console where peaksearch output are displayed.

2. Peak Searching

2.1 How to start

You can either select one or several directories in Image Navigator to do the peaksearch with common options or put one stem in peaksearch view as you would have done with the command line (with the path if files are not in fable application current directory see Fig.1).
If you peak search on several directories, all directories available in image Navigator will be taken in account. Common options * for all directories you choose are : darkfile, darkfile offset, SplineFile, perfect images, Flood, Thresholds, OmegaOverride, Step and Start. Other options varies depending on what value you put in the fields.

Required fields have the yellow tag in front of the fields ; if a field has an error value (!), you will find the red ! .

Input file: The name of input files (the images) should follow this convention:
filename = stem+nr+ “.” +fmt, where nr is an ndigit -digit number and fmt is one of the allowed formats (see box). Remember to specify ndigit –default is 4.

Formats [all fabio file formats are allowed], including:
".edf",".edf.gz",".edf.bz2",
".tif",".tif.gz",".tif.bz2",
".mccd",".mccd.gz",".mccd.bz2"

Specify "GE" or "bruker" for some special cases needed for those formats

2. 2 Optional corrections of images

Default is to use none
Darkfile: A fixed image is subtracted from all images – this may be a conventional background file as well as a real darkfield image (with no exposure, only readout noise). In order not to subtract a Darkfile, leave the entry blank.
Darkfileoffset : Subtract a (positive) constant from darkfile before subtracting the darkfile. This is used to avoid overflows. In order not to add any offset write “0”.
Spatial distortion: In order to perform this correction tick “No” in “Perfect Images” and enter the Splinefilename. Determining the splinefit is not part of the FABLE package, but should be done by Fit2D. Be sure to use the pixel size data from this file when computing the detector calibration parameters. Corrections are applied to peaks positions,NOT to the raw images.
Example spline file for ID11 Frelon4M detector: frelon4m.spline

Flood field : This is a correction for inhomogenities in detector efficiency among the detector pixels. In order not to perform a Floodfield correction, leave the entry blank.

Omega : each image must be associated with the center value in the omega range over which it was acquired. By default FABLE assumes the omega value to be read from image header. Alternatively, tick “OmegaOverride” and specify the start omega (in deg) and step in omega (in deg). Note that start omega is the beginning of the omega osc.range for the first image, not the center value.

Thresholds : Peaksearch enables spot finding for several threshold simultaneously – in this case 500 and 2000. (No blanks in input). The threshold is defined after the optional corrections of the images. To peak search for several threshold, list them in field threshold and separate each value with "," : 500, 2000 for example (see screenshot for example). To define a threshold, you can use ImageViewer perspective.

Output file: On successful completion Peaksearch will produce two files .spt and .flt. For format and content see below.

- peaks_t500.flt and peaks_t2000.flt : for the 3D peaks file
- peaks_t500.spt and peaks_t2000.spt: for the 2d peaks file.
Processing : tick "one thread" off or on depending wether Peaksearch is to run on a cluster (with several threads) or a stand alone computer, respectively.

3. Running peaksearch[[Image(...)]]

After all fields have been set, launch peaksearch with yellow arrow in Peaksearch options view or in the top of the view.
Once all options are set, you can save them in a file which can be set as a preference in Menu Window/Preferences/Peaksearch.

3. 1 Save options[[Image(...)]]

In menu Peaksearch, select Options..../Save Peaksearch options. There is also the same options in the view.
Depending on you operating System , by default the format is .xml. If no format is proposed, please save your file as XML format in the Save as dialog box.

3. 2 Load Options[[Image(...)]]

If you have saved several xml options file, you can load an options file in menu Peaksearch/ Options..../Load Options. There is also the same options in the view.

4. [[Image(...)]] Spot file (2D peaks file) : format and display

4. 1 Format

These files are the output of the 2D cluster analysis. For each image it lists the 2D peaks found and their properties. Example output:

# File Test_data0000.edf
[ ...etc... ]
# Number_of_pixels Average_counts f s fc sc sig_f sig_s cov_fs
37 180.648649 121.105177 988.061490 121.105177 988.061490 1.436834 1.424739 -0.000309
26 42.000000 513.627289 1378.409341 513.627289 1378.409341 1.441569 1.443066 -0.016903

# File Test_data0001.edf
[ ...etc... ]

The variables have the following meanings:
Number_of_pixels is the number of pixels in the connected object.
Average_counts is the average counts in each pixel in that object. If the camera has a constant offset (in this case about 1000) then you need to subtract that number before computing intensities. In this case intensity is approximately number_of_pixels(Average_counts-1000.0)
f and s are the position of the centre of mass of the peak in the uncorrected image The definition of f and s are in terms of the fast and slow array indices as the image comes into memory, so it depends on how the image was stored in the file and the routine which read it in as to what you might finally get.
fc and sc are the f and s positions corrected for spatial distortion.
sig_f and sig_s are the second moments of the intensity distribution in the blob. Something like the width, normalised by (N-1) to avoid some divide by zero issue.
cov_fs* is the covariance (the third one of the second moments). It ranges between -1 and 1 with a value of 0 for a circular peak and +1 and -1 referring to elliptical shapes rotated by 90 degrees from each other..

4. 2 Display (in our example peaks_t2000.spt)

To display 2D outfile for peaksearch, select menu peaksearch/open 2D peaks and load a spt file.

Two views open :

• 2D Peaks view: Displays a table with the files on which peaksearch has been launched (here first file was 0 and last 4 in my example). If you select a file in the list, it is displayed in the view. If you select one or more peaks in the table (right pane), they are displayed in green in the image.
• Image View : Displays selected file in the table (left pane) and its peaks in red square or green square for selected peaks.

Output view looks like that once you have loaded the file :

Fig. 2 Spot file view : This view displays peaks in imageviewer.

5. [[Image(...)]] Filtered peaks file (3D peaks) : format and display

5.1 Format

The file s the output of the 3D cluster analysis. It lists the 3D peaks and their properties.
Example output

sc fc omega Number_of_pixels avg_intensity s_raw f_raw sigs sigf covsf sigo covso covfo sum_intensity sum_intensity^2 IMax_int IMax_s IMax_f IMax_o Min_s Max_s Min_f Max_f Min_o Max_o
dety detz onfirst onlast spot3d_id
192.0157 82.7638 0.2500 10 12.7000 192.0157 82.7638 1.2327 1.3039 -0.0026 1.0000 0.0000 0.0000 127.0000 1867.0000 23.0000 192 83 0.2500 191 193 81 84 0.2500 0.2500 -82.7638 192.0157 1 0 0

Some of the variables were introduced above.
A "blob" is a 3D connected object of pixels who are above the threshold level in the peaksearch.
Among the others we mention:
sigo covso covfo: are the second moments of the intensity distribution in the blob in omega scaled by the omega step size which is assumed to be constant. Covariances with fast/slow pixel directions analogously to covsf.
sum_intensity the sum of the intensity of the pixels in the blob.
IMax_int IMax_s IMax_f IMax_o: the intensity value and slow, fast and omega co-ordinates of the maximum pixel in the blob.
Min_s Max_s Min_f Max_f Min_o Max_o: the minimum and maximum slow, fast and omega bounding box for the blob
dety detz: Currently rubbish, please ignore
onfirst onlast: Whether or not the blob is on the first or last frame in the peaksearch series [0 false, 1 true]
spot3d_id: A global id, starting at 0.

5. 2 Display ( peaks_t2000.flt in our example)

Choose menu peaksearch/open 3D peaks(.flt) and load a filtered peaks file.
Two views open (see below) :

• The first one displays a plot. By default sc and fc are plotted. But you can easily change plot in plot option (X and Y lists) : you can zoom your interesting area (ctrl + mouse selection),

X min/max values and Y max/min fields in Group Plot Editor are updated with chart new values .Click on keep or remove buttons ; spots selected in X min/max values and Y max/min area are kept/removed, and table view is updated

• The second view displays all data in a table. If you select one or several rows, plot displays your selection with red cross (see Fig. 3 Filtered peaks file plot.)

You can choose to remove or keep data in the table with a right click on the selected rows. A menu appears : select either keep or throw to remove selection. Plot is updated too.

If data have changed (remove/throw), a star * appears on the top of the editors. You can save your new filtered peak file using either menu File/Save File/Save as . Theses actions are also available in the coolbar.

Remark: Plot view is a Column file plot view. A column file is a file with columns as it is in filtered peak file ; this plot allows you to select interesting peaks and to save it in a file :

Fig. 3 Filtered peaks file : .flt file is displayed in a table and in a plot. You can change plot in Plot options with list X and List Y.

6. How does it work?

The algorithm used is based on a disjoint set, which is described in "Introduction to Algorithms" by Cormen, Leiserson., Rivest and Stein. An image is scanned row by row and each pixel is compared to a threshold value. If the pixel is above the threshold, it will be labelled as a peak. To determine the labels the pixel is compared to the previous pixel, and the pixels on the previous row. If one of these pixels is already labelled, the current pixel takes the same label. When there is a disagreement about labelling, the two labels are made the same using the "disjoint set"

oooooooooooo    o = pixel below threshold
oo1ooooo2ooo    1,2 = labels
o111ooo222oo    X pixel where label 1 and label 2 must be made equivalent
oo1111X

The connectivity in the 2D image is NNN or 8-connected, that is:

  0  0  0
  0  X  0
  0  0  0

The resulting 2D blobs are called spots or 2D peaks in FABLE.

The second part of the algorithm merges adjacent omega-frames. When pixels with exactly the same position in adjacent frames both are labeled, these labels are made equivalent. The connectivity along omega is NN only. The results are 3D blobs, known in FABLE as 3D peaks.

Peaks that are connected to the border of the detector area are allowed. So are peaks at the limits of the omega range

7. Installing

If you have installed the whole package FABLE, peaksearch GUI is ready to go.

8. Version

Sources code 1.0.5

Peaksearch is released with python programs which it depends and also their dependencies. These programs are available in python folder.
You don't have to install them, script file you launch for peaksearch set this path to python path.
Here are the two fable python program on which peaksearch GUI relies :
- ImageD11: version 1.2.1
- fabio : version 0.0.2

These fable python relies on numpy and PIL available in python folder.

9. Bug reports

Please sends bug with a priority number from sf.net/projects/fable/trackers/

10. TODO

• Editor filtered peaks file : layout to improve. Add an options to hide options as it is done in Culumnfile view.
• Find out how to set a default directory (which default directory) in spot view for the directory browser.
• Display a dialog box to user when it overrides an existing xml file : "This file already exists, do you want to override it?"
• move peaksearch option view to an editor ?(with 2 pages : one with xml and the other with option)
• Restore f1 help context (disappear?)