iotbx.reflection_file_reader - generic reflection file input

This module provides a generic frontend to all of the reflection file formats supported in iotbx. Note that this module can also be used indirectly via the even more generic iotbx.file_reader module, which provides a unified API for reading in any file (but calls iotbx.reflection_file_reader.any_reflection_file internally). Currently, the supported formats include:

  • CIF: Crystallographic Information Format, the common syntax for specifying most structured data encountered in crystallography (but more widely used in small-molecule versus macromolecular crystallography), usually as ASCII text. May encapsulate a variety of other data types, but only reflection data (of any type) is handled by this particular module. Uses iotbx.cif internally.

  • MTZ: Binary file format established by CCP4 capable of storing any numerical data, and used by most major macromolecular crystallography software packages. Because of its speed and broad compatibility, this is the primary interchange format for reflection data in Phenix. Uses iotbx.mtz internally.

  • Scalepack: Fixed-format ASCII text produced by the program of the same name and the HKL2000 graphical interface. This is actually two separate formats: one for merged intensities (with or without Friedel mates), another for unmerged intensities and associated processing metadata. Uses either iotbx.scalepack.merge or iotbx.scalepack.no_merge_original_index internally.

  • CNS: ASCII format, not as flexible as MTZ or CIF but able to store either amplitudes or intensities, R-free flags, and Hendrickson-Lattman coefficients. Uses iotbx.cns.reflection_reader internally.

  • SHELX: Fixed-format ASCII used by the eponymous software suite. This format has significan disadvantages, discussed below. Uses iotbx.shelx.hklf internally.

  • XDS: ASCII format for processed intensities (both merged and unmerged). Uses iotbx.xds.read_ascii internally.

  • D*Trek: ASCII format produced by software sold by Rigaku.

Independently, the cctbx.miller.array class defines output methods for CIF, MTZ, CNS, SHELX, and unmerged Scalepack files (although only the first two are recommended for routine use).

Note that the underlying formats do not always contain complete information about the crystal or even the data type. SHELX format is especially problematic as it not only omits crystal symmetry, but the same format may be used to store either amplitudes or intensities, without any distinguishing features. As a crude workaround for the latter problem, the data type may be specified as part of the file name:

hkl_file = any_reflection_file("data.hkl=hklf4")
hkl_file = any_reflection_file("data.hkl=intensities")

Other formats (CNS, unmerged Scalepack) may have incomplete or missing crystal symmetry. MTZ, XDS, and (usually) CIF files will be more complete.

class iotbx.reflection_file_reader.any_reflection_file(file_name, ensure_read_access=True, strict=True)

Bases: object

Proxy object for reading a reflection file of unspecified format, and extracting the Miller arrays contained therein.

Examples

>>> from iotbx.reflection_file_reader import any_reflection_file
>>> hkl_file = any_reflection_file("data.mtz")
>>> print hkl_file.file_type()
'ccp4_mtz'
>>> print type(hkl_file.file_content())
<class 'iotbx_mtz_ext.object'>
>>> miller_arrays = hkl_file.as_miller_arrays()
as_miller_arrays(crystal_symmetry=None, force_symmetry=False, merge_equivalents=True, base_array_info=None, assume_shelx_observation_type_is=None, enforce_positive_sigmas=False, anomalous=None, reconstruct_amplitudes=True)

Convert the contents of the reflection file into a list of cctbx.miller.array objects, each of which may contain multiple columns of data from the underlying file. By default this will automatically merge redundant observations to obtain a unique set under symmetry.

Parameters:

  • crystal_symmetry – cctbx.crystal.symmetry object (defaults to using internally specified symmetry, if any)

  • force_symmetry – TODO

  • merge_equivalents – merge redundant obervations (default=True)

  • base_array_info – cctbx.miller.array_info object containing basic information to be propagated to the arrays

  • assume_shelx_observation_type_is – if specified, instead of raising an exception if the SHELX file type is not known from the file name plus data type tag, the function will force the specified data type.

  • reconstruct_amplitudes – ignored by all other readers than mtz reader. If set to True mean amplitudes and adjacent anomalous diffference columns will be fused into anomalous miller_array object. If False, tells the reader not to fuse mean amplitude and adjacent anomalous difference columns into anomalous miller_array objects.

file_content()

Return the underlying format-specific object.

file_name()

Returns the file name.

file_type()

Return a string specifying the format type (e.g. ‘ccp4_mtz’).

iotbx.reflection_file_reader.collect_arrays(file_names, crystal_symmetry, force_symmetry, merge_equivalents=True, discard_arrays=False, verbose=2, report_out=None)
iotbx.reflection_file_reader.run(args)
iotbx.reflection_file_reader.try_all_readers(file_name)
iotbx.reflection_file_reader.unpickle_miller_arrays(file_name)