Configuration parameters for experimental data

This page describes configuration file parameters which may be useful when processing experimental data. Some of the options are also used in the simulation workflow, but this page may be more useful if you are working with simulated data.

[parameters]

Option	Description
detd	detector distance in millimeter
lambda	photon wavelength in Angstroms
detsize	linear size of detector in pixels (integer or 2 whitespace-separated integers). Two integers refer to a rectangular detector (width x height)
pixsize	pixel size in millimeters
stoprad	beamstop radius in pixels (float) (see image above)
polarization	correction due to incident beam polarization, which can be set as 'x', 'y', or 'none'
ewald_rad	Radius of curvature of the Ewald sphere in voxels. For a monochromatic scattering experiment (as is assumed throughout this analysis), detector pixels lie on the surface of the Ewald sphere in reciprocal space. However, one needs to still define where those pixels will be in the 3D intensity grid which will be reconstructed. This parameter defines that scaling. The reciprocal space point sampled by a voxel one voxel away from q=0 is q = 1/(lambda*ewald_rad) The default value is detd/pixsize.

[make_detector]

Option	Description
center	Coordinates of q=0 pixel (integer of 2 whitespace-separated integers). Two integers refer to different coordinates in the horizontal and vertical direction respectively. By default the center of the detector is used. The coordinates are specified in the C-convention (array starts with 0).
in_mask_file	Path to binary file containing mask information as 8 bit unsigned integers. The mask values are described here (0=good, 1=merge-only, 2=bad). There should be one value for each pixel in the detector.
out_detector_file	The output detector geometry file to be generated that corresponds to the values in [parameters]. For more on this output format, go to this page.

[emc]

Option	Description
in_photons_file	The data frames used for the EMC reconstruction. Various utilities are provided in the /utils/convert/ folder to convert standard facility formats to the sparse EMC format described here.
in_photons_list	Text file containing relative paths to multiple EMC files. A common use case for this would be the data was collected in runs and one does not want to combine everything into a giant file. The paths should be specified one per line. Note: in_photons_file cannot be used if a list file is specified (obviously!).
in_detector_file	The detector geometry file used for the EMC reconstruction. It should be set as in_detector_file = make_detector:::out_detector_file to use the detector geometry file from make_detector.py. The user may need to generate their own detector geometry file with the format described here or to use a conversion utility provided in /utils/convert/.
in_detector_list	Dragonfly now supports multiple detector geometries! Like in_photons_list, this file contains relative paths to multiple detector files. It must be paired with the in_photons_list option and must have the same number of lines as that file indicating the one-to-one correspondence between a photons file and a detector file. Note: in_detector_file cannot be used if a list file is specified (obviously!).
num_div	This integer determines the refinement of the quasi-uniform rotation sampling. The number of rotations is given by 10*(5*num_div^3 + num_div). More information can be found in the original EMC paper.
in_quat_file	Path to file containing quaternions if you would like to use a non-standard sampling. The format of the file should be identical to that created by the /utils/make_quaternion utility (one line with number of orientations, followed by five numbers per orientation). One use case of this could be if one wants to apply a known non-uniform prior weighting to different orientations for experimental reasons (eg. flow alignment). Note: num_div cannot be used if a quaternion file is provided (obviously!).
output_folder	The destination of output files of the EMC reconstruction.
log_file	The log file monitoring the progress of the EMC reconstruction.
need_scaling	The option to update the scaling of each data frame caused by fluence fluctuation, etc, 0 for off and 1 for on.
start_model_file	Initial guess 3D intensity model. Binary file with same format and size as output files (binary cube of double precision floats). If not provided, the initial guess is random white noise.
merge_photons_file	Path to data file containing frames to be merged in the Compress step if different from in_photons_file. This can be useful if there is excess background which can be filtered out for orientation purposes but one would still be interested in merging (eg. for crystallographic data). This file must have the same number of frames as in_photons_file and should correspond to the same detector file.
merge_photons_list	List of merge photons files.
alpha	Relaxation parameter which slows down convergence. In each iteration, the 3D volumes are updated according to model_new = alpha * model_old + (1-alpha) * model_new By default, alpha = 0.0. A larger value keeps part of the previous iteration in the current guess.
beta	Deterministic annealing parameter which flattens the probability distribution over orientations. for a given frame, the likelihood over orientations is raised to the power of beta before normalization. We find this aids convergence for data sets with high signal per frame where beta < 1. makes the distribution less sharp in the first few iterations when the iterate is far from the solution. By default, beta = 1.0.
beta_schedule	Deterministic annealing schedule for the beta parameter with iteration (pair of whitespace-separated numbers). The first number is how much to increase beta by multiplicatively and the second is how often to do this multiplication. If the two numbers are beta_jump and beta_period, beta = beta * beta_jump every beta_period iterations.
sym_icosahedral	Impose icosahedral symmetry (1 for on and 0 for off, off by default). This option does two things, reduces the size of the rotation group to the asymmetric unit of the icosahedral group and icosahedrally symmetrizes the 3D intensity volume every iteration.
scale_file	Initial guess for scale factors, text file with one floating point number per line for every frame. Only relevant if need_scaling=1. By default, the initial guess for the scale factors is considered to be uniform. If there is a better initial guess, it can be provided with this file.

[classifier]

This section contains options used by the pattern classifier. The properties of the options are identical to those in the [emc] section above.

Option	Description
in_photons_file	Data file in the EMC format
in_photons_list	List of data files
in_detector_file	Detector geometry file
in_detector_list	List of detector files
output_folder	Relative path to folder where various temporary and permanent output is stored