Util

class dials.util.command_line.Command

Bases: object

Class to nicely print out a command with timing info.

classmethod end(string)

Print the ‘end of command’ string.

indent = 0

max_length = 80

print_time = True

classmethod start(string)

Print the ‘start command’ string.

class dials.util.command_line.ProgressBar(title=None, spinner=True, bar=True, estimate_time=True, indent=0, length=80)

Bases: object

A command line progress bar.

__init__(title=None, spinner=True, bar=True, estimate_time=True, indent=0, length=80)

Init the progress bar parameters.

finished(string=None)

The progress bar is finished.

update(fpercent)

Update the progress bar with a percentage.

class dials.util.command_line.ProgressBarTimer

Bases: object

A simple timer for the progress bar.

__init__()

Init the progress bar timer.

get_elapsed_time()

update(percent)

Update the timer.

dials.util.command_line.coloured(text, *args, **kwargs)

dials.util.command_line.heading(text)

class dials.util.export_mtz.MADMergedMTZWriter(space_group, unit_cell=None)

Bases: MergedMTZWriter

Mtz writer for multi-wavelength merged data.

add_dataset(merged_array=None, anom_array=None, amplitudes=None, anom_amplitudes=None, dano=None, multiplicities=None, anom_multiplicities=None, suffix=None, half_datasets: MergedHalfDatasets | None = None, r_free_array=None)

Add merged data to the most recent dataset.

Parameters:

• merged_array – A merged miller array of IMEAN intensities

• wavelength – The wavelength of the dataset

• anom_array (Optional) – An anomalous merged miller array

• amplitudes (Optional) – A merged miller array of amplitudes

• anom_amplitudes (Optional) – An anomalous merged array of amplitudes

• suffix (Optional[str]) – Column name suffix to use for this dataset.

class dials.util.export_mtz.MTZWriterBase(space_group, unit_cell=None)

Bases: object

Helper for adding metadata, crystals and datasets to an mtz file object.

__init__(space_group, unit_cell=None)

If a unit cell is provided, will be used as default unless specified for each crystal.

add_crystal(crystal_name=None, project_name=None, unit_cell=None)

Add a crystal to the mtz file object.

add_empty_dataset(wavelength, name=None)

Add an empty dataset object to the mtz file.

class dials.util.export_mtz.MergedMTZWriter(space_group, unit_cell=None)

Bases: MTZWriterBase

Mtz writer for merged data.

add_dataset(merged_array=None, anom_array=None, amplitudes=None, anom_amplitudes=None, dano=None, multiplicities=None, anom_multiplicities=None, suffix=None, half_datasets: MergedHalfDatasets | None = None, r_free_array=None)

Add merged data to the most recent dataset.

Parameters:

• merged_array – A merged miller array of IMEAN intensities

• wavelength – The wavelength of the dataset

• anom_array (Optional) – An anomalous merged miller array

• amplitudes (Optional) – A merged miller array of amplitudes

• anom_amplitudes (Optional) – An anomalous merged array of amplitudes

• suffix (Optional[str]) – Column name suffix to use for this dataset.

class dials.util.export_mtz.WavelengthGroup(min_wl: 'float', max_possible_wl: 'float', identifiers: 'list[str]' = <factory>, exp_nos: 'list[int]' = <factory>, wavelengths: 'list[float]' = <factory>, weighted_mean: 'float' = 0)

Bases: object

__init__(min_wl: float, max_possible_wl: float, identifiers: list[str] = <factory>, exp_nos: list[int] = <factory>, wavelengths: list[float] = <factory>, weighted_mean: float = 0) → None

add_experiment(identifier: str, loc_in_list: int, wl: float) → None

calculate_weighted_mean(reflection_tables: List[reflection_table]) → None

exp_nos: list[int]

identifiers: list[str]

max_possible_wl: float

min_wl: float

wavelengths: list[float]

weighted_mean: float = 0

dials.util.export_mtz.add_batch_list(mtz, image_range, experiment, wavelength, dataset_id, batch_offset, force_static_model)

Add batch metadata to the gemmi mtz object.

dials.util.export_mtz.convert_to_cambridge(experiments)

Rotate the geometry of an experiment list to match the Cambridge frame, in which X is along the idealized X-ray beam and Z is along the primary rotation axis

dials.util.export_mtz.export_mtz(reflection_table, experiment_list, intensity_choice, filename, best_unit_cell=None, partiality_threshold=0.4, combine_partials=True, min_isigi=-5, filter_ice_rings=False, d_min=None, force_static_model=False, crystal_name=None, project_name=None, wavelength_tolerance=0.0001)

Export data from reflection_table corresponding to experiment_list to an MTZ file hklout.

dials.util.export_mtz.log_summary(mtz)

Log a summary of an MTZ object, based on the output of gemmi mtz –dump

dials.util.export_mtz.match_wavelengths(experiments, absolute_tolerance=0.0001)

dials.util.export_mtz.rotate_crystal(crystal, Rmat, axis, angle)

dials.util.export_mtz.write_columns(mtz, reflection_table)

Write the column definitions AND data to the current dataset.

dials.util.export_text.export_text(integrated_data)

Export contents of a dials reflection table as text.

class dials.util.image.reader

Bases: object

A class to read the CBF files used in DIALS

get_data()

Get the gain array from the file

read_file(filename)

Read the CBF file

Installer script for DIALS, based on automatically generated template. This must be moved to the proper location to work.

class dials.util.installer.installer(args=None, out=<colorama.ansitowin32.StreamWrapper object>)

Bases: installer

base_package_options = ['--dials', '--all']

configure_modules = ['mmtbx', 'smtbx', 'dials', 'cbflib', 'annlib_adaptbx', 'wxtbx', 'gltbx']

dest_dir_prefix = 'dials'

include_gui_packages = True

installer_dir = '/dls/science/groups/scisoft/DIALS/CD/now/build_dials/modules/dials/src/dials'

make_apps = []

product_name = 'DIALS'

product_specific_finalize_install(log)

Additional installation setup, file cleanup, more add-ons, etc.

remove_sources_default = False

source_packages = ['cctbx_bundle', 'dials', 'cbflib', 'annlib', 'annlib_adaptbx']

dials.util.ioutil.get_inverse_ub_matrix_from_xparm(handle)

Get the inverse_ub_matrix from an xparm file handle

Params:

handle The file handle

Returns:

The inverse_ub_matrix

dials.util.ioutil.get_space_group_type_from_xparm(handle)

Get the space group tyoe object from an xparm file handle

Params:

handle The file handle

Returns:

The space group type object

dials.util.nexus.dump(experiments, reflections, params)

dials.util.nexus.get_entry(filename, mode='a')

dials.util.nexus.load(filename)

class dials.util.options.ArgumentHandlingErrorInfo(name, validation, message, traceback, type, exception)

Bases: tuple

exception

Alias for field number 5

message

Alias for field number 2

name

Alias for field number 0

traceback

Alias for field number 3

type

Alias for field number 4

validation

Alias for field number 1

class dials.util.options.ArgumentParser(phil=None, read_experiments=False, read_reflections=False, read_experiments_from_images=False, check_format=True, sort_options=False, formatter_class=<class 'argparse.RawDescriptionHelpFormatter'>, **kwargs)

Bases: ArgumentParserBase

A class to parse command line options and get the system configuration. The class extends argparse.ArgumentParser to include the reading of phil parameters.

__init__(phil=None, read_experiments=False, read_reflections=False, read_experiments_from_images=False, check_format=True, sort_options=False, formatter_class=<class 'argparse.RawDescriptionHelpFormatter'>, **kwargs)

Initialise the class.

Parameters:

• phil – The phil scope

• read_experiments – Try to read the experiments

• read_reflections – Try to read the reflections

• read_experiments_from_images – Try to read the experiments from images

• check_format – Check the format when reading images

• sort_options – Show argument sorting options

property diff_phil

Get the diff phil.

Returns:

The diff phil scope

format_help()

Format the help string

Parameters:

formatter – The formatter to use

Returns:

The formatted help text

parse_args(args=None, show_diff_phil=False, return_unhandled=False, ignore_unhandled=False, quick_parse=False)

Parse the command line arguments and get system configuration.

Parameters:

• args – The input arguments

• show_diff_phil – True/False Print the diff phil

• return_unhandled – True/False return unhandled arguments

• ignore_unhandled – True/False ignore unhandled arguments if return_unhandled is False

• quick_parse – Return as fast as possible and without reading any data, ignoring class constructor options

Returns:

The options and phil parameters

property phil

Get the phil object

Returns:

The phil scope

property system_phil

Get the system phil.

Returns:

The system phil scope

class dials.util.options.ArgumentParserBase(config_options=False, sort_options=False, **kwargs)

Bases: ArgumentParser

The base class for the option parser.

__init__(config_options=False, sort_options=False, **kwargs)

Initialise the class.

Parameters:

• config_options – True/False show configuration options

• sort_options – True/False show argument sorting options

format_epilog(formatter)

Don’t do formatting on epilog.

parse_known_args(args=None, quick_parse=False)

Parse the command line arguments and get system configuration.

Parameters:

args – The arguments to parse.

Returns:

The options and phil parameters

class dials.util.options.Importer(args, read_experiments=False, read_reflections=False, read_experiments_from_images=False, check_format=True, verbose=False, compare_beam=None, compare_detector=None, compare_goniometer=None, scan_tolerance=None, format_kwargs=None, load_models=True)

Bases: object

A class to import the command line arguments.

__init__(args, read_experiments=False, read_reflections=False, read_experiments_from_images=False, check_format=True, verbose=False, compare_beam=None, compare_detector=None, compare_goniometer=None, scan_tolerance=None, format_kwargs=None, load_models=True)

Parse the arguments. Populates its instance attributes in an intelligent way from the arguments in args.

If include is set, only those items set will be tried. If not, then if exclude is set, then those items will not be tested.

These are the types we can import:

• images: a list of images

• reflections : a list of reflections

• experiments: a list of experiments

Parameters:

• args – The arguments to parse

• read_experiments – Try to read the experiments

• read_reflections – Try to read the reflections

• read_experiments_from_images – Try to read the experiments from images

• check_format – Check the format when reading images

• verbose – True/False print out some stuff

• load_models – Whether to load all models for ExperimentLists

try_read_experiments(args, check_format, verbose)

Try to import experiments.

Parameters:

• args – The input arguments

• check_format – True/False check the image format

• verbose – Print verbose output

Returns:

Unhandled arguments

try_read_experiments_from_images(args, verbose, compare_beam, compare_detector, compare_goniometer, scan_tolerance, format_kwargs, load_models=True)

Try to import images.

Parameters:

• args – The input arguments

• verbose – Print verbose output

• compare_beam

• compare_detector

• compare_goniometer

• scan_tolerance

• format_kwargs

• load_models – Whether to load all models for ExperimentLists

Returns:

Unhandled arguments

try_read_reflections(args, verbose)

Try to import reflections.

Parameters:

• args – The input arguments

• verbose – Print verbose output

Returns:

Unhandled arguments

exception dials.util.options.InvalidPhilError

Bases: ValueError

class dials.util.options.OptionParser(*args, **kwargs)

Bases: ArgumentParser

__init__(*args, **kwargs)

Initialise the class.

Parameters:

• phil – The phil scope

• read_experiments – Try to read the experiments

• read_reflections – Try to read the reflections

• read_experiments_from_images – Try to read the experiments from images

• check_format – Check the format when reading images

• sort_options – Show argument sorting options

class dials.util.options.PhilCommandParser(phil=None, read_experiments=False, read_reflections=False, read_experiments_from_images=False, check_format=True)

Bases: object

A class to parse phil parameters from positional arguments

__init__(phil=None, read_experiments=False, read_reflections=False, read_experiments_from_images=False, check_format=True)

Initialise the parser.

Parameters:

• phil – The phil scope

• read_experiments – Try to read the experiments

• read_reflections – Try to read the reflections

• read_experiments_from_images – Try to read the experiments from images

• check_format – Check the format when reading images

property diff_phil

Get the diff phil.

Returns:

The difference phil scope

parse_args(args, verbose=False, return_unhandled=False, quick_parse=False)

Parse the command line arguments.

Parameters:

• args – The input arguments

• verbose – Print verbose output

• return_unhandled – True/False also return unhandled arguments

• quick_parse – Return as fast as possible and without reading any data, ignoring class constructor options.

Returns:

The options and parameters and (optionally) unhandled arguments

property phil

Get the phil object

Returns:

The phil scope

property system_phil

Get the system phil.

Returns:

The system phil scope

dials.util.options.flatten_experiments(filename_object_list)

Flatten a list of experiment lists

Parameters:

filename_object_list – The parameter item

Returns:

The flattened experiment lists

dials.util.options.flatten_reflections(filename_object_list)

Flatten a list of reflections tables

A check is also made for the ‘id’ values in the reflection tables, which are renumbered from 0..n-1 to avoid clashes. The experiment_identifiers dict is also updated if present in the input tables.

Parameters:

filename_object_list – The parameter item

Returns:

The flattened reflection table

dials.util.options.reflections_and_experiments_from_files(reflection_file_object_list, experiment_file_object_list)

Extract reflection tables and an experiment list from the files. If experiment identifiers are set, the order of the reflection tables is changed to match the order of experiments.