############################################################################## # # # DDL 2.1 Compliant # # mmCIF Binary File Extension Dictionary # # # # Version of 1997-01-24 # # # # Adapted from the # # # # imgCIF Workshop, BNL Oct 1997 # # # # and # # # # Crystallographic Binary File Format Draft Proposal # # by Andy Hammersley # # # # # ############################################################################## # # # DDL 2.1 Version # # by # # John Westbrook # # Nucleic Acid Database # # Rutgers University # # # # HTML version available at: # # http://ndbserver.rutgers.edu/NDB/mmcif/dictionary/dict-html/cbfext97/Index/# # # ############################################################################## data_cbfext97.dict _dictionary.title cbfext97.dict _dictionary.version 0.2 _dictionary.datablock_id cbfext97.dict #################### ## ITEM_TYPE_LIST ## #################### # # # The regular expressions defined here are not compliant # with the POSIX 1003.2 standard as they include the # '\n' and '\t' special characters. These regular expressions # have been tested using the version 0.12 of Richard Stallman's # GNU regular expression libary in POSIX mode. # loop_ _item_type_list.code _item_type_list.primitive_code _item_type_list.construct _item_type_list.detail code char '[_,.;:"&<>/\{}'`~!@#$%A-Za-z0-9*|+-]*' ; code item types/single words ... ; text char '[][ \n\t()_,.;:"&<>/\{}'`~!@#$%?+=*A-Za-z0-9|^-]*' ; text item types / multi-line text ... ; int numb '-?[0-9]+' ; int item types are the subset of numbers that are the negative or positive integers. ; float numb '-?(([0-9]+)|([0-9]*[.][0-9]+))([(][0-9]+[)])?([eE][+-]?[0-9]+)?' ; int item types are the subset of numbers that are the floating numbers. ; any char '.*' ; A catch all for items that may take any form... ; ##################### ## ITEM_UNITS_LIST ## ##################### loop_ _item_units_list.code _item_units_list.detail 'meters' . ######################### ## CATEGORY_GROUP_LIST ## ######################### loop_ _category_group_list.id _category_group_list.parent_id _category_group_list.description 'inclusive_group' . ; Categories that belong to the dictionary extension. ; 'array_data_group' 'inclusive_group' ; Categories that describe array data. ; 'diffrn_group' 'inclusive_group' ; Categories that describe details of the diffraction experiment. ; ######################## ## DICTIONARY_HISTORY ## ######################## loop_ _dictionary_history.version _dictionary_history.update _dictionary_history.revision 0.2 1997-12-02 ; Modifications to the CBF draft (JW): + Added category heirarchy for describing frame data developed from discussions at the BNL imgCIF Workshop Oct 1997. The following changes were made in implementing the workshop draft. Category DIFFRN_ARRAY_DATA was renamed to DIFFRN_FRAME_DATA. Category DIFFRN_FRAME_TYPE was renamed to DIFFRN_DETECTOR_ELEMENT. The parent item for _diffrn_frame_data.array_id was changed from array_structure_list.array_id to array_structure.id. Item _diffrn_detector.array_id was deleted. + Added 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.1 1997-01-24 ; First draft of this dictionary in DDL 2.1 compliant format by John Westbrook (JW). This version was adapted from the Crystallographic Binary File (CBF) Format Draft Proposal provided by Andy Hammersley (AH). Modifications to the CBF draft (JW): + In this version the array description has been cast in the categories ARRAY_STRUCTURE and ARRAY_STRUCTURE_LIST. These categories have been generalized to describe array data of arbitrary dimension. + Array data in this description is contained in the category ARRAY_DATA. This departs from the CBF notion of data existing in some special comment. In this description, data is handled as an ordinary data item encapsulated in a character data type. Although, handling binary 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 carried in by the ARRAY_STRUCTURE and ARRAY_STRUCTURE_LIST. By 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 datablock. ; ############## # ARRAY_DATA # ############## save_ARRAY_DATA _category.description ; Data items in the ARRAY_DATA category are the containers for the array data items described in category ARRAY_STRUCTURE. ; _category.id array_data _category.mandatory_code no _category_key.name '_array_data.array_id' loop_ _category_group.id 'inclusive_group' 'array_data_group' loop_ _category_examples.detail _category_examples.case ; Example 1: ; ; loop_ _array_data.array_id _array_data.data image_1 ; 0A1239872398479A2983487A1098234140A1239872398479A2983487A10... 9872398479A2983487A1098234140A1239872398479A2983487A1098002... ... ; image_2 ; 0A12FF39872398479A2983FF487A10BAF98234147A10BAF98234147A103... 9872398479A2983487A1098234140A1239872398479A2983487A1098002... ... ; ; save_ save__array_data.array_id _item_description.description ; This item is a pointer to _array_structure.id in the ATOM_STRUCTURE category. ; _item.name '_array_data.array_id' _item.category_id array_data _item.mandatory_code yes _item_type.code code save_ save__array_data.data _item_description.description ; The value of _array_data.data contains the array data encapulated in a STAR string. ; _item.name '_array_data.data' _item.category_id array_data _item.mandatory_code yes _item_type.code any save_ ################### # ARRAY_STRUCTURE # ################### save_ARRAY_STRUCTURE _category.description ; Data items in the ARRAY_STRUCTURE category record the organization and encoding of array data which may be stored in the ARRAY_DATA category. ; _category.id array_structure _category.mandatory_code no _category_key.name '_array_structure.id' loop_ _category_group.id 'inclusive_group' 'array_data_group' loop_ _category_examples.detail _category_examples.case ; Example 1: ; ; Add example here ; save_ save__array_structure.id _item_description.description ; The value of _array_structure.id must uniquely identify each item of array data. ; loop_ _item.name _item.category_id _item.mandatory_code '_array_structure.id' array_structure yes '_array_data.array_id' array_data yes '_array_structure_list.array_id' array_structure_list yes '_array_intensities.array_id' array_intensities yes '_diffrn_frame_data.array_id' diffrn_frame_data yes _item_type.code code loop_ _item_linked.child_name _item_linked.parent_name '_array_data.array_id' '_array_structure.id' '_array_structure_list.array_id' '_array_structure.id' '_array_intensities.array_id' '_array_structure.id' '_diffrn_frame_data.array_id' '_array_structure.id' save_ save__array_structure.byte_order _item_description.description ; The order of bytes for integer values which require more than 1-byte. (IBM-PC's and compatiables, and Dec-Vaxes use low byte first ordered integers, whereas Hewlett Packard 700 series, Sun-4, and Silicon Graphics use high byte first ordered integers. Dec-Alphas can produce/use either depending on a compiler switch.) ; _item.name '_array_structure.byte_order' _item.category_id array_structure _item.mandatory_code yes _item_type.code code loop_ _item_enumeration.value _item_enumeration.detail 'big_endian' ; The first byte in the byte stream of the bytes which make up an integer value is the most significant byte of an integer. ; 'little_endian' ; The last byte in the byte stream of the bytes which make up an integer value is the most significant byte of an integer. ; save_ save__array_structure.compression_type _item_description.description ; Type of data compression method used to compress the array data. ; _item.name '_array_structure.compression_type' _item.category_id array_structure _item.mandatory_code no _item_type.code code loop_ _item_enumeration.value _item_enumeration.detail 'none' ; Data are stored in normal format as defined by _array_structure.encoding_type and _array_structure.byte_order. ; 'byte_offsets' ; Using the compression scheme defined in Section 5.0. ; save_ save__array_structure.encoding_type _item_description.description ; Data encoding of a single element of array data. ; _item.name '_array_structure.encoding_type' _item.category_id array_structure _item.mandatory_code yes _item_type.code code loop_ _item_enumeration.value 'unsigned_8_bit_integer' 'signed_8_bit_integer' 'unsigned_16_bit_integer' 'signed_16_bit_integer' 'unsigned_32_bit_integer' 'signed_32_bit_integer' '32_bit_real_ieee' '64_bit_real_ieee' '32_bit_complex_ieee' save_ ######################## # ARRAY_STRUCTURE_LIST # ######################## save_ARRAY_STRUCTURE_LIST _category.description ; Data items in the ARRAY_STRUCTURE_LIST category record the size and organization of each array dimension. ; _category.id array_structure_list _category.mandatory_code no loop_ _category_key.name '_array_structure_list.array_id' '_array_structure_list.index' loop_ _category_group.id 'inclusive_group' 'array_data_group' loop_ _category_examples.detail _category_examples.case ; Example 1: An image array of 1300 x 1200 elements. The raster order of the image is left-to-right (increasing) in first dimension and bottom-to-top (decreasing) in the second dimension. ; ; loop_ _array_structure_list.array_id _array_structure_list.index _array_structure_list.dimension _array_structure_list.precedence _array_structure_list.direction image_1 1 1300 1 increasing image_1 2 1200 2 decreasing ; save_ save__array_structure_list.array_id _item_description.description ; This item is a pointer to _array_structure.id in the ATOM_STRUCTURE category. ; _item.name '_array_structure_list.array_id' _item.category_id array_structure_list _item.mandatory_code yes _item_type.code code save_ save__array_structure_list.dimension _item_description.description ; The number of elements stored in the array structure in this dimension. ; _item.name '_array_structure_list.dimension' _item.category_id array_structure_list _item.mandatory_code yes _item_type.code int loop_ _item_range.maximum _item_range.minimum 1 1 . 1 save_ save__array_structure_list.index _item_description.description ; Identifies the one-based index of the row or column in the array structure. ; loop_ _item.name _item.category_id _item.mandatory_code '_array_structure_list.index' array_structure_list yes '_array_structure_list.precedence' array_structure_list yes '_array_element_size.index' array_element_size yes _item_type.code int loop_ _item_linked.child_name _item_linked.parent_name '_array_structure_list.precedence' '_array_structure_list.index' '_array_element_size.index' '_array_structure_list.index' loop_ _item_range.maximum _item_range.minimum 1 1 . 1 save_ save__array_structure_list.precedence _item_description.description ; Identifies the rank order in which this array index changes with respect to other array indices. The precedence of 1 indicates the index which changes fastest. This item is a pointer to item _array_structure_list.index. ; _item.name '_array_structure_list.precedence' _item.category_id array_structure_list _item.mandatory_code yes _item_type.code int loop_ _item_range.maximum _item_range.minimum 1 1 . 1 save_ save__array_structure_list.direction _item_description.description ; Identifies the direction in which this array index changes. ; _item.name '_array_structure_list.direction' _item.category_id array_structure_list _item.mandatory_code yes _item_type.code int loop_ _item_enumeration.value _item_enumeration.detail 'increasing' ; Indicates the index changes from 1 to the maximum dimension. ; 'decreasing' ; Indicates the index changes from the maximum dimension to 1. ; save_ ###################### # ARRAY_ELEMENT_SIZE # ###################### save_ARRAY_ELEMENT_SIZE _category.description ; Data items in the ARRAY_ELEMENT_SIZE category record the physical size of array elements along each array dimension. ; _category.id array_element_size _category.mandatory_code no loop_ _category_key.name '_array_element_size.array_id' '_array_element_size.index' loop_ _category_group.id 'inclusive_group' 'array_data_group' loop_ _category_examples.detail _category_examples.case ; Example 1: A regular 2D array with a uniform element dimension of 1220 nanometers. ; ; loop_ _array_element_size.array_id _array_element_size.index _array_element_size.size image_1 1 1.22e-6 image_1 2 1.22e-6 ; save_ save__array_element_size.array_id _item_description.description ; This item is a pointer to _array_structure.id in the ATOM_STRUCTURE category. ; _item.name '_array_element_size.array_id' _item.category_id array_element_size _item.mandatory_code yes _item_type.code code save_ save__array_element_size.index _item_description.description ; This item is a pointer to _array_structure_list.index in the ATOM_STRUCTURE_LIST category. ; _item.name '_array_element_size.index' _item.category_id array_element_size _item.mandatory_code yes _item_type.code code save_ save__array_element_size.size _item_description.description ; The size in meters of an image element in this dimension. This supposes that the elements are arranged on a regular. ; _item.name '_array_element_size.size' _item.category_id array_element_size _item.mandatory_code yes _item_type.code float _item_units.code 'meters' loop_ _item_range.maximum _item_range.minimum . 0.0 save_ ##################### # ARRAY_INTENSITIES # ##################### save_ARRAY_INTENSITIES _category.description ; Data items in the ARRAY_INTENSITIES category record the information required to recover the intensity data from the set of data values stored in the ARRAY_DATA category. ; _category.id array_intensities _category.mandatory_code no _category_key.name '_array_intensities.array_id' loop_ _category_group.id 'inclusive_group' 'array_data_group' loop_ _category_examples.detail _category_examples.case ; Example 1: ; ; loop_ _array_intensities.array_id _array_intensities.linearity _array_intensities.gain _array_intensities.overload _array_intensities.undefined image_1 linear 1.2 655535 0 ; save_ save__array_intensities.array_id _item_description.description ; This item is a pointer to _array_structure.id in the ATOM_STRUCTURE category. ; _item.name '_array_intensities.array_id' _item.category_id array_intensities _item.mandatory_code yes _item_type.code code save_ save__array_intensities.gain _item_description.description ; Detector "gain". The factor by which linearized intensity values should be divided to produce counts. ; _item.name '_array_intensities.gain' _item.category_id array_intensities _item.mandatory_code yes _item_type.code float loop_ _item_range.maximum _item_range.minimum . 0.0 loop_ _item_related.related_name _item_related.function_code '_array_intensities.gain' 'associated_value' save_ save__array_intensities.gain_esd _item_description.description ; The estimated standard deviation in detector "gain". ; _item.name '_array_intensities.gain_esd' _item.category_id array_intensities _item.mandatory_code yes _item_type.code float loop_ _item_related.related_name _item_related.function_code '_array_intensities.gain' 'associated_esd' save_ save__array_intensities.linearity _item_description.description ; The intensity linearity scaling used from raw intensity to the stored element value: 'linear' is obvious 'offset' means that the value defined by '_array_intensities.offset' should be added to each element value. 'scaling' means that the value defined by '_array_intensity.scaling' should be multiplied with each element value. 'scaling_offset' is the combination of the two previous cases, with the scale factor applied before the offset value. 'sqrt_scaled' means that the square root of raw intensities multiplied by '_array_intensity.scaling' is calculated and stored, perhaps rounded to the nearest integer. Thus, linearization involves dividing the stored values by '_array_intensity.scaling' and squaring the result. 'logarithmic_scaled' means that the logarithm based 10 of raw intensities multiplied by '_array_intensity.scaling' is calculated and stored, perhaps rounded to the nearest integer. Thus, linearization involves dividing the stored values by '_array_intensity.scaling' and calculating 10 to the power of this number. ; _item.name '_array_intensities.linearity' _item.category_id array_intensities _item.mandatory_code yes _item_type.code code loop_ _item_enumeration.value _item_enumeration.detail 'linear' . 'offset' ; The value defined by '_array_intensities.offset' should be added to each element value. ; 'scaling' ; The value defined by '_array_intensity.scaling' should be multiplied with each element value. ; 'scaling_offset' ; The combination of the scaling and offset with the scale factor applied before the offset value. ; 'sqrt_scaled' ; The square root of raw intensities multiplied by '_array_intensity.scaling' is calculated and stored, perhaps rounded to the nearest integer. Thus, linearization involves dividing the stored values by '_array_intensity.scaling' and squaring the result. ; 'logarithmic_scaled' ; The logarithm based 10 of raw intensities multiplied by '_array_intensity.scaling' is calculated and stored, perhaps rounded to the nearest integer. Thus, linearization involves dividing the stored values by '_array_intensity.scaling' and calculating 10 to the power of this number. ; save_ save__array_intensities.offset _item_description.description ; Offset value to add to array element values in the manner described by item _array_intensities.linearity. ; _item.name '_array_intensities.offset' _item.category_id array_intensities _item.mandatory_code no _item_type.code float save_ save__array_intensities.scaling _item_description.description ; Multiplicative scaling value to be applied to array data in the manner described by item _array_intensities.linearity. ; _item.name '_array_intensities.scaling' _item.category_id array_intensities _item.mandatory_code no _item_type.code float save_ save__array_intensities.overload _item_description.description ; The saturation intensity level for this data array. ; _item.name '_array_intensities.overload' _item.category_id array_intensities _item.mandatory_code no _item_type.code float save_ save__array_intensities.undefined_value _item_description.description ; A value to be substituted for undefined values in the data array. ; _item.name '_array_intensities.undefined_value' _item.category_id array_intensities _item.mandatory_code no _item_type.code float save_ ##################### # DIFFRN_FRAME_DATA # ##################### save_DIFFRN_FRAME_DATA _category.description ; Data items in the DIFFRN_FRAME_DATA category record the details about each frame of data. A frame may hold ; _category.id diffrn_frame_data _category.mandatory_code no loop_ _category_key.name '_diffrn_frame_data.id' '_diffrn_frame_data.detector_element_id' loop_ _category_group.id 'inclusive_group' 'array_data_group' loop_ _category_examples.detail _category_examples.case ; Example 1: A frame containing data from 4 frame elements. Each frame element has a common array configuration 'array_1' described in ARRAY_STRUCTURE and related categories. The data for each detector element is stored in four sequential groups in a binary section. ; ; loop_ _diffrn_frame_data.id _diffrn_frame_data.detector_element_id _diffrn_frame_data.array_id _diffrn_frame_data.binary_id frame_1 d1_ccd_1 array_1 1 frame_1 d1_ccd_2 array_1 2 frame_1 d1_ccd_3 array_1 3 frame_1 d1_ccd_3 array_1 4 ; save_ save__diffrn_frame_data.array_id _item_description.description ; This item is a pointer to _array_structure.id in the ATOM_STRUCTURE category. ; _item.name '_diffrn_frame_data.array_id' _item.category_id diffrn_frame_data _item.mandatory_code yes _item_type.code code save_ save__diffrn_frame_data.binary_id _item_description.description ; The integer index of this frame in the binary section. ; _item.name '_diffrn_frame_data.binary_id' _item.category_id diffrn_frame_data _item.mandatory_code no _item_type.code int loop_ _item_range.maximum _item_range.minimum 1 1 . 1 save_ save__diffrn_frame_data.detector_element_id _item_description.description ; This item is a pointer to _diffrn_frame_element.id in the DIFFRN_FRAME_ELEMENT category. ; _item.name '_diffrn_frame_data.detector_element_id' _item.category_id diffrn_frame_data _item.mandatory_code yes _item_type.code code save_ save__diffrn_frame_data.id _item_description.description ; The value of _diffrn_frame_data.id must uniquely identify each complete frame of data. ; loop_ _item.name _item.category_id _item.mandatory_code '_diffrn_frame_data.id' diffrn_frame_data yes '_diffrn_refln.frame_id' diffrn_refln yes _item_type.code code loop_ _item_linked.child_name _item_linked.parent_name '_diffrn_refln.frame_id' '_diffrn_frame_data.id' save_ ########################### # DIFFRN_DETECTOR_ELEMENT # ########################### save_DIFFRN_DETECTOR_ELEMENT _category.description ; Data items in the DIFFRN_DETECTOR_ELEMENT category record the details about spatial layout and other characteristics of each element of a detector which may have multiple elements. DRAFT NOTE: This category is intended to hold definitions which are specific to the elements of area/array detectors. Generic features about the class detector are defined in the existing mmCIF category DIFFRN_DETECTOR. ; _category.id diffrn_detector_element _category.mandatory_code no loop_ _category_key.name '_diffrn_detector_element.id' '_diffrn_detector_element.detector_id' loop_ _category_group.id 'inclusive_group' 'array_data_group' loop_ _category_examples.detail _category_examples.case ; Example 1: Detector d1 is composed of four CCD detector elements. ; ; loop_ _diffrn_detector_element.id _diffrn_detector_element.detector_id d1 d1_ccd_1 d1 d1_ccd_2 d1 d1_ccd_3 d1 d1_ccd_3 ; save_ save__diffrn_detector_element.id _item_description.description ; The value of _diffrn_detector_element.id must uniquely identify each element of a detector. ; loop_ _item.name _item.category_id _item.mandatory_code '_diffrn_detector_element.id' diffrn_detector_element yes _item_type.code code loop_ _item_linked.child_name _item_linked.parent_name '_diffrn_frame_data.detector_element_id' '_diffrn_detector_element.id' save_ save__diffrn_detector_element.detector_id _item_description.description ; This item is a pointer to _diffrn_detector.id in the DIFFRN_DETECTOR category. ; _item.name '_diffrn_detector_element.detector_id' _item.category_id diffrn_detector_element _item.mandatory_code yes _item_type.code code save_ # # Modifications to existing mmCIF categories ... # save_DIFFRN_DETECTOR _category.description ; This category redefinition has been added to extend the key of the standard DIFFRN_DETECTOR category. ; _category.id diffrn_detector _category.mandatory_code no _category_key.name '_diffrn_detector.id' loop_ _category_group.id 'inclusive_group' 'diffrn_group' save_ save__diffrn_detector.id _item_description.description ; The value of _diffrn_detector.id must uniquely identify each detector used to collect each diffraction data set. ; _item.name '_diffrn_detector.id' _item.category_id diffrn_detector _item.mandatory_code yes _item_type.code code save_ save_DIFFRN_REFLN _category.description ; This category redefinition has been added to extend the key of the standard DIFFRN_REFLN category. ; _category.id diffrn_refln _category.mandatory_code no _category_key.name '_diffrn_refln.frame_id' loop_ _category_group.id 'inclusive_group' 'diffrn_group' save_ save__diffrn_refln.frame_id _item_description.description ; This item is a pointer to _diffrn_frame_data.id in the DIFFRN_FRAME_DATA category. ; _item.name '_diffrn_frame_data.frame_id' _item.category_id diffrn_frame_data _item.mandatory_code yes _item_type.code code save_ #