Cppxfel Reference Manual
Here is a list of commands used in cppxfel and their effects on initial orientation matrix refinement or post-refinement.
List of commands
General
VERBOSITY_LEVEL x Integer x – number representing quantity of information sent to the standard output. Possible values: 0 Normal (default) 1 Detailed 2 Debug
MAX_THREADS x Integer x – number of threads to spread calculations over, but is preferentially overridden by setting the environment variable NSLOTS.
MATRIX_LIST_VERSION x Double x – default 2.0. It is unlikely that you should ever need to use v1.0.
INITIAL_MTZ String x - MTZ used as a starting reference data set in place of an initial merge. Useful for small numbers of images or to break the indexing ambiguity. No default.
IMAGE_LIMIT Integer x - Only attempt to load x images from the list of matrices specified in ORIENTATION_MATRIX_LIST. Default 0 (no limit).
NEW_MATRIX_LIST String x - Filename for the set of matrix lists (refine-x, integrate-x and merge-x) which may be produced from a round of integration or post-refinement. No default.
SPACE_GROUP Int x – space group number for crystal according to the International Tables. No default.
Post-refinement
MINIMUM_CYCLES x Integer x – minimum number of cycles of post-refinement to exceed before finishing (but may perform more cycles if not converged). Default 6.
MAXIMUM_CYCLES x Integer x – maximum number of cycles of post-refinement to execute even if not converged. Default 0 (no maximum).
STOP_REFINEMENT x Boolean x – if set to OFF, post-refinement will continue indefinitely.
MINIMIZATION_METHOD x Integer x Possible values: 0 Step search algorithm 1 Nelder-Mead algorithm (default)
NELDER_MEAD_CYCLES x Integer x – number of Nelder-Mead cycles to perform before finishing post-refinement of a single image per macrocycle. Default 50.
MEDIAN_WAVELENGTH Boolean x – calculate starting X-ray beam wavelength for post-refinement of an image using the median excitation wavelength of all strong reflections. Otherwise a mean average is used. Default OFF.
WAVELENGTH_RANGE x y Double x, y – start and end for range of wavelengths to consider when calculating the starting X-ray beam wavelength. Can ignore extreme outliers. Default 0 0 (not applied).
REFINEMENT_INTENSITY_THRESHOLD x Double x - Intensity threshold x in absolute terms to define ‘strong’ reflections in initial wavelength determination. Default 200.
ALLOW_TRUST x Boolean x - If an image correlates well with the reference data set, fix the indexing ambiguity chosen in the future to reduce computation time. Default ON
TRUST_INDEXING_SOLUTION x Boolean x - Do not attempt to check alternative indexing solutions if set to ON. Good if the indexing ambiguity has been resolved by some other means. Default OFF.
PARTIALITY_CUTOFF x Double x - If reflections are calculated with a cutoff below a certain partiality they are not included in target function calculation or merging. Default 0.2.
SCALING_STRATEGY Int x – number representing the strategy for scaling individual crystals on each merging cycle. Default 1. Possible values: 0 Average intensity set to 1000 1 Scale to match the reference data set 3 Minimise R merge as target function
MINIMUM_REFLECTION_CUTOFF Int x – if a crystal refines to have fewer than x reflections then it is not included in the final merge. Default 100.
DEFAULT_TARGET_FUNCTION Integer x - Target function used for post-refinement minimisation. Default 0. Possible values: 0 R factor with reference data set 1 Correlation with reference data set
TARGET_FUNCTIONS x, y, z… Integers x, y, z… - Further target functions to occur during a single macrocycle after the default target function. For each additional function the calculation will be reperformed on the same image. Default: no extra target functions.
RLP_MODEL x Integer x – model for reciprocal lattice point Possible values: 0 Uniform sphere 1 Gaussian decay from the centre
CORRELATION_THRESHOLD x Double x – threshold for merging images; image which correlate less than x with reference will not be included in refinement. Also see INITIAL_CORRELATION_THRESHOLD. Default 0.9.
INITIAL_CORRELATION_THRESHOLD x Double x – for a certain number of rounds of refinement determined by THRESHOLD_SWAP, a lower correlation threshold of x will be used. Also see CORRELATION_THRESHOLD. Default 0.8.
THRESHOLD_SWAP x Integer x – this specifies the number of rounds of refinement before swapping from INITIAL_CORRELATION_THRESHOLD to CORRELATION_THRESHOLD. Default 2.
PARTIALITY_CORRELATION_THRESHOLD x Double x – threshold for merging images, image whose partialities correlate less than x with the proportion of merged intensities of the reference will not be included in refinement. Default 0.
R_FACTOR_THRESHOLD x Double x – in addition to correlation threshold, images with an R factor of more than x with the reference data set are rejected during merging. Default is 0 (not in use).
MAX_RESOLUTION_ALL x Double x - do not use reflections in post-refinement beyond x Å resolution (but these will be included in the merge). Default 1.4.
MIN_REFINED_RESOLUTION x Double x – do not refine using reflections below x Å resolution (but these will be included in the merge). Default 0 (no minimum).
OUTLIER_REJECTION x Boolean x – master switch for rejection of outliers based on standard deviations from mean. Default ON.
OUTLIER_REJECTION_SIGMA x Double x – number of standard deviations away from the mean intensity of a merged reflection beyond which an observation is rejected during merging. Default 1.8.
CORRELATION_REJECTION x Boolean x – rejection on a per image basis if individual reflections correlate poorly with the image. Good for unindexed multiple lattices or bad-pixel detectors. Default ON.
POLARISATION_CORRECTION x Boolean x – if switched on, polarisation factor is applied. Default OFF.
POLARISATION_FACTOR x Double x – 0 for fully horizontal polarisation, 1 for fully vertical polarisation.
REFINE_B_FACTOR x Boolean x - Only works when step search is enabled; a B factor is refined per image against the reference data set.
PARTIALITY_SLICES x Integer x - Number of slices to make for individual reflections when calculating partiality higher than the resolution set by CAREFUL_RESOLUTION. Fewer slices can be made for smaller rlp sizes, increasing computation speed but running the risk of overfitting. Default 8, may need to be increased for high rlp size/mosaicity systems.
MAX_SLICES x Integer x – Number of slices to make for reflections with a resolution lower than CAREFUL_RESOLUTION. May need to be increased for high rlp size/mosaicity systems. Default 100.
CAREFUL_RESOLUTION x Double x – resolution at which reflections switch from using MAX_SLICES to PARTIALITY_SLICES for partiality calculation. Default 8 Å.
REPLACE_REFERENCE If ON, reference is updated on each merging cycle (recommended). Otherwise reference is not replaced. Only generally used to measure degree of overfitting from refining a small number of images. Default ON.
INITIAL_WAVELENGTH Does not need to be set, but if set, wavelength is always set to this value and not calculated per image. Possibly useful for very low resolution structures where individual spots deviate far from the true wavelength. Default 0 (not set).
INITIAL_BANDWIDTH Initial bandwidth standard deviation for beam model. Multiply this by the wavelength to get the standard deviation in Å. Default 0.0013 (calibrated for a SASE pulse).
INITIAL_MOSAICITY Initial mosaicity for rlp size determining how much the rlp increases with resolution in degrees. Defined according to Rossmann et al 1979 in degrees. Default 0º.
INITIAL_EXPONENT Initial exponent for super-Gaussian distribution of beam wavelengths. Default 1.5.
INITIAL_RLP_SIZE Size of theoretical Miller index (0, 0, 0) in reciprocal space distance (Å-1). Default 0.0001 Å-1.
STEP_SIZE_WAVELENGTH x Double x - Initial step size or initial displacement for step search or Nelder-Mead algorithm respectively for wavelength. Default 0.005 Å.
STEP_SIZE_BANDWIDTH x Double x - Initial step size or initial displacement for step search or Nelder-Mead algorithm respectively for bandwidth. Default 0.0003.
STEP_SIZE_MOSAICITY x Double x - Initial step size or initial displacement for step search or Nelder-Mead algorithm respectively for mosaicity. Default 0.001.
STEP_SIZE_EXPONENT x Double x - Initial step size or initial displacement for step search or Nelder-Mead algorithm respectively for the super-Gaussian exponent. Default 0.1.
STEP_SIZE_ORIENTATION x Double x - Initial step size or initial displacement for step search or Nelder-Mead algorithm respectively for horizontal/vertical rotation displacement (degrees). Default 0.06º.
STEP_SIZE_RLP_SIZE x Double x - Initial step size or initial displacement for step search or Nelder-Mead algorithm respectively for base rlp size. Default 2 × 10-5 Å-1.
STEP_SIZE_UNIT_CELL_A x Double x - Initial step size or initial displacement for step search or Nelder-Mead algorithm respectively for unit cell dimension A. Default 0.2 Å.
STEP_SIZE_UNIT_CELL_B x Double x - Initial step size or initial displacement for step search or Nelder-Mead algorithm respectively for unit cell dimension B. Default 0.2 Å.
STEP_SIZE_UNIT_CELL_C x Double x - Initial step size or initial displacement for step search or Nelder-Mead algorithm respectively for unit cell dimension C. Default 0.2 Å.
TOLERANCE_WAVELENGTH x Double x – Step size search algorithm only – when step search size falls below this tolerance, stop parameter refinement; wavelength. Default 1 × 10-5 Å.
TOLERANCE_BANDWIDTH x Double x – Step size search algorithm only – when step search size falls below this tolerance, stop parameter refinement; bandwidth. Default 1 × 10-5.
TOLERANCE_MOSAICITY x Double x – Step size search algorithm only – when step search size falls below this tolerance, stop parameter refinement; mosaicity. Default 1 × 10-3º.
TOLERANCE_EXPONENT x Double x – Step size search algorithm only – when step search size falls below this tolerance, stop parameter refinement; super-Gaussian exponent. Default 5 × 10-3.
TOLERANCE_ORIENTATION x Double x – Step size search algorithm only – when step search size falls below this tolerance, stop parameter refinement; horizontal/vertical orientation displacement (degrees). Default 1 × 10-4º.
TOLERANCE_RLP_SIZE x Double x – Step size search algorithm only – when step search size falls below this tolerance, stop parameter refinement; base rlp size. Default 1 × 10-5 Å-1.
OPTIMISING_WAVELENGTH x Boolean x – sets whether wavelength is a refined parameter. Default ON.
OPTIMISING_BANDWIDTH x Boolean x – sets whether bandwidth is a refined parameter. Default OFF.
OPTIMISING_MOSAICITY x Boolean x – sets whether mosaicity is a refined parameter. Default OFF.
OPTIMISING_EXPONENT x Boolean x – sets whether exponent is a refined parameter. Default OFF.
OPTIMISING_ORIENTATION x Boolean x – sets whether horizontal/vertical orientation displacement is a refined parameter. Default ON
OPTIMISING_RLP_SIZE x Boolean x – sets whether rlp size is a refined parameter. Default ON.
OPTIMISING_UNIT_CELL_A x Boolean x – sets whether unit cell dimension A is a refined parameter. Default OFF, should be turned on for certain space groups.
OPTIMISING_UNIT_CELL_B x Boolean x – sets whether unit cell dimension B is a refined parameter. Default OFF, should be turned on for certain space groups.
OPTIMISING_UNIT_CELL_C x Boolean x – sets whether unit cell dimension C is a refined parameter. Default OFF, should be turned on for certain space groups.
ORIENTATION_MATRIX_LIST x String x - path to list of orientation matrices generated using cppxfel.input_gen. No default.
Integration
INTEGRATION_WAVELENGTH Double x – wavelength of X-ray beam in Å. No default.
DETECTOR_DISTANCE Double x – detector distance from crystal in mm. No default.
BEAM_CENTRE Double x, y – coordinate position at which the beam hits the image in pixels. Default 882.0, 882.0 px to match CSPAD detector.
MM_PER_PIXEL Double x – height/width of a pixel on the detector in mm. Default 0.11 mm to match CSPAD detector.
DETECTOR_SIZE Int x, y – width and height of the detector. Default 1765, 1765 to match CSPAD detector.
OVER_PRED_BANDWIDTH Double x – integration requires an over-estimated bandwidth to ‘catch’ all the reflections and more. This represents the % bandwidth to either side of the mean wavelength which should be used. Default 3%.
OVER_PRED_RLP_SIZE Double x – reciprocal lattice point radius in Å-1 at the Miller index position (0, 0, 0) (i.e. without consideration of mosaicity). Default 2 × 10-4 Å-1.
REFINE_ORIENTATIONS Boolean x – if set to ON, using the INTEGRATE command will also refine orientation matrices according to the protocol in Ginn et al Nat Comms 2015. Default ON.
INDEXING_ORIENTATION_TOLERANCE Double x – Initial orientation matrix refinement will finish when the step search angle decreases below x degrees. Default 1 × 10-3º.
INTENSITY_THRESHOLD Double x - Absolute (counts) or signal-to-noise (I/sigI) threshold at which a spot is considered to be a strong spot for initial orientation matrix refinement. Default 12 (assuming a detector gain of 1.0) and also dependent on ABSOLUTE_INTENSITY.
ABSOLUTE_INTENSITY Boolean x – if set to ON, intensity threshold is measured in counts, whereas if set to OFF this is a I/sigI threshold for spots to be considered strong spots for initial orientation matrix refinement. Default OFF.
METROLOGY_SEARCH_SIZE Int x – metrology search size can be set to an integer number of pixels from which the predicted spot position may deviate in order to find the highest pixel value. Integration will be performed centred on this highest pixel value. Default 0 but often needs changing.
SHOEBOX_FOREGROUND_PADDING Int x – for a simple shoebox centred on a coordinate, this represents the extra number of pixels in both axes which will be integrated as part of the signal foreground. This overrides the background and neither flags. Default 1.
SHOEBOX_NEITHER_PADDING Int x - – for a simple shoebox centred on a coordinate, this represents the extra number of pixels from the centre in both axes for which pixels will not be considered as part of foreground or background signal. This overrides the background flags. Default 2.
SHOEBOX_BACKGROUND_PADDING Int x - – for a simple shoebox centred on a coordinate, this represents the extra number of pixels from the centre in both axes for which pixels will be used to estimate the background. Default 3.
COMPLEX_SHOEBOX Boolean x – if this is set, a complex shoebox will be generated to attempt to take into account the shape of the spot at high resolution, which may be distorted by the wavelength spread of the beam.
MAX_INTEGRATED_RESOLUTION Double x – if set, integration will only occur up to the specified resolution. Default 1.4 Å.
UNIT_CELL Double a, b, c, alpha, beta, gamma – unit cell parameters for the crystal of interest.
FIX_UNIT_CELL Boolean x – if set to ON, the unit cell found in the ORIENTATION_MATRIX_LIST file will have its unit cell reset to the values specified in UNIT_CELL, preserving orientation, before any further integration or post-refinement.
INITIAL_ORIENTATION_STEP Double x – for initial orientation matrix refinement, this is the angle in degrees that the algorithm steps in order to search for a new minimum. Step search algorithm is used. Default 1.0º.
ORIENTATION_SCORE Int x – target function during initial orientation matrix refinement. Default 0 (weighted combination of total reflections and standard deviation). Values of interest: 0 weighted combination of total reflections within bandwidth range and standard deviation 1 total reflections within bandwidth range only
ORIENTATION_CORRECTION Double x,y – sometimes the indexing solutions from DIALS are corrected by a systematic error in the horizontal and vertical rotations due to a component of the experiment which is modelled in DIALS but not by cppxfel. If this systematic shift is known, it can be supplied in degrees (x in the horizontal axis and y in the vertical axis). These values may be deduced from a table of corrections produced at the end of an INTEGRATE command. Default 0,0.
IMAGE_MASKED_VALUE Int x – if there is a pixel value used as a masking value in the images provided, this can be set using this command. If IMAGE_MASKED_VALUE is not set, the default is not to mask any pixel value.
SPHERE_THICKNESS Double x - This is the thickness in Å-1 around the mean Ewald radius to consider integrating. The subset of reflections which are chosen for integration are then determined by OVER_PRED_RLP_SIZE, so SPHERE_THICKNESS is a prior scanning step. Default 0.02 Å-1. Increasing this will improve spot prediction at low resolution but will reduce the overall speed of the program.
PIXEL_COUNT_CUTOFF Int x - If, during integration, a pixel exceeds the value x, this reflection is rejected. Can be used to protect against non-linear gain of the detector at high pixel counts. Default is not to use.
REFINE_UNIT_CELL_A Boolean x – if set to ON, this unit cell a dimension is refined in either integration or post-refinement, using the step size specified by STEP_UNIT_CELL_A. Default OFF.
REFINE_UNIT_CELL_B Boolean x – if set to ON, this unit cell b dimension is refined in either initial orientation matrix refinement or post-refinement, using the step size specified by STEP_UNIT_CELL_B. Default OFF.
REFINE_UNIT_CELL_C Boolean x – if set to ON, this unit cell c dimension is refined in either initial orientation matrix refinement or post-refinement, using the step size specified by STEP_UNIT_CELL_C. Default OFF.
STEP_UNIT_CELL_A Double x – this determines the step size used during either initial orientation matrix refinement or post-refinement for unit cell A. Default 0.2 Å.
STEP_UNIT_CELL_B Double x – this determines the step size used during either initial orientation matrix refinement or post-refinement for unit cell B. Default 0.2 Å.
STEP_UNIT_CELL_C Double x – this determines the step size used during either initial orientation matrix refinement or post-refinement for unit cell C. Default 0.2 Å.
FROM_DIALS Boolean x – should be set to ON if matrices were calculated by DIALS. Unlikely to be any other value. Default ON.
DO_NOT_REJECT_REFLECTIONS Boolean x – usually, if there are multiple lattices on the same image then overlapping shoeboxes lead to reflections being rejected. This also applies to overlapping reflections from the same lattice, if the over-prediction is too wide. This may not always be a desired feature, so setting this value to OFF will disable it. Default ON.
REFINE_IN_PLANE_OF_DETECTOR Boolean x – in some cases, the rotation of the orientation matrix around the beam axis is not exact. Setting this value to ON will refine the orientation matrix around this axis. Default OFF.
FIT_BACKGROUND_AS_PLANE Boolean x – to fit the background pixels as a plane rather than simple summation, switch this to ON. Individual pixels may also be rejected as outliers. Default OFF.
PANEL_LIST String x – list of panels generated by cppxfel.input_gen or modified by REFINE_METROLOGY command. Individual panels in this file are specified by the keyword PANEL followed by the upper left x,y and bottom right x,y integer coordinates separated by single spaces. Required for initial orientation matrix refinement but not post-refinement. No default.
ROUGH_CALCULATION - v1.1 Bool x - if switched to ON, some recalculations are skipped during integration, which vastly increases the speed of integration. Comes with a mild warning that the integration solutions may be compromised - in practice this appears to be fine. Default OFF.
Merging
RECALCULATE_SIGMA Boolean x - To be used on a final merge of MTZ files: an estimate of the standard deviation will be made from the distribution of the observation intensities for each reflection. Default OFF.
MERGE_ANOMALOUS Boolean x – to be used on a final merge of MTZ files, this flag will merge anomalous data sets rather than straight intensities. Anomalous data will be written to anomalous_diff.mtz. Default OFF.