Supporting Data mmcif_img.dic

Dictionary Revision History

Version Revision Date Revision Description
0.1 1997-01-24
First draft of this dictionary in DDL 2.1 compliant format by John
Westbrook (JW). This version is adapted from the Crystallographic
Binary File (CBF) Format Draft Proposal provided by Andy Hammersley

Modifications to the CBF draft. (JW)

+ In this version the array description has been cast in the categories
have been generalized to describe array data of arbitrary dimension.

+ Array data in this description are contained in the category
ARRAY_DATA. This departs from the CBF notion of data existing
in some special comment. In this description, data are handled as an
ordinary data item encapsulated in a character data type. Although
data this manner deviates from CIF conventions, it does not violate
any DDL 2.1 rules. DDL 2.1 regular expressions can be used to define
the binary representation which will permit some level of data
validation. In this version, the placeholder type code "any" has
been used. This translates to a regular expression which will match
any pattern.

It should be noted that DDL 2.1 already supports array data objects
although these have not been used in the current mmCIF dictionary.
It may be possible to use the DDL 2.1 ITEM_STRUCTURE and
ITEM_STRUCTURE_LIST categories to provide the information that is
moving the array structure to the DDL level it would be possible to
define an array type as well as a regular expression defining the
data format.

+ Multiple array sections can be properly handled within a single
0.2 1997-12-02
Modifications to the CBF draft. (JW)

+ Add category hierarchy for describing frame data developed from
discussions at the BNL imgCIF Workshop Oct 1997. The following
changes are made in implementing the workshop draft. Category
DIFFRN_array_data is renamed to DIFFRN_FRAME_DATA. Category
parent item for '_diffrn_frame_data.array_id' is changed from
'_array_structure_list.array_id' to ''. Item
'_diffrn_detector.array_id' is deleted.
+ Add data item '_diffrn_frame_data.binary_id' to identify data
groups within a binary section. The formal identification of the
binary section is still fuzzy.
0.3 1998-07-04
Modifications for imgCIF. (HJB)

+ Add binary type, which is a text field containing a variant on
MIME encoded data.

+ Change type of '' to binary and specify internal
structure of raw binary data.

+ Add '_array_data.binary_id', and make
'_diffrn_frame_data.binary_id' and '_array_intensities.binary_id'
into pointers to this item.
0.4 1998-08-11
Modifications to the 0.3 imgCIF draft. (HJB)

+ Reflow comment lines over 80 characters and corrected typos.

+ Update examples and descriptions of MIME encoded data.

+ Change name to cbfext98.dic.
0.5 1999-01-01
Modifications for axis definitions and reduction of binary header. (HJB)

+ Restore '_diffrn_detector.diffrn_id' to DIFFRN_DETECTOR KEY.

+ Add AXIS category.

+ Bring in complete DIFFRN_DETECTOR and DIFFRN_MEASUREMENT categories
from cif_mm.dic for clarity.

+ Change '_array_structure.encoding_type' from type code to uline and
added X-Binary-Element-Type to MIME header.

+ Add detector beam centre '[1]' and

+ Correct item name of '_diffrn_refln.frame_id'.

+ Replace reference to '_array_intensities.undefined' by

+ Replace references to '_array_intensity.scaling' with

+ Add DIFFRN_SCAN... categories.
0.5.1 1999-01-03
Cleanup of typos and syntax errors. (HJB)

+ Cleanup example details for DIFFRN_SCAN category.

+ Add missing quote marks for '' definition.
0.6.0 1999-01-14
Remove redundant information for ENC_NONE data. (HJB)

+ After the D5 remove binary section identifier, size and
compression type.

+ Add Control-L to header.
0.7.0 2000-09-09
Respond to comments by I. David Brown. (HJB)

+ Add further comments on '\n' and '\t'.

+ Update ITEM_UNITS_LIST by taking section from mmCIF dictionary
and adding metres. Change 'meter' to 'metre' throughout.

+ Add missing enumerations to '_array_structure.compression_type'
and make 'none' the default.

+ Remove parent-child relationship between
'_array_structure_list.index' and '_array_structure_list.precedence'.

+ Improve alphabetization.

+ Fix '_array_intensities.gain_esd' related function.

+ Improve comments in AXIS.

+ Fix DIFFRN_FRAME_DATA example.

+ Remove erroneous DIFFRN_MEASUREMENT example.

+ Add '' to the category key.
0.7.1 2000-09-29
Cleanup fixes. (JW)

+ Correct spelling of DIFFRN_MEASUREMENT_AXIS in ''

+ Correct ordering of uses of '_item.mandatory_code' and
1.0 2000-12-21
Release version - few typos and tidying up. (BM & HJB)

of dictionary.

+ Alphabetize dictionary.
1.1 2001-02-06
Draft resulting from discussions on header for use at NSLS. (HJB)


+ Change '' to '_diffrn_detector_axis.detector_id'.

+ Add '_diffrn_measurement_axis.measurement_device' and change
'' to

+ Add '_diffrn_radiation.div_x_source', '_diffrn_radiation.div_y_source',
'_diffrn_radiation.polarizn_source_ratio', '_diffrn_scan.date_end',
'_diffrn_scan.date_start', '_diffrn_scan_axis.angle_rstrt_incr',

+ Add '_diffrn_measurement.device' to category key.

+ Update yyyy-mm-dd to allow optional time with fractional seconds
for time stamps.

+ Fix typos caught by RS.

+ Add ARRAY_STRUCTURE_LIST_AXIS category, and use concept of axis sets to
allow for coupled axes, as in spiral scans.

+ Add examples for fairly complete headers thanks to R. Sweet and P.
1.1.1 2001-02-16
Several typo corrections by JW.
1.1.2 2001-03-06
Several typo corrections by Wilfred Li.
1.1.3 2001-04-19
Another typo corrections by Wilfred Li, and cleanup by HJB.
1.2 2003-02-07
Corrections to encodings (remove extraneous hyphens) remove
extraneous underscore in '_array_structure.encoding_type'
enumeration. Correct typos in items units list. (HJB)
1.2.1 2003-02-22
Correction of ATOM_ for ARRAY_ typos in various descriptions.
1.2.2 2003-03-10
Correction of typos in various DIFFRN_SCAN_AXIS descriptions.
1.2.3 2003-07-03
Cleanup to conform to ITVG.
+ Correct sign error in ..._cubed units.
+ Correct '_diffrn_radiation.polarisn_norm' range.
1.2.4 2003-07-14
Changes as per I. David Brown.
+ Enhance descriptions in DIFFRN_SCAN_AXIS to make them less
dependent on the descriptions in DIFFRN_SCAN_FRAME_AXIS.
+ Provide a copy of the deprecated DIFFRN_FRAME_DATA
category for completeness.
1.3.0 2003-07-24
Changes as per Brian McMahon.
+ Consistently quote tags embedded in text.
+ Clean up introductory comments.
+ Adjust line lengths to fit in 80 character window.
+ Fix several descriptions in AXIS category which
referred to '_axis.type' instead of the current item.
+ Fix erroneous use of deprecated item
'' in examples for
+ Add deprecated items ''
and ''.
1.3.1 2003-08-13
Changes as per Frances C. Bernstein.
+ Identify initials.
+ Adopt British spelling for centre in text.
+ Set \p and \%Angstrom and powers.
+ Clean up commas and unclear wordings.
+ Clean up tenses in history.
Changes as per Gotzon Madariaga.
+ Fix the ARRAY_DATA example to align '_array_data.binary_id'
and X-Binary-ID.
+ Add a range to '_array_intensities.gain_esd'.
+ In the example of DIFFRN_DETECTOR_ELEMENT,
'' and
'_diffrn_detector_element.detector_id' interchanged.
+ Fix typos for direction, detector and axes.
+ Clarify description of polarisation.
+ Clarify axes in '[1]'
+ Add local item types for items that are pointers.
1.3.2 2005-06-25 2005-06-25 ITEM_TYPE_LIST: code, ucode, line, uline regexps updated
to those of current mmCIF; float modified by allowing integers
terminated by a point as valid. The 'time' part of
yyyy-mm-dd types made optional in the regexp. (BM)

2005-06-17 Minor corrections as for proofs for IT G Chapter 4.6

2005-02-21 Minor corrections to spelling and punctuation

2005-01-08 Changes as per Nicola Ashcroft.
+ Updated example 1 for DIFFRN_MEASUREMENT to agree with mmCIF.
+ Spelled out "micrometres" for "um" and "millimetres" for "mm".
+ Removed phrase "which may be stored" from ARRAY_STRUCTURE
+ Removed unused 'byte-offsets' compressions and updated
cites to ITVG for '_array_structure.compression_type'.
1.4 2006-07-04 This is a change to reintegrate all changes made in the course of
publication of ITVG, by the RCSB from April 2005 through
August 2008 and changes for the 2006 imgCIF workshop in

2006-07-04 Consolidated changes for the 2006 imgCIF workshop (edited by HJB)
+ Correct type of '_array_structure_list.direction' from 'int' to 'code'.
+ Added new data items suggested by CN
'_array_intensities.pixel_slow_bin_size and
+ Added deprecated item for completeness
+ Added entry for missing item in contents list
+ Added new MIME type X-BASE32K based on work by VL, KM, GD, HJB
+ Correct description of MIME boundary delimiter to start in
column 1.
+ General cleanup of text fields to conform to changes for ITVG
by removing empty lines at start and finish of text field.
+ Amend example for ARRAY_INTENSITIES to include binning.
+ Add local copy of type specification (as 'code') for all children
of ''.
+ For consistency, change all references to 'pi' to '\p' and all
references to 'Angstroms' to '\%Angstroms'.
+ Clean up all powers to use IUCr convention of '^power^', as in
'10^3^' for '10**3'.
+ Update 'yyyy-mm-dd' type regex to allow truncation from the right
and improve comments to explain handling of related mmCIF
'yyyy-mm-dd:hh:mm' type, and use of 'Z' for GMT time zone.

2005-03-08 and
2004-08-08 fixed cases where _item_units.code used
instead of _item_type.code (JDW)
2004-04-15 fixed item ordering in
added sub_category 'vector' (JDW)
1.5 2007-07-25 This is a cummulative list of the changes proposed since the
imgCIF workshop in Hawaii in July 2006. It is the result
of contributions by H. J. Bernstein, A. Hammersley,
J. Wright and W. Kabsch.

2007-02-19 Consolidated changes (edited by HJB)
+ Added new data items
'_map.details', '_map.diffrn_id',
'_map.entry_id', '',
'_map_segment.array_id', '_map_segment.binary_id',
'_map_segment.mask_array_id', '_map_segment.mask_binary_id',
'', '_map_segment.map_id',
+ Change type of
'_array_structure.byte_order' and
to ucode to make these values case-insensitive
+ Add values 'packed_v2' and 'byte_offset' to enumeration of values for
+ Add to definitions for the binary data type to handle new compression
types, maps, and a variety of new axis types.
2007-07-25 Cleanup of typos for formal release (HJB)
+ Corrected text fields for reference_ tag descriptions that
were off by one column
+ Fix typos in comments listing fract_ tags
+ Changed name of release from 1.5_DRAFT to 1.5
+ Fix unclosed text fields in various map definitions
1.5.1 2007-04-26 Improve defintion of X-axis to cover the case of no goniometer
and clean up more line folds (HJB)
1.5.2 2007-05-06 Further clarifications of the coordinate system. (HJB) mmcif_img.dic
1.5.3 2007-07-08 Changes to support SLS miniCBF and suggestions
from the 24 May 07 BNL imgCIF workshop (HJB)

+ Added new data items
+ Deprecated data items
+ Added comments and example on miniCBF
+ Changed all array_id data items to implicit
1.5.4 2007-07-28 Typographics corrections (HJB)

+ Corrected embedded degree characters to \%
+ Corrected embedded Aring to \%A
+ Added trailing ^ for a power
+ Removed 2 cases of a space after an underscore
in tag name.
1.6.3 2010-08-26 Cummulative corrections from 1.6.0, 1, 2 drafts (HJB)

+ Move descriptive dictionary comments into
_datablock.description with catgeory tree described
+ add default _array_data.array_id value of 1
+ add option of CBF_BACKGROUND_OFFSET_DELTA compression
+ add VARIANT category and tags
1.6.4 2011-07-02 Corrections to support DLS Dectris header as per G. Winter (HJB)

+ Define new tags _diffrn_scan.time_period,
+ fix bad category name in loop in
+ remove stray text field terminator at line 4642
+ fix unquoted tag as a value in
+ make formerly mandatory and implicit deprecated items non-mandatory
1.7 2013-06-18 Additions to start merge of CBF, HDF5 and NeXus (HJB)

+ Add new _category.NX_mapping_details DDL tag to carry
details on NeXus category mappings.
+ Define new tags _array_structure_list_section.array_id,,
1.7.1 2013-08-10 Minor cleanup (HJB)

+ Correction to description of
+ Change NXgoniometer to NXsample
+ Fix typos in NeXus mappings
1.7.2 2013-10-07 Add FEL detector positioning tags and change back to NXgoniometer

+ Add
_axis.rotation_axis and
_axis.rotation and
+ Change NXsample back to NXgoniometer
1.7.3 2013-10-15 Major cleanup of dictionary typos, misplaced loops, etc
by John Westbrook

+ Change _item.mandatory_code of all *.variant to implicit
+ Add and _diffrn_refln.diffrn_id
+ Correct many values that were wrong or missing
quote marks
1.7.4 2013-10-23 Minor cleanup and rmeove spurious tag

+ remove spurious _array_structure_list_section.array_set_id
references. (JS)
+ Change case of category names to conform to PDB conventions. (JW)
1.7.5 2013-10-27 At request of JW for the PDB move _category.NX_mapping_details
to be adjacent to other category tags. (HJB)
1.7.6 2013-10-29 To avoid a conflict with PDB software, remove the null value
enumeration for _variant.role (HJB)
1.7.7 2014-02-22 Major changes to NeXus mapping to conform to JS functional
mapping prototype, add Stoke parameter tags for polarization
and beam intensity, and add an new tag for FEL axes (HJB)

+ Add
+ Remove erroneous type code from _diffrn_scan_frame_monitor.value.
+ Update dictionary version
1.7.8 2014-02-22 Minor changes to NeXus mapping. (HJB)

+ Conform NeXus mapping of DIFFRN_DETECTOR to neXus
NXdetector base class terminology

+ Add _diffrn_detector.gain_setting to handle
the reverse mapping fron NeXus of the equivalent field in NXdetector.
Data Type Code Primitive Type Code Regular Expression Description
any char .* A catch all for items that may take any form...
binary char \n--CIF-BINARY-FORMAT-SECTION--\n\
[][ \n\t()_,.;:"&<>/\{}'`~!@#$%?+=*A-Za-z0-9|^-]*\
binary items are presented as MIME-like ascii-encoded
sections in an imgCIF. In a CBF, raw octet streams
are used to convey the same information.
code char [_,.;:"&<>()/\{}'`~!@#$%A-Za-z0-9*|+-]* code item types/single words ...
float numb -?(([0-9]+)[.]?|([0-9]*[.][0-9]+))([(][0-9]+[)])?([eE][+-]?[0-9]+)? float item types are the subset of numbers that are the floating
point numbers.
int numb -?[0-9]+ int item types are the subset of numbers that are the negative
or positive integers.
line char [][ \t_(),.;:"&<>/\{}'`~!@#$%?+=*A-Za-z0-9|^-]* char item types / multi-word items ...
text char [][ \n\t()_,.;:"&<>/\{}'`~!@#$%?+=*A-Za-z0-9|^-]* text item types / multi-line text ...
ucode uchar [_,.;:"&<>()/\{}'`~!@#$%A-Za-z0-9*|+-]* code item types/single words (case insensitive) ...
uline uchar [][ \t_(),.;:"&<>/\{}'`~!@#$%?+=*A-Za-z0-9|^-]* char item types / multi-word items (case insensitive)...
yyyy-mm-dd char \

Standard format for CIF date and time strings (see,
consisting of a yyyy-mm-dd date optionally followed by
the character 'T' followed by a 24-hour clock time,
optionally followed by a signed time-zone offset.

The IUCr standard has been extended to allow for an optional
decimal fraction on the seconds of time.

Time is local time if no time-zone offset is given.

Note that this type extends the mmCIF yyyy-mm-dd type
but does not conform to the mmCIF yyyy-mm-dd:hh:mm
type that uses a ':' in place if the 'T' specified
by the IUCr standard. For reading, both forms should
be accepted, but for writing, only the IUCr form should
be used.

For maximal compatibility, the special time zone
indicator 'Z' (for 'zulu') should be accepted on
reading in place of '+00:00' for GMT.
SubCategory Identifier Description
matrix The collection of elements of a matrix.
vector The collection of elements of a vector.
Units Identifier Description
8pi2_angstroms_squared 8\p2 * \%Angstroms squared (metres * 10(-10))2
angstroms \%Angstroms (metres * 10(-10))
angstroms_cubed \%Angstroms cubed (metres * 10(-10))3
angstroms_squared \%Angstroms squared (metres * 10(-10))2
arbitrary arbitrary system of units.
celsius degrees (of temperature) Celsius
centimetres centimetres (metres * 10( -2))
counts counts
counts_per_photon counts per photon
degrees degrees (of arc)
degrees_per_minute degrees (of arc) per minute
degrees_squared degrees (of arc) squared
electrons electrons
electrons_per_angstroms_cubed electrons per \%Angstroms cubed (electrons/(metres * 10(-10))(-3))
electrons_per_nanometres_cubed electrons per nanometres cubed (electrons/(metres * 10( -9))(-3))
electrons_per_picometres_cubed electrons per picometres cubed (electrons/(metres * 10(-12))(-3))
electrons_squared electrons squared
femtometres femtometres (metres * 10(-15))
gigapascals gigapascals
hours hours
kelvins degrees (of temperature) Kelvin
kilopascals kilopascals
kilovolts kilovolts
kilowatts kilowatts
metres metres
microseconds microseconds
milliamperes milliamperes
millimetres millimetres (metres * 10( -3))
minutes minutes
nanometres nanometres (metres * 10( -9))
nanometres_cubed nanometres cubed (metres * 10( -9))3
nanometres_squared nanometres squared (metres * 10( -9))2
picometres picometres (metres * 10(-12))
picometres_cubed picometres cubed (metres * 10(-12))3
picometres_squared picometres squared (metres * 10(-12))2
pixels_per_element (image) pixels per (array) element
reciprocal_angstroms reciprocal \%Angstroms ((metres * 10(-10))(-1))
reciprocal_centimetres reciprocal centimetres ((metres * 10( -2))(-1))
reciprocal_metres reciprocal metres (metres(-1))
reciprocal_millimetres reciprocal millimetres ((metres * 10( -3))(-1))
reciprocal_nanometres reciprocal nanometres ((metres * 10( -9))(-1))
reciprocal_picometres reciprocal picometres ((metres * 10(-12))(-1))
seconds seconds

Units Conversion List

From Units&Identifier To Units&Identifier Operator Conversion Factor
metres centimetres * 1.0E+02
metres millimetres * 1.0E+03
metres nanometres * 1.0E+09
metres angstroms * 1.0E+10
metres picometres * 1.0E+12
metres femtometres * 1.0E+15
centimetres metres * 1.0E-02
centimetres millimetres * 1.0E+01
centimetres nanometres * 1.0E+07
centimetres angstroms * 1.0E+08
centimetres picometres * 1.0E+10
centimetres femtometres * 1.0E+13
millimetres metres * 1.0E-03
millimetres centimetres * 1.0E-01
millimetres nanometres * 1.0E+06
millimetres angstroms * 1.0E+07
millimetres picometres * 1.0E+09
millimetres femtometres * 1.0E+12
nanometres metres * 1.0E-09
nanometres centimetres * 1.0E-07
nanometres millimetres * 1.0E-06
nanometres angstroms * 1.0E+01
nanometres picometres * 1.0E+03
nanometres femtometres * 1.0E+06
angstroms metres * 1.0E-10
angstroms centimetres * 1.0E-08
angstroms millimetres * 1.0E-07
angstroms nanometres * 1.0E-01
angstroms picometres * 1.0E+02
angstroms femtometres * 1.0E+05
picometres metres * 1.0E-12
picometres centimetres * 1.0E-10
picometres millimetres * 1.0E-09
picometres nanometres * 1.0E-03
picometres angstroms * 1.0E-02
picometres femtometres * 1.0E+03
femtometres metres * 1.0E-15
femtometres centimetres * 1.0E-13
femtometres millimetres * 1.0E-12
femtometres nanometres * 1.0E-06
femtometres angstroms * 1.0E-05
femtometres picometres * 1.0E-03
reciprocal_centimetres reciprocal_metres * 1.0E+02
reciprocal_centimetres reciprocal_millimetres * 1.0E-01
reciprocal_centimetres reciprocal_nanometres * 1.0E-07
reciprocal_centimetres reciprocal_angstroms * 1.0E-08
reciprocal_centimetres reciprocal_picometres * 1.0E-10
reciprocal_millimetres reciprocal_metres * 1.0E+03
reciprocal_millimetres reciprocal_centimetres * 1.0E+01
reciprocal_millimetres reciprocal_nanometres * 1.0E-06
reciprocal_millimetres reciprocal_angstroms * 1.0E-07
reciprocal_millimetres reciprocal_picometres * 1.0E-09
reciprocal_nanometres reciprocal_metres * 1.0E+09
reciprocal_nanometres reciprocal_centimetres * 1.0E+07
reciprocal_nanometres reciprocal_millimetres * 1.0E+06
reciprocal_nanometres reciprocal_angstroms * 1.0E-01
reciprocal_nanometres reciprocal_picometres * 1.0E-03
reciprocal_angstroms reciprocal_metres * 1.0E+10
reciprocal_angstroms reciprocal_centimetres * 1.0E+08
reciprocal_angstroms reciprocal_millimetres * 1.0E+07
reciprocal_angstroms reciprocal_nanometres * 1.0E+01
reciprocal_angstroms reciprocal_picometres * 1.0E-02
reciprocal_picometres reciprocal_metres * 1.0E+12
reciprocal_picometres reciprocal_centimetres * 1.0E+10
reciprocal_picometres reciprocal_millimetres * 1.0E+09
reciprocal_picometres reciprocal_nanometres * 1.0E+03
reciprocal_picometres reciprocal_angstroms * 1.0E+01
nanometres_squared angstroms_squared * 1.0E+02
nanometres_squared picometres_squared * 1.0E+06
angstroms_squared nanometres_squared * 1.0E-02
angstroms_squared picometres_squared * 1.0E+04
angstroms_squared 8pi2_angstroms_squared * 78.9568
picometres_squared nanometres_squared * 1.0E-06
picometres_squared angstroms_squared * 1.0E-04
nanometres_cubed angstroms_cubed * 1.0E+03
nanometres_cubed picometres_cubed * 1.0E+09
angstroms_cubed nanometres_cubed * 1.0E-03
angstroms_cubed picometres_cubed * 1.0E+06
picometres_cubed nanometres_cubed * 1.0E-09
picometres_cubed angstroms_cubed * 1.0E-06
kilopascals gigapascals * 1.0E-06
gigapascals kilopascals * 1.0E+06
hours minutes * 6.0E+01
hours seconds * 3.6E+03
hours microseconds * 3.6E+09
minutes hours / 6.0E+01
minutes seconds * 6.0E+01
minutes microseconds * 6.0E+07
seconds hours / 3.6E+03
seconds minutes / 6.0E+01
seconds microseconds * 1.0E+06
microseconds hours / 3.6E+09
microseconds minutes / 6.0E+07
microseconds seconds / 1.0E+06
celsius kelvins - 273.0
kelvins celsius + 273.0
electrons_per_nanometres_cubed electrons_per_angstroms_cubed * 1.0E+03
electrons_per_nanometres_cubed electrons_per_picometres_cubed * 1.0E+09
electrons_per_angstroms_cubed electrons_per_nanometres_cubed * 1.0E-03
electrons_per_angstroms_cubed electrons_per_picometres_cubed * 1.0E+06
electrons_per_picometres_cubed electrons_per_nanometres_cubed * 1.0E-09
electrons_per_picometres_cubed electrons_per_angstroms_cubed * 1.0E-06