|
INTERNATIONAL TABLES for CRYSTALLOGRAPHY |
Volume G |
Definition and Exchange of Crystallographic Data |
In a slightly later revision of the initial CIF specification, 'macros' are introduced. Macro definitions were intended to be predefined collections of specific data items, declared in a public CIF glossary, that would be referenced in the file structure header. The intention was to make the header more compact and to build a collection of standard sets of required items. Note the proposal to identify macro definitions with a version number to safeguard the archival function of the file format.
# Version: Aug 3 88 /1 # # CRYSTALLOGRAPHIC INFORMATION FILE # -------------------------------- # S.R. Hall, Roentgenlabor # Max-Planck-Instut fuer Kohlenforschung # D-4330 Muelheim/Ruhr, FRG. # Ph: [49]208 306 491/488 # Fx: [49]208 306 407 # Em: [email protected] # # This is a proposal for a free-format self-defining text file for # storing crystallographic information (CIF). The data structure in CIF # will handle any data type that can be expressed as ascii characters. # It will provide for future definitions of data types, and allow for # the inclusion of 'stranger' or 'system-specific' data types (which # will make it more amenable as a storage medium for program systems). # # The 'structure' of the file is relatively simple and very flexible. # The overall structure of each file will be defined by a sequence of # definition commands at the front of the file. Each of these lines will # start with a semicolon ';'. The file-definition structure is # self-defining. Note that any information following a sharp '#' in # column 1 is considered as a comment and will be ignored by software # processing this file. Blank lines are ignored, and tabs are treated as # blanks. # # First, here is an example of the file-definition structure. A short # description of this structure follows. This is followed by the actual # data file that matches this structure, and methods of improving the # file-definition structure with definition 'macros'. # # --------------------------------------------------------------------- ; define_file xtal_archive ; define_list compound_description ; chemical_name text ; chemical_formula char ; compound_id_code char xtal ; define_list publication_data ; author_names text ; title text ; full_reference text ; database_ref_number int ; define_list crystal_cell ; unit_cell_a real ; unit_cell_a_sd (in) ; unit_cell_b real ; unit_cell_b_sd (in) ; unit_cell_c real ; unit_cell_c_sd (in) ; unit_cell_alpha real ; unit_cell_alpha_sd (in) ; unit_cell beta real ; unit_cell_beta_sd (in) ; unit_cell_gamma real ; unit_cell_gamma_sd (in) ; unit_cell_volume real ; unit_cell_volume_sd (in) ; define_list crystal_symmetry ; herm-maug_symbol char ; hall_symbol char ; define_loop jones_representation ; equiv_pos_in_xyz char ; define_list experimental_data ; radiation_type char ; radiation_wave_length real ; diffractometer_type char ; define_loop crystal_shape ; face_h int ; face_k int ; face_l int ; face_dim_cm real ; define_list atom_types ; define_loop atom_types ; atom_type_description char ; cell_contents_for_type int ; atom_bond_radius real ; sf_name char ; sf_delta_real real ; sf_delta_imag real ; sf_description char ; sf_crom/mann_coef_a1 real ; sf_crom/mann_coef_b1 real ; sf_crom/mann_coef_a2 real ; sf_crom/mann_coef_b2 real ; sf_crom/mann_coef_a3 real ; sf_crom/mann_coef_b3 real ; sf_crom/mann_coef_a4 real ; sf_crom/mann_coef_b4 real ; sf_crom/mann_coef_c real ; define_loop sf_vs_stol ; sf_name char ; sf_at_stol real ; sin_theta_on_lambda real ; define_list crystal_structure ; define_loop atom_sites ; site_name char ; site_frac_x real ; site_frac_x_sd (in) ; site_frac_y real ; site_frac_y_sd (in) ; site_frac_z real ; site_frac_z_sd (in) ; site_tf_uiso real ; site_occupancy real ; site_tf_u11 real ; site_tf_u22 real ; site_tf_u33 real ; site_tf_u12 real ; site_tf_u13 real ; site_tf_u23 real ; define_list diffraction_information ; define_loop reflection_data ; ref_h; ref_k; ref_l ; ref_sin_theta/lambda ; ref_sym_reinf_factor int xtal ; ref_sym_multiplicity int xtal ; ref_status_code char ; ref_sf_measured ; ref_sf_calculated ; end_loop reflection_data ; define_loop diffraction_data ; ref_h; ref_k; ref_l ; ref_net_int_counts int ; ref_diff_angle_theta real ; ref_diff_angle_kappa real ; ref_diff_angle_phi real ; ref_diff_angle_psi real ; end_definition_file xtal_archive # --------------------------------------------------------------------- # # There are three levels of structure definition: 'file', 'list' and # 'loop'. Multiple 'file' definitions allow for multiple data sets of # the same crystal with different radiations, or for # isomorphically-related structures. The name of the 'file' is not # expected to have a special significance, though, in the case of # multiple data sets, it would presumably identify the nature of the # data sets. The name may also be used to identify the generating # program (as is the case in this example). # # The 'list' definitions enable the data to be subdivided into 'logical' # units. When there is more than one occurrence of information (e.g. # reflection data) these are defined as 'loop' packets. Note that 'loop' # data may be nested (as for atom_types and sf_vs_stol in 'list' # atom_types), or unnested (as in the case of reflection_data and # diffraction_data in 'list' diffraction_information). The extent of a # 'loop' definition is terminated by either a define_list line or an # end_loop tine. There is no limit to the number 'loop' nestings. # # Each 'list' and 'loop' data item may be assigned TWO ATTRIBUTES. The # first attribute specifies the data type. For 'standard' items (i.e. # those with names which are listed in the CIF GLOSSARY) the data types # may be assumed. The second attribute identifies an item for a special # 'non-standard' purpose. This attribute is only used if an item is NOT # listed in the CIF GLOSSARY. # # The following DATA TYPE ATTRIBUTES are permitted. # # char String of characters not exceeding 80 in length. # If the string contains any imbedded blanks, it must # be surrounded by single or double quotes (' or "). # # dble All double precision floating-point numbers with, and # without, decimal point and explicit exponent. The # numbers must be in the same range as real numbers. # # hex Hexadecimal number not exceeding 8 hexadecimal digits. # # int Integer number inside the range -2147483648 (-2**32) to # +2147483647 (2**31-1). # # (in) Integer number bounded by parentheses. This is converted # to a real number with the same precision of the preceding # number where this integer is the least significant digit. # # real All floating-point number representations with, and # without, decimal point and explicit exponent. The absolute values # of the numbers must be in the range of 0.29E-38 (16**-32) to # 1.7E+38 (16**32). # # text Character data that starts on a new line and is terminated # by a line starting with a semicolon';'. # # # --------------------------------------------------------------------- ; file xtal_archive ; list compound_description 3-(2,5-dihydro-4-hydroxy-5-oxo-3-phenyl-2-furyl)propionic acid ; C13H12O15 WF3681 ; list publication_data Charles R. Kissinger, Stewart Turley and John I. Clark ; Structure of WF-3681, 3-(2,5-Dihydro-4-hydroxy-5-oxo-3-phenyl-2-furyl)propionic Acid. ; Acta Crystallographica (1988). C44, p512-514. ; CDF-834645 ; list crystal_cell 18.757(8) 7.282(2) 17.511(8) 90(0) 91.20(3) 90(0) 2391(3) ; list crystal_symmetry C2/c -C2yc x,y,z -X,-y,-Z -x,y,1/2-z x,-y,1/2+z 1/2+x,1/2+y,z 1/2-x,1/2-y,-z 1/2-x,1/2+y,1/2-z 1/2+x,1/2-y,1/2+z ; list experimental_data 1.54179 'Ni_filtered Cu' 'Picker FACS-1' 0 0 -1 0.012 0 0 1 0.012 1 0 0 0.023 -1 0 0 0.023 0 -1 0 0.027 0 1 0 0.027 ; list atom_types carbon 104 0.75 C 0.22 0.01 'Cromer-Mann coefficients' 1.9302 12.7181 1.8781 28.6498 1.5742 .5964 .3711 65.0337 .2464 ; 'neutral oxygen' 40 0.85 O 0.25 0.03 'Cromer-Mann coefficients' 2.9565 13.8964 2.4524 5.9177 1.5051 .3454 .7814 34.0811 .3041 ; hydrogen 96 0.5 H 0 0 'Stewart-Davidson form factors' 0 0 0 0 0 0 0 0 0 H 1.00 0.00 H 0.97 0.0429 H 0.899 0.0859 ...................... H 0.047 1.530 ; ; list crystal_structure C(1) .6237(1) -.2055(4) -.3119(2) .053 1.00 .044 .036 .077 -.01 .012 .01 C(2) .6022(2) -.2468(6) -.2322(2) .059 1.00 .047 .052 .067 .03 -.011 .01 ................................................ O(5) .7504(1) .0454(3) .0417(1) .056 1.00 .032 .024 .036 .012 -.011 .03 ; list diffraction_information 0 0 1 .0326 4 4 obs 119.78 132.34 0 0 2 .0655 4 4 <2s 7.33 4.29 ..................................... 12 9 13 .5788 1 1 <3S 12.49 11.45 ; 0 0 1 45093485 6.78 28.56 68.24 92.32 0 0 2 7445 12.73 45.93 76.20 94.37 .................................................. 12 9 13 43782 82.76 56.21 12.67 56.03 ; end_file xtal_archive # --------------------------------------------------------------------- # # # It is important to emphasise that the format of both the control # commands (e.g. 'file' and 'list') and the data items is not fixed # except for the following rules: # # 1) commands must follow a semicolon, # # 2) commands and data must be entered in precisely # the order specified in the file structure, # # 3) at least one blank must separate each data item # and items must not be omitted unless delimited # by a semicolon, and # # 4) a nested 'loop' level is terminated with a semicolon. # # In the above example note that a 'loop' packets of data can occupy # more than line (see the crystal_structure list), or alternatively # several 'loop' packets may be on the same line (see the # crystal_symmetry list). A list or packet may occupy any number of # lines but no data item, except type_text, may 'straddle' two lines. # # In both the file definition and data entry parts of the file, note # how the nested loops are defined and controlled (as per rule 4). In # particular look at the use of the semicolon in the nested atom_types # list and the unnested loops in the diffraction_information list. # # # Application of Macro Definitions in the CIF # ------------------------------------------- # # A simplification and abbreviation of the CIF structure definition may # be achieved using 'macro definitions'. These macros are predefined in # the CIF GLOSSARY (which will also be available as a computer-readable # file). # # There are four levels of macro definitions: # # ; define_file_macro # ; define_list_macro # ; define_loop_macro # ; define_data_macro # # A simple example of a 'data' macro is: # # ; define_data_macro ref-hkl # # which is equivalent to entering the sequence: # ; ref_h int # ; ref_k int # ; ref_l int # into any definition. # # Another obvious data cluster that could be easily macro'd is: # # ; define-data-macro sf_crom/mann_coefficients # # which is equivalent to entering: # # ; sf_crom/mann_coef_a1 real # ; sf_crom/mann_coef_b1 real # ; sf_crom/mann_coef_a2 real # ; sf_crom/mann_coef_b2 real # ; sf_crom/mann_coef_a3 real # ; sf_crom/mann_coef_b3 real # ; sf_crom/mann_coef_a4 real # ; sf_crom/mann_coef_b4 real # ; sf_crom/mann_coef_c real # # Yet another typical example would be the application of: # # ; define_data_macro unit_cell_dimensions_1 # # instead of standard data entries: # # ; unit_cell_a real # ; unit_cell_a_sd (in) # ; unit_cell_b real # ; unit_cell_b_sd (in) # ; unit_cell_c real # ; unit_cell_c_sd (in) # ; unit_cell_alpha real # ; unit_cell_alpha_sd (in) # ; unit_cell_beta real # ; unit_cell_beta_sd (in) # ; unit_cell_gamma real # ; unit_cell_gamma_sd (in) # ; unit_cell_volume real # ; unit_cell_volume_sd (in) # # Note the use of '_1' in this macro name. This is to permit more than # one arrangement of the unit cell data. For example, this may be the # preferred data structure for Acta Cryst. but other structures would be # permitted. # # # From these definitions it is obvious how 'loop', 'list' and 'file' # macros could be defined as well. A typical 'loop' macro might define # the structure data required for Acta for publication purposes. # # ; define_loop_macro atom_sites_acta # # represents the sequence: # # ; site_name char # ; site_frac_x real # ; site_frac_x_sd (in) # ; site_frac_y real # ; site_frac_y_sd (in) # ; site_frac_z real # ; site_frac_z_sd (in) # ; site_tf_uiso real # ; site_occupancy real # ; site_tf_u11 real # ; site_tf_u22 real # ; site_tf_u33 real # ; site_tf_u12 real # ; site_tf_u13 real # ; site_tf_u23 real # # Assuming that this was the only data required in the crystal structure # 'list' then it would be possible to use: # # ; define_list_macro crystal_structure_acta # # which has been predefined as: # # ; atom_sites_acta macro # # This is a trivial example but it emphasises that macro definitions may # be included in other macro definitions. Note that the attribute of # macro name is 'macro'. This is important only in the software # processing of the CIF definitions, since the actual definitions of the # macros do not appear in a CIF, only in the CIF GLOSSARY and # computer-readable file. # # Finally, it may be possible in some cases to apply a more comprehensive # define_file_macro. Again using submission to Acta Cryst. as an # example, it may be desirable for reasons of simplicity and brevity # (smaller files take up less disk space!) to specify a file # structure as simply one line: # # ; define_file_macro acta_cryst_C_1988 # # Similarly, it will probably be desirable for program systems to # predefine a file structure such as: # # ; define_file_macro xtal_2.4 # # Note that the names of these macros contain a date or version number. # This is important because it assumes that the requirements of journals # and program systems are going to change (which obviously true!). This # does not mean, however, that files containing past definitions wIll # become inaccessible as soon as a new preferred definition is # formulated. It is absolutely fundamental to the CIF concept that names # and definitions may be added to CIF GLOSSARY but never removed. Newer # names and structures are encouraged but old names must always be # supported. #
Copyright © 2005 International Union of Crystallography