This documentation page refers to a previous release of DIALS (2.2).
Click here to go to the corresponding page for the latest version of DIALS

dials.combine_experiments

Introduction

Utility script to combine multiple reflections and experiments files into one multi-experiment reflections and one experiments file. Experiments are matched to reflections in the order they are provided as input.

Reference models can be chosen from any of the input experiments files. These will replace all other models of that type in the output experiments file. This is useful, for example, for combining mutiple experiments that should differ only in their crystal models. No checks are made to ensure that a reference model is a good replacement model.

Although only one reference model of each type is allowed, more complex combinations of experiments can be created by repeat runs.

Examples:

dials.combine_experiments experiments_0.expt experiments_1.expt \
  reflections_0.refl reflections_1.refl \
  reference_from_experiment.beam=0 \
  reference_from_experiment.detector=0

Basic parameters

reference_from_experiment {
  beam = None
  scan = None
  crystal = None
  goniometer = None
  detector = None
  average_detector = False
  compare_models = True
  average_hierarchy_level = None
}
clustering {
  use = False
  dendrogram = False
  threshold = 1000
  max_clusters = None
  max_crystals = None
  exclude_single_crystal_clusters = True
}
output {
  experiments_filename = combined.expt
  reflections_filename = combined.refl
  n_subset = None
  n_subset_method = *random n_refl significance_filter
  n_refl_panel_list = None
}

Full parameter definitions

reference_from_experiment {
  beam = None
    .help = "Take beam model from this experiment to overwrite all other beam"
            "models in the combined experiments"
    .type = int(value_min=0, allow_none=True)
  scan = None
    .help = "Take scan model from this experiment to overwrite all other scan"
            "models in the combined experiments"
    .type = int(value_min=0, allow_none=True)
  crystal = None
    .help = "Take crystal model from this experiment to overwrite all other"
            "crystal models in the combined experiments"
    .type = int(value_min=0, allow_none=True)
  goniometer = None
    .help = "Take goniometer model from this experiment to overwrite all other"
            "goniometer models in the combined experiments"
    .type = int(value_min=0, allow_none=True)
  detector = None
    .help = "Take detector model from this experiment to overwrite all other"
            "detector models in the combined experiments"
    .type = int(value_min=0, allow_none=True)
  average_detector = False
    .help = "Create an average detector model from all the input detector"
            "models and use it as the reference. Not compatible with"
            "reference_from_experiment.detector"
    .type = bool
  compare_models = True
    .help = "Whether to compare a model with the reference model before"
            "replacing it. If the comparison falls outside the tolerance, the"
            "combination will not be allowed. Disable comparison to force"
            "overwriting of models with the reference"
    .type = bool
  average_hierarchy_level = None
    .help = "For hierarchical detectors, optionally provide a single level to"
            "do averaging at."
    .type = int(value_min=0, allow_none=True)
  tolerance
    .help = "Tolerances used to determine shared models"
    .expert_level = 2
  {
    beam {
      wavelength = 1e-6
        .help = "The wavelength tolerance"
        .type = float(value_min=0, allow_none=True)
      direction = 1e-6
        .help = "The direction tolerance"
        .type = float(value_min=0, allow_none=True)
      polarization_normal = 1e-6
        .help = "The polarization normal tolerance"
        .type = float(value_min=0, allow_none=True)
      polarization_fraction = 1e-6
        .help = "The polarization fraction tolerance"
        .type = float(value_min=0, allow_none=True)
    }
    detector {
      fast_axis = 1e-6
        .help = "The fast axis tolerance"
        .type = float(value_min=0, allow_none=True)
      slow_axis = 1e-6
        .help = "The slow axis tolerance"
        .type = float(value_min=0, allow_none=True)
      origin = 5e-2
        .help = "The origin tolerance"
        .type = float(value_min=0, allow_none=True)
    }
    goniometer {
      rotation_axis = 1e-6
        .help = "The rotation axis tolerance"
        .type = float(value_min=0, allow_none=True)
      fixed_rotation = 1e-6
        .help = "The fixed rotation tolerance"
        .type = float(value_min=0, allow_none=True)
      setting_rotation = 1e-6
        .help = "The setting rotation tolerance"
        .type = float(value_min=0, allow_none=True)
    }
    scan {
      oscillation = 0.01
        .help = "The oscillation tolerance for the scan"
        .type = float(value_min=0, allow_none=True)
    }
  }
}
clustering {
  use = False
    .help = "Separate experiments into subsets using the clustering toolkit."
            "One json per cluster will be saved."
    .type = bool
  dendrogram = False
    .help = "Display dendrogram of the clustering results. Should not be used"
            "with parallel processing."
    .type = bool
  threshold = 1000
    .help = "Threshold used in the dendrogram to separate into clusters."
    .type = int(allow_none=True)
  max_clusters = None
    .help = "Maximum number of clusters to save as jsons."
    .type = int(allow_none=True)
  max_crystals = None
    .help = "Maximum number of crystals to cluster."
    .type = int(allow_none=True)
  exclude_single_crystal_clusters = True
    .help = "Don't produce a 'cluster' containing only one crystal."
    .type = bool
}
output {
  experiments_filename = combined.expt
    .help = "The filename for combined experimental models"
    .type = str
  reflections_filename = combined.refl
    .help = "The filename for combined reflections"
    .type = str
  n_subset = None
    .help = "If not None, keep a subset of size n_subset when saving the"
            "combined experiments"
    .type = int(allow_none=True)
  n_subset_method = *random n_refl significance_filter
    .help = "Algorithm to be used for choosing the n_subset images/"
            "experiments for refinement.  n_refl chooses the set with the"
            "largest numbers of reflections listed in the pickle files"
            "significance filter used to select n_subset images based on"
            "I/sig(I) cutoff"
    .type = choice
  n_refl_panel_list = None
    .help = "If n_subset_method is n_refl, specify which panels to search on."
    .type = ints
  max_batch_size = None
    .help = "If not None, split the resultant combined set of experiments into"
            "seperate files, each at most max_batch_size number of"
            "experiments. Example, if there were 5500 experiments and"
            "max_batch_size is 1000, 6 experiment lists will be created, of"
            "sizes 917, 917, 917, 917, 916, 916"
    .type = int(allow_none=True)
    .expert_level = 2
  delete_shoeboxes = False
    .help = "If true, delete shoeboxes from reflection tables while comb-"
            "ining them to save on memory."
    .type = bool
    .expert_level = 2
  min_reflections_per_experiment = None
    .help = "If not None, throw out any experiment with fewer than this many"
            "reflections"
    .type = int(allow_none=True)
    .expert_level = 2
  significance_filter
    .expert_level = 1
  {
    enable = False
      .help = "If enabled, the significance filter will, for every experiment,"
              "find the highest resolution where the I/sigI remains above a"
              "certain point (controlled by isigi_cutoff)."
      .type = bool
    d_min = None
      .help = "High resolution cutoff for binning. If None, use the highest"
              "resolution reflection as d_min."
      .type = float(allow_none=True)
    n_bins = 20
      .help = "Number of bins to use when examining resolution falloff"
      .type = int(allow_none=True)
    isigi_cutoff = 1.0
      .help = "I/sigI cutoff. Reflections in and past the first bin that falls"
              "below this cutoff will not be retained"
      .type = float(allow_none=True)
  }
}