dials.index

Introduction

This program attempts to perform autoindexing on strong spots output by the program dials.find_spots. The program is called with a “datablock.json” file (as generated by dials.import) and a “strong.pickle” file (as generated by dials.find_spots). If one or more lattices are identified given the input list of strong spots, then the crystal orientation and experimental geometry are refined to minimise the differences between the observed and predicted spot centroids. The program will output an “experiments.json” file which is similar to the input “datablock.json” file, but with the addition of the crystal model(s), and an “indexed.pickle” file which is similar to the input “strong.pickle” file, but with the addition of miller indices and predicted spot centroids.

dials.index provides both one-dimensional and three-dimensional fast Fourier transform (FFT) based methods. These can be chosen by setting the parameters indexing.method=fft1d or indexing.method=fft3d. By default the program searches for a primitive lattice, and then proceeds with refinement in space group P1. If the unit_cell and space_group parameters are set, then the program will only accept solutions which are consistent with these parameters. Space group constraints will be enforced in refinement as appropriate.

Examples:

dials.index datablock.json strong.pickle

dials.index datablock.json strong.pickle unit_cell=37,79,79,90,90,90 space_group=P43212

dials.index datablock.json strong.pickle indexing.method=fft1d

Basic parameters

indexing {
  nproc = 1
  fft3d {
    reciprocal_space_grid {
      d_min = Auto
    }
  }
  scan_range = None
  known_symmetry {
    space_group = None
    unit_cell = None
  }
  index_assignment {
    simple {
      hkl_tolerance = 0.3
    }
  }
  check_misindexing {
    grid_search_scope = 0
  }
  refinement_protocol {
    n_macro_cycles = Auto
    d_min_step = Auto
    d_min_start = None
    d_min_final = None
    verbosity = 1
  }
  method = *fft3d fft1d real_space_grid_search
  stills {
    ewald_proximity_resolution_cutoff = 2.0
    refine_all_candidates = True
    rmsd_min_px = 2
    ewald_proximal_volume_max = 0.0025
    isoforms {
      name = None
      cell = None
      lookup_symbol = None
      rmsd_target_mm = None
      beam_restraint = None
    }
  }
}
refinement {
  verbosity = 0
  parameterisation {
    auto_reduction {
      min_nref_per_parameter = 5
      action = *fail fix remove
    }
    scan_varying = False
    beam {
      fix = all *in_spindle_plane out_spindle_plane *wavelength
    }
    crystal {
      fix = all cell orientation
    }
    detector {
      fix = all position orientation
    }
    goniometer {
      fix = *all in_beam_plane out_beam_plane
    }
  }
  reflections {
    reflections_per_degree = 100
    minimum_sample_size = 1000
    maximum_sample_size = None
    outlier {
      algorithm = null *auto mcd tukey sauter_poon
      minimum_number_of_reflections = 20
      separate_experiments = True
      separate_panels = Auto
      separate_blocks = True
      block_width = Auto
    }
  }
}
output {
  experiments = experiments.json
  split_experiments = False
  reflections = indexed.pickle
  unindexed_reflections = None
  log = dials.index.log
  debug_log = dials.index.debug.log
}
verbosity = 1

Full parameter definitions

indexing {
  nproc = 1
    .help = "The number of processes to use."
    .type = int(value_min=1, allow_none=True)
  mm_search_scope = 4.0
    .help = "Global radius of origin offset search."
    .type = float(value_min=0, allow_none=True)
    .expert_level = 1
  wide_search_binning = 2
    .help = "Modify the coarseness of the wide grid search for the beam"
            "centre."
    .type = float(value_min=0, allow_none=True)
    .expert_level = 1
  min_cell_volume = 25
    .help = "Minimum unit cell volume (in Angstrom^3)."
    .type = float(value_min=0, allow_none=True)
    .expert_level = 1
  min_cell = 3
    .help = "Minimum length of candidate unit cell basis vectors (in"
            "Angstrom)."
    .type = float(value_min=0, allow_none=True)
    .expert_level = 1
  max_cell = Auto
    .help = "Maximum length of candidate unit cell basis vectors (in"
            "Angstrom)."
    .type = float(value_min=0, allow_none=True)
    .expert_level = 1
  max_cell_estimation
    .expert_level = 1
  {
    filter_ice = True
      .help = "Filter out reflections at typical ice ring resolutions before"
              "max_cell estimation."
      .type = bool
    filter_overlaps = True
      .help = "Filter out reflections with overlapping bounding boxes before"
              "max_cell estimation."
      .type = bool
    overlaps_border = 0
      .help = "Optionally add a border around the bounding boxes before"
              "finding overlaps."
      .type = int(value_min=0, allow_none=True)
    multiplier = 1.3
      .help = "Multiply the estimated maximum basis vector length by this"
              "value."
      .type = float(value_min=0, allow_none=True)
      .expert_level = 2
    step_size = 45
      .help = "Step size, in degrees, of the blocks used to peform the"
              "max_cell  estimation."
      .type = float(value_min=0, allow_none=True)
      .expert_level = 2
    nearest_neighbor_percentile = None
      .help = "Percentile of NN histogram to use for max cell determination."
      .type = float(value_min=0, value_max=1, allow_none=True)
      .expert_level = 2
    histogram_binning = linear *log
      .help = "Choose between linear or logarithmic bins for nearest neighbour"
              "histogram analysis."
      .type = choice
    nn_per_bin = 5
      .help = "Target number of nearest neighbours per histogram bin."
      .type = int(value_min=1, allow_none=True)
    max_height_fraction = 0.25
      .type = float(value_min=0, value_max=1, allow_none=True)
      .expert_level = 2
  }
  fft3d {
    peak_search = *flood_fill clean
      .type = choice
      .expert_level = 2
    peak_volume_cutoff = 0.15
      .type = float(allow_none=True)
      .expert_level = 2
    reciprocal_space_grid {
      n_points = 256
        .type = int(value_min=0, allow_none=True)
        .expert_level = 1
      d_min = Auto
        .help = "The high resolution limit in Angstrom for spots to include in"
                " the initial indexing."
        .type = float(value_min=0, allow_none=True)
    }
  }
  sigma_phi_deg = None
    .help = "Override the phi sigmas for refinement. Mainly intended for"
            "single-shot rotation images where the phi sigma is almost"
            "certainly incorrect."
    .type = float(value_min=0, allow_none=True)
    .expert_level = 2
  b_iso = Auto
    .type = float(value_min=0, allow_none=True)
    .expert_level = 2
  rmsd_cutoff = 15
    .type = float(value_min=0, allow_none=True)
    .expert_level = 1
  scan_range = None
    .help = "The range of images to use in indexing. Number of arguments must"
            "be a factor of two. Specifying  0 0\" will use all images\" by"
            "default. The given range follows C conventions (e.g. j0 <= j <"
            "j1)."
    .type = ints(size=2)
    .multiple = True
  known_symmetry {
    space_group = None
      .help = "Target space group for indexing."
      .type = space_group
    unit_cell = None
      .help = "Target unit cell for indexing."
      .type = unit_cell
    relative_length_tolerance = 0.1
      .help = "Relative tolerance for unit cell lengths in unit cell"
              "comparision."
      .type = float(allow_none=True)
      .expert_level = 1
    absolute_angle_tolerance = 5
      .help = "Angular tolerance (in degrees) in unit cell comparison."
      .type = float(allow_none=True)
      .expert_level = 1
    max_delta = 5
      .help = "Maximum allowed Le Page delta used in searching for basis"
              "vector combinations that are consistent with the given"
              "symmetry."
      .type = float(value_min=0, allow_none=True)
      .expert_level = 1
  }
  basis_vector_combinations
    .expert_level = 1
  {
    max_combinations = None
      .help = "Maximum number of basis vector combinations to test for"
              "agreement with input symmetry."
      .type = int(value_min=1, allow_none=True)
    max_refine = Auto
      .help = "Maximum number of putative crystal models to test. Default for"
              "rotation sweeps: 50, for still images: 5"
      .type = int(value_min=1, allow_none=True)
      .expert_level = 1
    sys_absent_threshold = 0.9
      .type = float(value_min=0, value_max=1, allow_none=True)
    solution_scorer = filter *weighted
      .type = choice
      .expert_level = 1
    filter
      .expert_level = 1
    {
      check_doubled_cell = True
        .type = bool
      likelihood_cutoff = 0.8
        .type = float(value_min=0, value_max=1, allow_none=True)
      volume_cutoff = 1.25
        .type = float(value_min=1, allow_none=True)
      n_indexed_cutoff = 0.9
        .type = float(value_min=0, value_max=1, allow_none=True)
    }
    weighted
      .expert_level = 1
    {
      power = 1
        .type = int(value_min=1, allow_none=True)
      volume_weight = 1
        .type = float(value_min=0, allow_none=True)
      n_indexed_weight = 1
        .type = float(value_min=0, allow_none=True)
      rmsd_weight = 1
        .type = float(value_min=0, allow_none=True)
    }
  }
  index_assignment {
    method = *simple local
      .help = "Choose between simple 'global' index assignment and xds-style "
              "'local' index assignment."
      .type = choice
      .expert_level = 1
    simple {
      hkl_tolerance = 0.3
        .help = "Maximum allowable deviation from integer-ness for assigning "
                "a miller index to a reciprocal lattice vector."
        .type = float(value_min=0, value_max=0.5, allow_none=True)
    }
    local
      .expert_level = 1
    {
      epsilon = 0.05
        .help = "This corresponds to the xds parameter INDEX_ERROR="
        .type = float(allow_none=True)
      delta = 8
        .help = "This corresponds to the xds parameter INDEX_MAGNITUDE="
        .type = int(allow_none=True)
      l_min = 0.8
        .help = "This corresponds to the xds parameter INDEX_QUALITY="
        .type = float(allow_none=True)
      nearest_neighbours = 20
        .type = int(value_min=1, allow_none=True)
    }
  }
  check_misindexing {
    grid_search_scope = 0
      .help = "Search scope for testing misindexing on h, k, l."
      .type = int(allow_none=True)
  }
  optimise_initial_basis_vectors = False
    .type = bool
    .expert_level = 2
  debug = False
    .type = bool
    .expert_level = 1
  debug_plots = False
    .help = "Requires matplotlib"
    .type = bool
    .expert_level = 1
  combine_scans = False
    .type = bool
    .expert_level = 1
  refinement_protocol {
    mode = *refine_shells repredict_only
      .help = "refine_shells: refine in increasing resolution cutoffs after"
              "indexing. repredict_only: do not refine after indexing, just"
              "update spot predictions."
      .type = choice
      .expert_level = 1
    n_macro_cycles = Auto
      .type = int(value_min=1, allow_none=True)
    d_min_step = Auto
      .help = "Reduction per step in d_min for reflections to include in"
              "refinement."
      .type = float(value_min=0, allow_none=True)
    d_min_start = None
      .type = float(value_min=0, allow_none=True)
    d_min_final = None
      .help = "Do not ever include reflections below this value in refinement."
      .type = float(value_min=0, allow_none=True)
    verbosity = 1
      .type = int(value_min=0, allow_none=True)
    disable_unit_cell_volume_sanity_check = False
      .help = "Disable sanity check on unrealistic increases in unit cell"
              "volume during refinement."
      .type = bool
      .expert_level = 1
  }
  method = *fft3d fft1d real_space_grid_search
    .type = choice
  multiple_lattice_search
    .expert_level = 1
  {
    cluster_analysis_search = False
      .help = "Perform cluster analysis search for multiple lattices."
      .type = bool
    recycle_unindexed_reflections_cutoff = 0.1
      .help = "Attempt another cycle of indexing on the unindexed reflections "
              "if more than the fraction of input reflections are unindexed."
      .type = float(value_min=0, value_max=1, allow_none=True)
    minimum_angular_separation = 5
      .help = "The minimum angular separation (in degrees) between two"
              "lattices."
      .type = float(value_min=0, allow_none=True)
    max_lattices = 1
      .type = int(allow_none=True)
    cluster_analysis {
      method = *dbscan hcluster
        .type = choice
      hcluster {
        linkage {
          method = *ward
            .type = choice
          metric = *euclidean
            .type = choice
        }
        cutoff = 15
          .type = float(value_min=0, allow_none=True)
        cutoff_criterion = *distance inconsistent
          .type = choice
      }
      dbscan {
        eps = 0.05
          .type = float(value_min=0, allow_none=True)
        min_samples = 30
          .type = int(value_min=1, allow_none=True)
      }
      min_cluster_size = 20
        .type = int(value_min=0, allow_none=True)
      intersection_union_ratio_cutoff = 0.4
        .type = float(value_min=0, value_max=1, allow_none=True)
    }
  }
  real_space_grid_search
    .expert_level = 1
  {
    characteristic_grid = 0.02
      .type = float(value_min=0, allow_none=True)
  }
  stills {
    indexer = *Auto stills sweeps
      .help = "Use the stills or sweeps indexer. Auto: choose based on the"
              "input imagesets (stills or sweeps)."
      .type = choice
      .expert_level = 1
    ewald_proximity_resolution_cutoff = 2.0
      .help = "the acceptable volume of reciprocal space for spot prediction"
      .type = float(allow_none=True)
    refine_all_candidates = True
      .help = "If False, no attempt is made to refine the model from initial"
              "basis vector selection. The indexing solution with the best"
              "RMSD is chosen."
      .type = bool
    candidate_outlier_rejection = True
      .help = "If True, while refining candiate basis solutions, also apply"
              "Sauter/ Poon (2010) outlier rejection"
      .type = bool
      .expert_level = 1
    refine_candidates_with_known_symmetry = False
      .help = "If False, when choosing the best set of candidate basis"
              "solutions, refine the candidates in the P1 setting. If True,"
              "after indexing in P1, convert the candidates to the known"
              "symmetry and apply the corresponding change of basis to the"
              "indexed reflections."
      .type = bool
      .expert_level = 2
    rmsd_min_px = 2
      .help = "Minimum acceptable RMSD for choosing candidate basis solutions"
              "(in pixels)"
      .type = float(allow_none=True)
    ewald_proximal_volume_max = 0.0025
      .help = "Maximum acceptable ewald proximal volume when choosing"
              "candidate basis solutions"
      .type = float(allow_none=True)
    isoforms
      .help = "Constrain the unit cell to specific values during refinement"
              "after initial indexing."
      .multiple = True
    {
      name = None
        .type = str
      cell = None
        .type = unit_cell
      lookup_symbol = None
        .help = "The sgtbx lookup symbol of the reflections pointgroup"
        .type = str
      rmsd_target_mm = None
        .help = "Maximum acceptable DIALS positional rmsd, in mm"
        .type = float(allow_none=True)
      beam_restraint = None
        .help = "to assure that no images are accepted where the lattice is"
                "misindexed by a unit shift."
        .type = floats(size=2)
    }
  }
}
refinement
  .help = "Parameters to configure the refinement"
{
  mp
    .expert_level = 2
  {
    nproc = 1
      .help = "The number of processes to use. Not all choices of refinement"
              "engine support nproc > 1. Where multiprocessing is possible, it"
              "is helpful only in certain circumstances, so this is not"
              "recommended for typical use."
      .type = int(value_min=1, allow_none=True)
  }
  verbosity = 0
    .help = "verbosity level"
    .type = int(value_min=0, allow_none=True)
  parameterisation
    .help = "Parameters to control the parameterisation of experimental models"
  {
    auto_reduction
      .help = "determine behaviour when there are too few reflections to"
              "reasonably produce a full parameterisation of the experiment"
              "list"
    {
      min_nref_per_parameter = 5
        .help = "the smallest number of reflections per parameter for a model"
                "parameterisation below which the parameterisation will not be"
                "made in full, but the action described below will be"
                "triggered."
        .type = int(value_min=1, allow_none=True)
      action = *fail fix remove
        .help = "action to take if there are too few reflections across the"
                "experiments related to a particular model parameterisation."
                "If fail, an exception will be raised and refinement will not"
                "proceed. If fix, refinement will continue but with the"
                "parameters relating to that model remaining fixed at their"
                "initial values. If remove, parameters relating to that model"
                "will be fixed, and in addition all reflections related to"
                "that parameterisation will be removed. This will therefore"
                "remove these reflections from other parameterisations of the"
                "global model too. For example, if a crystal model could not"
                "be parameterised it will be excised completely and not"
                "contribute to the joint refinement of the detector and beam."
                "In the fix mode, reflections emanating from that crystal will"
                "still form residuals and will contribute to detector and beam"
                "refinement."
        .type = choice
      detector_reduce = False
        .help = "Special case designed for detector metrology refinement"
                "(particularly of the CSPAD). See detector_reduce_list for"
                "details."
        .type = bool
        .expert_level = 1
      detector_reduce_list = Dist Tau2 Tau3
        .help = "Partial names to match to detector parameters to try fixing."
                "If there are still not enough parameters for refinement after"
                "fixing these, then fail. This is to ensure that metrology"
                "refinement never completes if it is not able to refine some"
                "panels. The default is to try fixing the distance as well as"
                "Tau2 and Tau3 rotations of detector panel, leaving the"
                "in-plane shifts and the rotation around the detector normal"
                "for refinement. groups only."
        .type = strings
        .expert_level = 1
    }
    scan_varying = False
      .help = "Allow models that are not forced to be static to vary during"
              "the
               scan"
      .type = bool
    compose_model_per = image *block
      .help = "For scan-varying parameterisations, compose a new model either"
              "every image or within blocks of a width specified in the"
              "reflections parameters. When this block width is larger than"
              "the image width the result is faster, with a trade-off in"
              "accuracy"
      .type = choice
      .expert_level = 1
    debug_centroid_analysis = False
      .help = "Set True to write out a file containing the reflections used"
              "for centroid analysis for automatic setting of the "
              "scan-varying interval width. This can then be analysed with"
              "dev.dials.plot_centroid_analysis"
      .type = bool
      .expert_level = 2
    beam
      .help = "beam parameters"
    {
      fix = all *in_spindle_plane out_spindle_plane *wavelength
        .help = "Whether to fix beam parameters. By default, in_spindle_plane"
                "is selected, and one of the two parameters is fixed. If a"
                "goniometer is present this leads to the beam orientation"
                "being restricted to a direction in the initial spindle-beam"
                "plane. Wavelength is also fixed by default, to allow"
                "refinement of the unit cell volume."
        .type = choice(multi=True)
      fix_list = None
        .help = "Fix specified parameters by a list of 0-based indices or"
                "partial names to match"
        .type = strings
        .expert_level = 1
      constraints
        .help = "Parameter equal shift constraints to use in refinement."
        .multiple = True
        .expert_level = 2
      {
        id = None
          .help = "Select only the specified experiments when looking up which"
                  "parameterisations to apply the constraint to. If an"
                  "identified parameterisation affects multiple experiments"
                  "then the index of any one of those experiments suffices to"
                  "identify that parameterisation. If None (the default) then"
                  "constraints will be applied to all parameterisations of"
                  "this type."
          .type = ints(value_min=0)
        parameter = None
          .help = "Identify which parameter of each parameterisation to"
                  "constrain by a (partial) parameter name to match. Model"
                  "name prefixes such as 'Detector1' will be ignored as"
                  "parameterisations are already identified by experiment id"
          .type = str
      }
      force_static = True
        .help = "Force a static parameterisation for the beam when doing"
                "scan-varying refinement"
        .type = bool
        .expert_level = 1
      smoother
        .help = "Options that affect scan-varying parameterisation"
        .expert_level = 1
      {
        interval_width_degrees = 36.0
          .help = "Width of scan between checkpoints in degrees. Can be set to"
                  "Auto."
          .type = float(value_min=0, allow_none=True)
        absolute_num_intervals = None
          .help = "Number of intervals between checkpoints if scan_varying"
                  "refinement is requested. If set, this overrides"
                  "interval_width_degrees"
          .type = int(value_min=1, allow_none=True)
      }
    }
    crystal
      .help = "crystal parameters"
    {
      fix = all cell orientation
        .help = "Fix crystal parameters"
        .type = choice
      unit_cell
        .expert_level = 1
      {
        fix_list = None
          .help = "Fix specified parameters by a list of 0-based indices or"
                  "partial names to match"
          .type = strings
          .expert_level = 1
        restraints
          .help = "Least squares unit cell restraints to use in refinement."
          .expert_level = 1
        {
          tie_to_target
            .multiple = True
          {
            values = None
              .help = "Target unit cell parameters for the restraint for this"
                      "parameterisation"
              .type = floats(size=6)
            sigmas = None
              .help = "The unit cell target values are associated with sigmas"
                      "which are used to determine the weight of each"
                      "restraint. A sigma of zero will remove the restraint at"
                      "that position. If symmetry constrains two cell"
                      "dimensions to be equal then only the smaller of the two"
                      "sigmas will be kept"
              .type = floats(size=6, value_min=0)
            id = None
              .help = "Select only the specified experiments when looking up"
                      "which parameterisations to apply these restraints to."
                      "If an identified parameterisation affects multiple"
                      "experiments then the index of any one of those"
                      "experiments suffices to restrain that parameterisation."
                      "If None (the default) then the restraints will be"
                      "applied to all experiments."
              .type = ints(value_min=0)
          }
          tie_to_group
            .multiple = True
          {
            target = *mean low_memory_mean median
              .help = "Function to tie group parameter values to"
              .type = choice
            sigmas = None
              .help = "The unit cell parameters are associated with sigmas"
                      "which are used to determine the weight of each"
                      "restraint. A sigma of zero will remove the restraint at"
                      "that position."
              .type = floats(size=6, value_min=0)
            id = None
              .help = "Select only the specified experiments when looking up"
                      "which  parameterisations to apply these restraints to."
                      "For every parameterisation that requires a restraint at"
                      "least one experiment index must be supplied. If None"
                      "(the default) the restraints will be applied to all"
                      "experiments."
              .type = ints(value_min=0)
          }
        }
        constraints
          .help = "Parameter equal shift constraints to use in refinement."
          .multiple = True
          .expert_level = 2
        {
          id = None
            .help = "Select only the specified experiments when looking up"
                    "which parameterisations to apply the constraint to. If an"
                    "identified parameterisation affects multiple experiments"
                    "then the index of any one of those experiments suffices"
                    "to identify that parameterisation. If None (the default)"
                    "then constraints will be applied to all parameterisations"
                    "of this type."
            .type = ints(value_min=0)
          parameter = None
            .help = "Identify which parameter of each parameterisation to"
                    "constrain by a (partial) parameter name to match. Model"
                    "name prefixes such as 'Detector1' will be ignored as"
                    "parameterisations are already identified by experiment id"
            .type = str
        }
        force_static = False
          .help = "Force a static parameterisation for the crystal unit cell"
                  "when doing scan-varying refinement"
          .type = bool
          .expert_level = 1
        set_scan_varying_errors = False
          .help = "If scan-varying refinement is done, and if the estimated"
                  "covariance of the B matrix has been calculated by the"
                  "minimiser, choose whether to return this to the model or"
                  "not. The default is not to, in order to keep the file size"
                  "of the serialized model small."
          .type = bool
        smoother
          .help = "Options that affect scan-varying parameterisation"
          .expert_level = 1
        {
          interval_width_degrees = 36.0
            .help = "Width of scan between checkpoints in degrees. Can be set"
                    "to Auto."
            .type = float(value_min=0, allow_none=True)
          absolute_num_intervals = None
            .help = "Number of intervals between checkpoints if scan_varying"
                    "refinement is requested. If set, this overrides"
                    "interval_width_degrees"
            .type = int(value_min=1, allow_none=True)
        }
      }
      orientation
        .expert_level = 1
      {
        fix_list = None
          .help = "Fix specified parameters by a list of 0-based indices or"
                  "partial names to match"
          .type = strings
          .expert_level = 1
        constraints
          .help = "Parameter equal shift constraints to use in refinement."
          .multiple = True
          .expert_level = 2
        {
          id = None
            .help = "Select only the specified experiments when looking up"
                    "which parameterisations to apply the constraint to. If an"
                    "identified parameterisation affects multiple experiments"
                    "then the index of any one of those experiments suffices"
                    "to identify that parameterisation. If None (the default)"
                    "then constraints will be applied to all parameterisations"
                    "of this type."
            .type = ints(value_min=0)
          parameter = None
            .help = "Identify which parameter of each parameterisation to"
                    "constrain by a (partial) parameter name to match. Model"
                    "name prefixes such as 'Detector1' will be ignored as"
                    "parameterisations are already identified by experiment id"
            .type = str
        }
        force_static = False
          .help = "Force a static parameterisation for the crystal orientation"
                  "when doing scan-varying refinement"
          .type = bool
          .expert_level = 1
        smoother
          .help = "Options that affect scan-varying parameterisation"
          .expert_level = 1
        {
          interval_width_degrees = 36.0
            .help = "Width of scan between checkpoints in degrees. Can be set"
                    "to Auto."
            .type = float(value_min=0, allow_none=True)
          absolute_num_intervals = None
            .help = "Number of intervals between checkpoints if scan_varying"
                    "refinement is requested. If set, this overrides"
                    "interval_width_degrees"
            .type = int(value_min=1, allow_none=True)
        }
      }
    }
    detector
      .help = "detector parameters"
    {
      panels = *automatic single multiple hierarchical
        .help = "Select appropriate detector parameterisation. Both the single"
                "and multiple panel detector options treat the whole detector"
                "as a rigid body. The hierarchical parameterisation treats"
                "groups of panels as separate rigid bodies."
        .type = choice
        .expert_level = 1
      hierarchy_level = 0
        .help = "Level of the detector hierarchy (starting from the root at 0)"
                "at which to determine panel groups to parameterise"
                "independently"
        .type = int(value_min=0, allow_none=True)
        .expert_level = 1
      fix = all position orientation
        .help = "Fix detector parameters. The translational parameters"
                "(position) may be set separately to the orientation."
        .type = choice
      fix_list = None
        .help = "Fix specified parameters by a list of 0-based indices or"
                "partial names to match"
        .type = strings
        .expert_level = 1
      constraints
        .help = "Parameter equal shift constraints to use in refinement."
        .multiple = True
        .expert_level = 2
      {
        id = None
          .help = "Select only the specified experiments when looking up which"
                  "parameterisations to apply the constraint to. If an"
                  "identified parameterisation affects multiple experiments"
                  "then the index of any one of those experiments suffices to"
                  "identify that parameterisation. If None (the default) then"
                  "constraints will be applied to all parameterisations of"
                  "this type."
          .type = ints(value_min=0)
        parameter = None
          .help = "Identify which parameter of each parameterisation to"
                  "constrain by a (partial) parameter name to match. Model"
                  "name prefixes such as 'Detector1' will be ignored as"
                  "parameterisations are already identified by experiment id"
          .type = str
      }
      force_static = True
        .help = "Force a static parameterisation for the detector when doing"
                "scan-varying refinement"
        .type = bool
        .expert_level = 1
      smoother
        .help = "Options that affect scan-varying parameterisation"
        .expert_level = 1
      {
        interval_width_degrees = 36.0
          .help = "Width of scan between checkpoints in degrees. Can be set to"
                  "Auto."
          .type = float(value_min=0, allow_none=True)
        absolute_num_intervals = None
          .help = "Number of intervals between checkpoints if scan_varying"
                  "refinement is requested. If set, this overrides"
                  "interval_width_degrees"
          .type = int(value_min=1, allow_none=True)
      }
    }
    goniometer
      .help = "goniometer setting matrix parameters"
    {
      fix = *all in_beam_plane out_beam_plane
        .help = "Whether to fix goniometer parameters. By default, fix all."
                "Alternatively the setting matrix can be constrained to allow"
                "rotation only within the spindle-beam plane or to allow"
                "rotation only around an axis that lies in that plane. Set to"
                "None to refine the in two orthogonal directions."
        .type = choice(multi=True)
      fix_list = None
        .help = "Fix specified parameters by a list of 0-based indices or"
                "partial names to match"
        .type = strings
        .expert_level = 1
      constraints
        .help = "Parameter equal shift constraints to use in refinement."
        .multiple = True
        .expert_level = 2
      {
        id = None
          .help = "Select only the specified experiments when looking up which"
                  "parameterisations to apply the constraint to. If an"
                  "identified parameterisation affects multiple experiments"
                  "then the index of any one of those experiments suffices to"
                  "identify that parameterisation. If None (the default) then"
                  "constraints will be applied to all parameterisations of"
                  "this type."
          .type = ints(value_min=0)
        parameter = None
          .help = "Identify which parameter of each parameterisation to"
                  "constrain by a (partial) parameter name to match. Model"
                  "name prefixes such as 'Detector1' will be ignored as"
                  "parameterisations are already identified by experiment id"
          .type = str
      }
      force_static = True
        .help = "Force a static parameterisation for the goniometer when doing"
                "scan-varying refinement"
        .type = bool
        .expert_level = 1
      smoother
        .help = "Options that affect scan-varying parameterisation"
        .expert_level = 1
      {
        interval_width_degrees = 36.0
          .help = "Width of scan between checkpoints in degrees. Can be set to"
                  "Auto."
          .type = float(value_min=0, allow_none=True)
        absolute_num_intervals = None
          .help = "Number of intervals between checkpoints if scan_varying"
                  "refinement is requested. If set, this overrides"
                  "interval_width_degrees"
          .type = int(value_min=1, allow_none=True)
      }
    }
    sparse = Auto
      .help = "Calculate gradients using sparse data structures."
      .type = bool
      .expert_level = 1
    treat_single_image_as_still = False
      .help = "Set this to True to treat a single image scan with a non zero"
              "oscillation width as a still"
      .type = bool
      .expert_level = 1
    spherical_relp_model = False
      .help = "For stills refinement, set true to use the spherical relp model"
              "for prediction and gradients."
      .type = bool
      .expert_level = 1
  }
  refinery
    .help = "Parameters to configure the refinery"
    .expert_level = 1
  {
    engine = SimpleLBFGS LBFGScurvs GaussNewton *LevMar SparseLevMar
      .help = "The minimisation engine to use"
      .type = choice
    max_iterations = None
      .help = "Maximum number of iterations in refinement before termination."
              "None implies the engine supplies its own default."
      .type = int(value_min=1, allow_none=True)
    log = None
      .help = "Filename for an optional log that a minimisation engine may use"
              "to write additional information"
      .type = path
    journal
      .help = "Extra items to track in the refinement history"
    {
      track_step = False
        .help = "Record parameter shifts history in the refinement journal, if"
                "the engine supports it."
        .type = bool
      track_gradient = False
        .help = "Record parameter gradients history in the refinement journal,"
                "if the engine supports it."
        .type = bool
      track_parameter_correlation = False
        .help = "Record correlation matrix between columns of the Jacobian for"
                "each step of refinement."
        .type = bool
      track_condition_number = False
        .help = "Record condition number of the Jacobian for each step of "
                "refinement."
        .type = bool
      track_out_of_sample_rmsd = False
        .help = "Record RMSDs calculated using the refined experiments with"
                "reflections not used in refinement at each step. Only valid"
                "if a subset of input reflections was taken for refinement"
        .type = bool
    }
  }
  target
    .help = "Parameters to configure the target function"
    .expert_level = 1
  {
    rmsd_cutoff = *fraction_of_bin_size absolute
      .help = "Method to choose rmsd cutoffs. This is currently either as a"
              "fraction of the discrete units of the spot positional data,"
              "i.e. (pixel width, pixel height, image thickness in phi), or a"
              "tuple of absolute values to use as the cutoffs"
      .type = choice
    bin_size_fraction = 0.0
      .help = "Set this to a fractional value, say 0.2, to make a cut off in"
              "the natural discrete units of positional data, viz., (pixel"
              "width, pixel height, image thickness in phi). This would then"
              "determine when the RMSD target is achieved. Only used if"
              "rmsd_cutoff = fraction_of_bin_size."
      .type = float(value_min=0, allow_none=True)
    absolute_cutoffs = None
      .help = "Absolute Values for the RMSD target achieved cutoffs in X, Y"
              "and Phi. The units are (mm, mm, rad)."
      .type = floats(size=3, value_min=0)
    gradient_calculation_blocksize = None
      .help = "Maximum number of reflections to use for gradient calculation."
              "If there are more reflections than this in the manager then the"
              "minimiser must do the full calculation in blocks."
      .type = int(value_min=1, allow_none=True)
  }
  reflections
    .help = "Parameters used by the reflection manager"
  {
    reflections_per_degree = 100
      .help = "The number of centroids per degree of the sweep to use in"
              "refinement. Set to None to use all suitable reflections."
      .type = float(value_min=0, allow_none=True)
    minimum_sample_size = 1000
      .help = "cutoff that determines whether subsetting of the input"
              "reflection list is done"
      .type = int(allow_none=True)
    maximum_sample_size = None
      .help = "The maximum number of reflections to use in refinement."
              "Overrides reflections_per_degree if that produces a larger"
              "sample size."
      .type = int(value_min=1, allow_none=True)
    random_seed = 42
      .help = "Random seed to use when sampling to create a working set of"
              "reflections. May be int or None."
      .type = int(allow_none=True)
      .expert_level = 1
    close_to_spindle_cutoff = 0.02
      .help = "The inclusion criterion currently uses the volume of the"
              "parallelepiped formed by the spindle axis, the incident beam"
              "and the scattered beam. If this is lower than some value then"
              "the reflection is excluded from refinement. In detector space,"
              "these are the reflections located close to the rotation axis."
      .type = float(value_min=0, allow_none=True)
      .expert_level = 1
    trim_scan_edges = 0.0
      .help = "Reflections within this value in degrees from the centre of the"
              "first or last image of the scan will be removed before"
              "refinement, unless doing so would result in too few remaining"
              "reflections. Reflections that are truncated at the scan edges"
              "have poorly-determined centroids and can bias the refined model"
              "if they are included."
      .type = float(value_min=0, value_max=1, allow_none=True)
      .expert_level = 1
    block_width = 1.0
      .help = "Width of a reflection 'block' (in degrees) determining how"
              "fine- grained the model used for scan-varying prediction during"
              "refinement is. Currently only has any effect if the crystal"
              "parameterisation is set to use compose_model_per=block"
      .type = float(value_min=0, allow_none=True)
      .expert_level = 1
    weighting_strategy
      .help = "Parameters to configure weighting strategy overrides"
      .expert_level = 1
    {
      override = statistical stills constant external_deltapsi
        .help = "selection of a strategy to override default weighting"
                "behaviour"
        .type = choice
      delpsi_constant = 1000000
        .help = "used by the stills strategy to choose absolute weight value"
                "for the angular distance from Ewald sphere term of the target"
                "function, whilst the X and Y parts use statistical weights"
        .type = float(value_min=0, allow_none=True)
      constants = 1.0 1.0 1.0
        .help = "constant weights for three parts of the target function,"
                "whether the case is for stills or scans. The default gives"
                "unit weighting."
        .type = floats(size=3, value_min=0)
    }
    outlier
      .help = "Outlier rejection after initial reflection prediction."
    {
      algorithm = null *auto mcd tukey sauter_poon
        .help = "Outlier rejection algorithm. If auto is selected, the"
                "algorithm is chosen automatically"
        .type = choice
      minimum_number_of_reflections = 20
        .help = "The minimum number of input observations per outlier"
                "rejection job below which all reflections in the job will be"
                "rejected as potential outliers."
        .type = int(value_min=0, allow_none=True)
      separate_experiments = True
        .help = "If true, outlier rejection will be performed on each"
                "experiment separately. Otherwise, the data from all"
                "experiments will be combined for outlier rejection."
        .type = bool
      separate_panels = Auto
        .help = "If true, outlier rejection will be performed separately for"
                "each panel of a multi-panel detector model. Otherwise data"
                "from across all panels will be combined for outlier"
                "rejection."
        .type = bool
      separate_blocks = True
        .help = "If true, for scans outlier rejection will be performed"
                "separately in equal-width blocks of phi, controlled by the"
                "parameter outlier.block_width."
        .type = bool
      block_width = Auto
        .help = "If separate_blocks, a scan will be divided into equal-sized"
                "blocks with width (in degrees) close to this value for"
                "outlier rejection. If Auto, a width of at least 18 degrees"
                "will be determined, such that each block contains enough"
                "reflections to perform outlier rejection."
        .type = float(value_min=1, allow_none=True)
      tukey
        .help = "Options for the tukey outlier rejector"
        .expert_level = 1
      {
        iqr_multiplier = 1.5
          .help = "The IQR multiplier used to detect outliers. A value of 1.5"
                  "gives Tukey's rule for outlier detection"
          .type = float(value_min=0, allow_none=True)
      }
      mcd
        .help = "Options for the mcd outlier rejector, which uses an algorithm"
                "based on FAST-MCD by Rousseeuw and van Driessen. See"
                "doi.org/10.1080/00401706.1999.10485670."
        .expert_level = 1
      {
        alpha = 0.5
          .help = "Decimal fraction controlling the size of subsets over which"
                  "the covariance matrix determinant is minimised."
          .type = float(value_min=0, value_max=1, allow_none=True)
        max_n_groups = 5
          .help = "The maximum number of groups to split the dataset into if"
                  "the dataset is 'large' (more observations than twice the"
                  "min_group_size)."
          .type = int(value_min=1, allow_none=True)
        min_group_size = 300
          .help = "The smallest sub-dataset size when splitting the dataset"
                  "into a number of groups, maximally max_n_groups."
          .type = int(value_min=100, allow_none=True)
        n_trials = 500
          .help = "The number of samples used for initial estimates to seed"
                  "the search within each sub-dataset."
          .type = int(value_min=1, allow_none=True)
        k1 = 2
          .help = "The number of concentration steps to take after initial"
                  "estimates."
          .type = int(value_min=1, allow_none=True)
        k2 = 2
          .help = "If the dataset is 'large', the number of concentration"
                  "steps to take after applying the best subset estimates to"
                  "the merged group."
          .type = int(value_min=1, allow_none=True)
        k3 = 100
          .help = "If the dataset is 'small', the number of concentration"
                  "steps to take after selecting the best of the initial"
                  "estimates, applied to the whole dataset."
          .type = int(value_min=1, allow_none=True)
        threshold_probability = 0.975
          .help = "Quantile probability from the Chi-squared distribution with"
                  "number of degrees of freedom equal to the number of"
                  "dimensions of the data data (e.g. 3 for X, Y and Phi"
                  "residuals). Observations whose robust Mahalanobis distances"
                  "are larger than the obtained quantile will be flagged as"
                  "outliers."
          .type = float(value_min=0, value_max=1, allow_none=True)
      }
      sauter_poon
        .help = "Options for the outlier rejector described in Sauter & Poon"
                "(2010) (https://doi.org/10.1107/S0021889810010782)"
        .expert_level = 1
      {
        px_sz = Auto
          .help = "X, Y pixel size in mm. If Auto, this will be taken from the"
                  "first panel of the first experiment."
          .type = floats(size=2, value_min=0.001)
        verbose = False
          .help = "Verbose output."
          .type = bool
          .multiple = False
        pdf = None
          .help = "Output file name for making graphs of |dr| vs spot number"
                  "and dy vs dx."
          .type = str
          .multiple = False
      }
    }
  }
}
output {
  experiments = experiments.json
    .type = path
  split_experiments = False
    .type = bool
  reflections = indexed.pickle
    .type = path
  unindexed_reflections = None
    .type = path
  log = dials.index.log
    .type = str
  debug_log = dials.index.debug.log
    .type = str
}
verbosity = 1
  .help = "The verbosity level"
  .type = int(value_min=0, allow_none=True)