Binoculars tutorial #1 (process images)

Welcome to the first part of tutorial for BINoculars!

The dataset, which is used as and example for this and following tutorials, is a scan along L direction (parallel to the surface normal) complemented with rocking scans at various L values. The advantage is that there is no need to treat the two different types of scans separately, but rather we treat all the images at the same time. The dataset and all the necessary files are in... For more information, see Roobol et al...., Drnec et al., J. Appl. Cryst., 47 (2014), 365-377.

The example dataset used in the three tutorial can be found here

First step is to calculate an HKL map from diffraction images. For that, we need to set up a config file for the particular backend we are going to use. In this tutorial, we use ID03/EH2 backend which is particular for EH2 hutch of ID03 beamline at ESRF. Each experimental setup should have it's own backend, which essentially convert each pixel to HKL map.

Config File (config_tutorial.txt):

config_tutorial.txt

### the DISPATCHER is responsible for job management
[dispatcher]
type = local # run locally
#ncores = 4 # optionally, specify number of cores (autodetect by default)

# To use the OAR cluster at ESRF:

#type = oar
#tmpdir = /some/globally/available/path
#oarsub_options = walltime=0:15 # optionally, tweak oarsub parameters
#executable = python /data/id03/inhouse/binoculars/binoculars.py # optionally, override default location of python and/or BINoculars installation

# Specificy destination file using scan numbers. The {first}-{last} part of the file name will be replaced by the actual scan numbers

destination = ./examples/dataset/maps/scan_{first}-{last}.hdf5 
overwrite = true

# or, by default: numbered files in the form output_###.hdf5:
# destination = output.hdf5
# overwrite = false

### Choose an appropriate INPUT class and specify custom options

[input]
type = id03:eh2 # refers to class EH2 in BINoculars/backends/id03.py

### Select the spec file where the analyzed scan belongs to

specfile = ./examples/dataset/sixc_tutorial.spec

### Select the image folder. {rUCCD[0]} (reverse UCCD list) value is the string of last directory in the UCCD tag in the spec file. The UCCD is the path to the image folder. For example: 
#UCCD = /users/drnec/binoculars_tutorial/images/img_#n_#p_#r14567.edf and {rUCCD[0]}=images

imagefolder = ./examples/dataset/{rUCCD[0]}/  # this will be replaced by ./examples/dataset/images/


## approximate number of images per job, only useful when running on the oar cluster

target_weight = 4000 

# technical yadayada for this particular input class

centralpixel = 345, 391   # x,y
sdd = 586               # sample to detector distance (mm)
pixelsize = 0.055, 0.055 # pixel size x/y (mm)
ymask = 275-485  # y range of the mask. Only pixels within the mask will be taken into consideration
xmask = 273-427  # x range of the mask


### choose PROJECTION plus resolution

[projection]
type = id03:hklprojection # refers to HKLProjection in BINoculars/backends/id03.py
resolution = 0.002, 0.002, 0.02 # Resolution in HKL space. You can also give 1 number for all dimensions

Having the config file and all the necessary images in the directory specified in the config, we can convert all the image pixels into the voxels in reciprocal space (binning procedure). To make the example work set the binoculars folder as the current working directory:

python binoculars process ./examples/dataset/config_tutorial.txt 820-839

, where the first path is the path to binoculars pythons script, the process means processing of the images, config_tutorial.txt is the path to the config file name and 820-839 are the scan numbers which will be processed (as appear in the spec file).

This results in creation of .hdf5 file, which is named as defined in the config. In this case, the file name is

./examples/dataset/maps/scan_820-839.hdf5

This file can be then used in graphical interface (gui.py) or for structure factor determination (fitaid.py).