dials.merge

Introduction

This program merges scaled DIALS data to produce a merged MTZ file.

A truncation procedure is run as part of the merging process, to convert intensity estimates to positive structure-factor amplitudes (French & Wilson, 1978).

R-free flags are generated for the output MTZ. A number of options can be used to control this process, including the use of a reference dataset.

A HTML output report is generated with merging statistics tables and plots.

Examples:

dials.merge scaled.expt scaled.refl

dials.merge scaled.expt scaled.refl truncate=False

Basic parameters

assess_space_group = True
anomalous = True
truncate = True
french_wilson {
  implementation = *dials cctbx
  min_reflections = 200
  fallback_to_flat_prior = True
}
d_min = None
d_max = None
wavelength_tolerance = 1e-4
combine_partials = True
partiality_threshold = 0.4
best_unit_cell = None
n_residues = 200
merging {
  use_internal_variance = False
  n_bins = 20
  anomalous = False
}
r_free_flags {
  generate = True
  fraction = 0.05
  use_lattice_symmetry = True
  use_dataman_shells = False
  n_shells = 20
  extend = None
  relative_to_complete_set = False
  reference = None
}
output {
  log = dials.merge.log
  mtz = merged.mtz
  html = dials.merge.html
  json = None
  crystal_names = XTAL
  project_name = AUTOMATIC
  dataset_names = NATIVE
  additional_stats = False
}

Full parameter definitions

assess_space_group = True
  .help = "Option to assess space group by testing presence of axial"
          "reflections"
  .type = bool
anomalous = True
  .help = "Output anomalous as well as mean intensities."
  .type = bool
truncate = True
  .help = "Use the French & Wilson (1978) algorithm to correct for negative "
          "intensities when estimating amplitudes."
  .type = bool
french_wilson {
  implementation = *dials cctbx
    .help = "Choice of implementation of the French & Wilson algorithm"
    .type = choice
  min_reflections = 200
    .help = "Only perform French & Wilson procedure if at least this  number"
            "of reflections."
    .type = int(value_min=1, allow_none=True)
  fallback_to_flat_prior = True
    .help = "If insufficient number of reflections to perform the  French &"
            "Wilson procedure, fallback to assumption of a  flat prior, i.e.: "
            "  |F| = sqrt((Io+sqrt(Io**2 +2sigma**2))/2.0)"
    .type = bool
}
d_min = None
  .help = "High resolution limit to apply to the data."
  .type = float(allow_none=True)
d_max = None
  .help = "Low resolution limit to apply to the data."
  .type = float(allow_none=True)
wavelength_tolerance = 1e-4
  .help = "Absolute tolerance for determining wavelength grouping for merging."
  .type = float(value_min=0, allow_none=True)
combine_partials = True
  .help = "Combine partials that have the same partial id into one
       "
          "reflection, with an updated partiality given by the sum of the
    "
          "   individual partialities."
  .type = bool
partiality_threshold = 0.4
  .help = "All reflections with partiality values above the partiality
       "
          "threshold will be retained. This is done after any combination of
 "
          "      partials if applicable."
  .type = float(allow_none=True)
best_unit_cell = None
  .help = "Best unit cell value, to use when performing resolution cutting,"
          "and as the overall unit cell in the merged mtz. If undefined, the"
          "median cell will be used."
  .type = unit_cell
n_residues = 200
  .help = "Number of residues to use in Wilson scaling"
  .type = int(allow_none=True)
merging {
  use_internal_variance = False
    .type = bool
  n_bins = 20
    .type = int(value_min=5, allow_none=True)
  anomalous = False
    .help = "Option to control whether reported merging stats are anomalous."
    .type = bool
}
r_free_flags {
  generate = True
    .short_caption = "Generate R-free flags if not already present"
    .type = bool
    .style = "bold noauto"
  fraction = 0.05
    .short_caption = "Fraction of reflections in test set"
    .type = float(allow_none=True)
    .expert_level = 0
  max_free = 2000
    .short_caption = "Maximum number of reflections in test set"
    .type = int(allow_none=True)
    .expert_level = 2
  lattice_symmetry_max_delta = 5
    .type = float(allow_none=True)
    .expert_level = 2
  use_lattice_symmetry = True
    .short_caption = "Use lattice symmetry to generate test set"
    .type = bool
    .expert_level = 0
  use_dataman_shells = False
    .help = "Used to avoid biasing of the test set by certain types of"
            "non-crystallographic symmetry."
    .short_caption = "Assign test set in thin resolution shells"
    .type = bool
  n_shells = 20
    .short_caption = "Number of resolution shells"
    .type = int(allow_none=True)
  extend = None
    .short_caption = "Extend existing R-free array(s) to full resolution range"
    .type = bool
    .style = "bold noauto"
  old_test_flag_value = None
    .help = "Overrides automatic guess of test flag value from existing set."
            "This will usually be 1 for reflection files generated by Phenix,"
            "and 0 for reflection files from CCP4. Do not change unless you're"
            "sure you know what flag to use!"
    .short_caption = "Original test flag value"
    .type = int(allow_none=True)
    .expert_level = 2
  d_eps = 0.0001
    .short_caption = "Resolution buffer"
    .type = float(allow_none=True)
    .expert_level = 2
  d_max = None
    .short_caption = "The maximum resolution to which to generate R-free flags"
    .type = float(allow_none=True)
    .expert_level = 2
  d_min = None
    .short_caption = "The minimum resolution to which to generate R-free flags"
    .type = float(allow_none=True)
    .expert_level = 2
  relative_to_complete_set = False
    .short_caption = "Generate R-free flags relative to complete set"
    .type = bool
  reference = None
    .type = path
}
output {
  log = dials.merge.log
    .type = str
  mtz = merged.mtz
    .help = "Filename to use for mtz output."
    .type = str
  html = dials.merge.html
    .help = "Filename for html output report."
    .type = str
  json = None
    .help = "Filename to output data from html report in json format."
    .type = str
  crystal_names = XTAL
    .help = "Crystal name to be used in MTZ file output (multiple names
      "
            "     allowed for MAD datasets)"
    .type = strings
  project_name = AUTOMATIC
    .help = "Project name to be used in MTZ file output"
    .type = str
  dataset_names = NATIVE
    .help = "Dataset name to be used in MTZ file output (multiple names
      "
            "     allowed for MAD datasets)"
    .type = strings
  additional_stats = False
    .help = "Calculate and report the R-split statistic. Also saves the"
            "half-dataset merged arrays to the MTZ output file."
    .type = bool
}
exclude_images = None
  .help = "Input in the format exp:start:end Exclude a range of images (start,"
          "stop) from the dataset with experiment identifier exp  (inclusive"
          "of frames start, stop). Multiple ranges can be given in one go,"
          "e.g. exclude_images=0:150:200,1:200:250 exclude_images='0:150:200"
          "1:200:250'"
  .short_caption = "Exclude images"
  .type = strings
  .multiple = True
  .expert_level = 1
exclude_images_multiple = None
  .help = "Exclude this single image and each multiple of this image number in"
          "each experiment. This is provided as a convenient shorthand to"
          "specify image exclusions for cRED data, where the scan of"
          "diffraction images is interrupted at regular intervals by a crystal"
          "positioning image (typically every 20th image)."
  .type = int(value_min=2, allow_none=True)
  .expert_level = 2