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

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.

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.

get_elapsed_time()

update(percent)

Update the timer.

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

dials.util.command_line.heading(text)

dials.util.command_line.parse_range_list_string(string)

Parse a string in the following ways: string: 1, 2, 3 -> [1, 2, 3] string: 1 - 6 -> [1, 2, 3, 4, 5, 6] string: 1 - 6, 7, 8, 9 -> [1, 2, 3, 4, 5, 6, 7, 8, 9]

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

Bases: dials.util.export_mtz.MergedMTZWriter

Mtz writer for multi-wavelength merged data.

add_dataset(merged_array, anom_array=None, amplitudes=None, anom_amplitudes=None, suffix=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.

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: dials.util.export_mtz.MTZWriterBase

Mtz writer for merged data.

add_dataset(merged_array, anom_array=None, amplitudes=None, anom_amplitudes=None, suffix=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.UnmergedMTZWriter(space_group, unit_cell=None)

Bases: dials.util.export_mtz.MTZWriterBase

add_batch_list(image_range, experiment, wavelength, dataset_id, batch_offset, force_static_model)

Add batch metadata to the mtz file.

write_columns(integrated_data)

Write the column definitions AND data to the current dataset.

dials.util.export_mtz.export_mtz(integrated_data, experiment_list, params)

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

dials.util.export_mtz.match_wavelengths(experiments)

Create a dictionary matching wavelength to experiments (index in list)

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=<_io.TextIOWrapper name='<stdout>' mode='w' encoding='UTF-8'>)

Bases: libtbx.auto_build.install_distribution.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/now22/build_dials/modules/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.ioutil.get_ub_matrix_from_xparm(handle)

Get the ub_matrix from an xparm file handle

Params:

handle The file handle

Returns:The ub_matrix

dials.util.ioutil.get_unit_cell_from_xparm(handle)

Get the unit_cell object from an xparm file handle

Params:

handle The file handle

Returns:The unit cell 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.ConfigWriter(master_phil)

Bases: object

Class to write configuration to file.

write(params, filename)

Write the configuration to file.

Parameters:

• params – The input phil parameters
• filename – The output filename

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.

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

class dials.util.options.OptionParser(phil=None, read_experiments=False, read_reflections=False, read_experiments_from_images=False, check_format=True, sort_options=False, **kwargs)

Bases: dials.util.options.OptionParserBase

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

diff_phil

Get the diff phil.

Returns:The diff phil scope

format_help(formatter=None)

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

phil

Get the phil object

Returns:The phil scope

system_phil

Get the system phil.

Returns:The system phil scope

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

Bases: optparse.OptionParser, object

The base class for the option parser.

format_epilog(formatter)

Don’t do formatting on epilog.

parse_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.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

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

phil

Get the phil object

Returns:The phil scope

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.