|
INTERNATIONAL TABLES for CRYSTALLOGRAPHY |
Volume G |
Definition and Exchange of Crystallographic Data |
By September 1989 the format for tagging the components of the data structure has become much more similar to the final CIF syntax, but the two-part separation of data structure header followed by the data remains. Macro definitions are still considered an important component of the file specification. By this stage a working prototype of the processing software QUASAR exists, and specific implementation details are being given.
CIF Documents: #1 Version: Sep25-89
##########################################################
##########################################################
### ###
### Description of a STAR 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 document describes the application of a Self-defining Text Archive
and Retrieval (STAR) file for the storage of text and numeric data. The
format of a STAR file permits the storage of any data type in any order.
Primary Structure of a STAR File
--------------------------------
A STAR file is a formatted sequential file composed of text lines. These
lines contain up to eighty (80) standard visible ascii characters and may
be viewed or edited with a standard text editor. A STAR file may contain any
number of data sets. Each data set is specified in two parts. The first part
is a directory containing an unique name for each of the data items in the
second part of the file. More specifically:
Part 1 of each data set is the DIRECTORY of data NAMES. The order of the
data names determines the order of the data items in part 2 of
the data set. Each name may appear only once in a directory. The
first line of a directory contains a 'star_***' command where
'***' is the name of the data set. The directory is closed with
a 'stop_star' command. In addition to data names, the directory
contains 'list_' and 'loop_' commands which specify the "structure"
of the data in part 2 of the file. These are described below.
Part 2 of a each data set contains the DATA items. The start of the data
entries is defined by a 'data_***' command where the data set name
'***' must match that of a preceding 'star_***' command. Data
entries are closed with a 'stop_data' command.
Both the directory and the data entries are machine-readible, as well as being
intelligible as text. A directory MUST precede the data entries for the same
data set. When there are multiple data sets in a file, the directory and data
parts may be interleaved, or all directories may precede all data.
Here is a brief description of the STAR structure commands. Examples of their
application are given in later sections.
star_xxxx specifies the start of a STAR directory for the data set
named 'xxxx'. Each data set in a file must have a different
name.
data_xxxx specifies the start of data entries for data set 'xxxx'.
This must be preceded by a directory of the same name.
list_yyyy specifies the start of a list of data names or items
grouped under the name 'yyyy'. The end of this list
is signaled by either another 'list_' or 'stop_star' or
'stop_data' command.
loop_zzzz specifies the start of a subset of repeated data items
grouped under the name 'zzzz'. The end of a loop is
is signaled by either a 'stop_loop' command or a 'list_'
command. In part 2 of the file a semicolon (;) may also
be used to delimit a loop. 'loop_' commands may be
nested but the data must be front loading (this is
described in the STAR File Description section below).
macro_pppp specifies a combination of structure commands and data
names grouped within the macro definition 'pppp'. Macros
be appear only in the directory of the file. They are used
to abbreviate the file description. STAR structure commands
contained within the macro definition must appear in part 2
of the file.
The Syntax of a STAR File
-------------------------
The syntactical rules of a STAR file are simple. They are:
1. Characters appearing on a line after a sharp '#' are considered
to be comments only.
2. A single character string cannot contain imbedded blanks unless
surrounded by matching single or double quotes.
3. A single character string starting with a dollar sign '$' is
considered to be a comment only.
4. A data name is a single character string, not surrounded by quotes,
and not exceeding thirty two (32) characters in length.
5. A data name may only appear in a directory where it must be unique.
6. The characters in a data name are case-insensitive.
7. A data name may have two ATTRIBUTES. These are specified by codes
that follow the data name in the directory. The codes have a max.
four (4) characters.
i) the first ATTRIBUTE code designates the TYPE of data item.
Permitted TYPE codes are:
numb specifies a number which may be in integer,
real or scientific format. If a number is
concatenated with another number bounded by
parentheses, it is taken to be the standard
deviation [e.g. nn.nm(m)]. This is the
DEFAULT data type.
char specifies a data item as a string of less
than 80 characters, either without blanks or
bounded by matching single or double quotes.
A character item must not straddle two lines.
text specifies lines of text data. Text data is
terminated by a semicolon (;) as the first
character of a line.
ii) the second ATTRIBUTE code designates the UNITS of the item.
The recognised codes are listed in a STAR Glossary. The first
listed code is the default. Note that if a units attribute is
declared in a file it MUST be preceded by the type attribute.
Example of a STAR file
----------------------
The following is a typical example of a small STAR file. This is suitable
for use as a test input file (STARIN) for the program QUASAR (described
below). [** PLEASE NOTE that although this example uses crystallographic
data it is NOT intended to match names defined in the CIF Glossary -- it
is intended only to 1llustrate way a STAR file is defined, and how it is
applied].
#..............................................................................
#
# Part 1: STAR file Directory
# --------------------------
#
star_xtal
list_chemical
chemical_name text
chemical_formula char
list_publication
publication_reference char
publication_title text
loop_publication_authors
publication_author_name char
publication_author_address text
list_cell
cell_a
cell_b
cell_c
cell_alpha
cell_beta
cell_gamma
cell_volume
list_symmetry
symmetry_space_group_Hall char
loop_symmetry_positions
symmetry_pos_in_xyz char
list_experimental
exptl_radiation_type char
exptl_radiation_wave_length
exptl_diffractometer_type char
loop_exptl_crystal_shape
exptl_crystal_face_h
exptt_crystal_face_k
exptl_crystat_face_l
exptl_crystal_face_dist numb cm
list_atom_types
loop_atom_types
atom_type_description char
atom_type_contents
atom_type_radius
atom_type_sf_name char
atom_type_sf_delta_real
atom_type_sf_delta_imag
atom_type_sf_source char
macro_sf_Cromer_Mann_coeff
loop_atom_type_sf_vs_angle
atom_type_sf_value
atom_type_sint/lambda
list_atom_sites
loop_atom_sites
atom_site_name char
atom_site_frac_x
atom_site_frac_y
atom_site_frac_z
atom_Site_occupancy
atom_site_U_iso
atom_site_U_11
atom_site_U_22
atom_site_U_33
atom_site_U_12
atom_site_U_13
atom_site_U_23
list_reflections
loop_refln_diffrn
refln_diffrn_h
refln_dlffrn_k
refln_diffrn_l
refln_diffrn_net_counts
refln_diffrn_theta
refln_diffrn_kappa
refln_diffrn_phi
refln_diffrn_psi
stop_loop
loop_refln_refined
refln_refine_h ; refln_refine_k ; refln_refine_l
refln_refine_sint/lambda
refln_refine_multiplicity
refln_refine_status_code char
refln_refine_F_measured
refln_refine_F_calculated
stop_star
# Part 2: Data Items
# ------------------
data_xtal
list_chemical
3-(2,5-dihydro-4-hydroxy-5-oxo-3-phenyl-2-furyl)propionic acid
;
C13_H12_O5
list_publication
'Acta Crystallographica (1988). C44, p512-514.'
Structure of WF-3681,
3-(2,5-Dihydro-4-hydroxy-5-oxo-3-phenyl-2-furyl)propionic Acid.
;
loop_publication_authors
'Charles R. Kissinger'
Department of Biological Structure, SM-20
University of Washington
Seattle WA 98195
U.S.A.
;
"Barry O'Connell"
Department of Chemistry
University of Kalamazoo
Michigan U.S.A.
;
'John I. Clark'
University of Washington
Seattle WA 98195 U.S.A.
;
list_cell
18.757(8) 7.282(2) 17.511(8) 90(0) 91.20(3) 90(0) 2391(3)
list_symmetry
-C2_yc
loop_symmetry_positions
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
'Ni-filtered Cu' 1.54179 'Picker FACS-1'
loop_crystal_shape
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
loop_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
loop_atom_type_sf_vs_angle * * ;
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
loop_atom_type_sf_vs_angle * * ; _
hydrogen 96 0.5
H 0 0
'Stewart_Davidson form factors,
* * * * * * * * *
loop_atom_type_sf_vs_angle
1.00 0.00
0.97 0.0429
0.899 0.0859
# ..............
0.047 1.530 ;
list_atom_sites
loop_atom_sites
C(1) .6237(1) -.2055(4) -.3119(2) 1.00 .053
.044 .036 .077 -.01 .012 .01
C(2) .6022(2) -.2468(6) -.2322(2) 1.00 .059
.047 .052 .067 .03 -.011 .01
# ................................................
O(5') .7504(1) .0454(3) .0417(1) 1.00 .056
.032 .024 .036 .012 -.011 .03
list_reflections
loop_diffrn_reflns
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
;
loop_refine_reflns
0 0 1 .0326 4 obs 119.78 132.34
0 0 2 .0655 4 <2s 7.33 4.29
# ...................................
12 9 13 .5788 1 <3s 12.49 11.45
stop_data
# .............................................................................
Note that the 'list_' commands are used principally to separate the data
into 'logical' records. This separation aids the organisation and retrieval
of data and is flag for processing software such as QUASAR to check that
the number of data items matches the number of data names. It also serves
to delimit the 'loop' data structures.
'Loop_' commands may be either NESTED (see the 'loop_atom_types' and
'loop_atom_type_sf_vs_angle' commands above), or UNNESTED (see the
'loop_diffrn_reflns' and 'loop_refine_reflns'). Data stored in loops
must be 'front-loading'. That is, data is stored in the front of each
level before preceding to the next -- data should not be stored at
lower levels as the loops are 'unnested'. In the data part of the file
each item must appear at least once in a loop. In some cases this will
necessitate the inclusion of dummy data (see 'loop_atom_types'). Dummy or
void data must be entered as asterisks (*). In both the file directory
and data parts of the file, note how the nested loops are defined and
controlled (as per rule 4 below). In particular look at the use of the
semicolon in the nested 'atom_types' list and the unnested loops in the
'reflections' list.
The 'macro_' commands are used to simplify and abbreviate the definition
of a file structure. Macro commands may be used only in the directory but
all of the STAR commands that are contained in the macro definition must
be declared explicitly in the data part of the file. In the above example
file the macro 'macro_sf_Cromer_Mann_coeff' is used as part of the
'loop_atom_types' structure. This is a relatively simple example of a
'macro'. Macros must be defined in the STAR macro file (called STARMO)
which is accessed by processing software such as QUASAR. An example of a
typical macro file is given below. Further information about macro
applications is also given below.
Data names are usually specified on separate lines. It is possible,
however, to define more than one data name (and associated attributes)
on a single line but these must be separated by a semi-colon (see the
'refln_refine_h', etc. definitions above).
Here is a summary of the rules that govern the structure of the data
part of a STAR file.
1) data must be entered in the same order as the data
definition 'names' in the star directory,
2) at least one blank must separate each data item,
3) each 'loop' level must contain at least one packet
of data (one of each data item),
4) each 'loop' is terminated with a single semi-colon
(one per level) or a 'list' or 'stop' command,
5) no data item, except type 'text', may straddle two lines,
6) any information following a sharp '#' is treated as a
comment EXCEPT in lines defined as 'text' data. Blank
lines are ignored.
Application of Macros in a STAR File
------------------------------------
The STAR file directory may be abbreviated with use of macros. These macros
must be defined in the STAR macro file. Some simple examples of macros for
crystallographic applications are given below in a test file.
The use of macros may range from a simple list of related data items (such
as the macro used in the above example) to a macro that defines the entire
structure of the data file. This latter application may be desirable for
situations where the same set of data items is routinely generated by a
program system for archiving, or for a specific purpose such as submission
to a journal or data base.
For example, the macro name 'macro_file_Acta_Cryst_C_1990' may be used to
submit a manuscript and data file to Acta Crystallographica C. Note that
this would not necessarily be the only arrangement of data that would meet
the requirements of this journal, but it may be the minimum and recommended
one. Its definition must, of course, exist in the macro file.
It is essential that the names of these 'global' macros contain either
a date or version number because the requirements of journals and program
systems are certain to change in the future. This does not mean, however,
that files containing past definitions will become inaccessible as soon
as another definition is formulated to meet new requirements. It is
absolutely fundamental to the STAR concept that names and macro defin-
itions may be added to macro file but never removed. Newer names and
macros are accepted but old definitions must always be supported.
The STAR macro file (labelled 'STARMO') contains the definitions of macros
that appear either in the directory of a STAR data file (labelled 'STARIN'),
or a STAR request file (labelled 'STAREQ'). Here is an example macro file
which could be used in conjunction with the test data file described above.
Note that the 'macro_' and 'end_macro' commands MUST start at the beginning
of a line. Macro definitions may be nested up to ten (10) levels.
#.......................................................................
#
# STAR macro file containing crystallographic examples
#
open_macros
macro_cell_dimensions
cell_a
cell_b
cell_c
cell_alpha
cell_beta
cell_gamma
cell_volume
end_macro
macro_sf_Cromer_Mann_coeff
sf_Cromer_Mann_a1
sf_Cromer_Mann_b1
sf_Cromer_Mann_a2
sf_Cromer_Mann_b2
sf_Cromer_Mann_a3
sf_Cromer_Mann_b3
sf_Cromer_Mann_a4
sf_Cromer_Mann_b4
sf_Cromer_Mann_c
end_macro
macro_atom_sites_acta
loop_atom_sites
atom_site_name char
atom_site_frac_x
atom_site_frac_y
atom_site_frac_z
atom_site_occupancy
atom_site_U_iso
atom_site_U_11
atom_site_U_22
atom_site U_33
atom_site_U_12
atom_site_U_13
atom_site_U_23
end_macro
macro_list_atom_sites_acta
list_atom_sites_acta
macro_atom_sites_acta
end_macro
macro_refln_refine_hkl
refln_refine_h
refln_refine_k
refln_refine_l
end_macro
macro_reflections_xtal
loop_refln_refine
macro_refln_refine_hkl
refln_refine_sint/lambda
refln_refine_multiplicity
refln_refine_status_code char
refln_refine_F_measured
refln_refine_F_calculated
end_macro
close_macros
#.......................................................................
The program QUASAR requires that the macro file may be read as a
'direct-access' file. This makes the access to nested macros much more
efficient. This means that a macro file, such as the one above, must be
converted from 'sequential-access' to 'direct-access' before it can be
used with QUASAR. A simple program (STOD) for doing this is given below.
C.......................................................................
program stod
character*80 ibuf
open(1,file='STARMO',status='new',form='formatted',
* access='direct',recl=80)
open(2,file='STARMO.seq',status='old',form='formatted')
i=0
10 read(2,'(a)',end=20) ibuf
i=i+1
write(1,'(a)',rec=i) ibuf
go to 10
20 close(1)
close(2)
end
C.......................................................................
The program STOD reads a standard text version of a macro file labelled
'STARMO.seq' and outputs a direct-access file labelled 'STARMO'. This
latter file will be accessed by QUASAR whenever a 'macro_' is encountered
in either in the request file 'STAREQ' or the data file 'STARIN'.
Extracting Data from a STAR File
--------------------------------
Data may be extracted from a STAR file in a variety of ways. All depend
on understanding the structure of a STAR file. The procedure described
here is based on the 'parsing' method used by the program QUASAR. This
program provides a template for developing other software that may be
used to manipulate and access a STAR file.
With the program QUASAR, data is extracted from a STAR data file (labelled
'STARIN') by submitting a list of data requests as a text file labelled
'STAREQ'. A typical request list is given below. The format of this list
is almost identical to that of a star directory. There are important
differences, however. With exception of 'star_', control commands
are NOT needed in a request list -- but they may be included if the user
finds that they help the visual organisation of the data. The 'star_'
command is needed to specify the name of the data set to be accessed in the
STARIN file (it is always assumed that more than one data set may be present).
Data attributes may be included in the request file but they wIll be
ignored. If more than one item is requested on a line these must be
separated by a 'blank-semicolon-blank' sequence. Macros may also be used
to request a group of items, provided the macro is defined in the macro
file (labelled 'STARMO').
QUASAR outputs the data items (with their names) in the order requested.
Requested items that are missing from the STAR file are listed and flagged.
Here is a typical request file. The QUASAR output file which resulted
from the submission of this file follows.
#.......................................................................
#
# QUASAR request file (labelled STAREQ)
#
star_xtal
chemical_name
publication_reference
publication_title
publication_author_name
publication_author_address
macro_cell_dimensions
symmetry_space_group_Hall
symmetry_pos_in_xyz
macro_list_atom_sites_acta
exptl_radiation_wave_length
exptl_radiation_type
exptl_crystal_face_h
exptl_crystal_face_k
exptl_crystal_face_l
exptl_crystal_face_dist
loop_atom_types # included for visual reasons only
atom_type_sf_name
atom_type_description
atom_type_sf_source
atom_type_sf_neutron_length
atom_type_sf_delta_real
atom_type_sf_delta_imag
macro_sf_Cromer_Mann_coeff
atom_type_contents
atom_type_radius
loop_atom_type_sf_vs_angle # included for visual reasons only
atom_type_sf_value
atom_type_sint/lambda
refln_diffrn_h ; refln_diffrn_k ; refln_diffrn_l
refln_diffrn_theta
refln_diffrn_omega
refln_diffrn_phi
refln_diffrn_chi
refln_diffrn_net_counts
macro_reflections_xtal
#.......................................................................
Data Output from QUASAR
-----------------------
The following sequence of lines is the file STAROT output from the program
QUASAR upon entering the request file STAREQ. Please check this carefully
when testing the application of the STAR file. Note that while this is a
relatively exhaustive test of the file structure, and the QUASAR facilities
(the request list is intentionally in a different order to the data stored
in the STAR file example), the extent of the data has been kept to a min-
imum for the sake of brevity. Note also that certain data items that are
not on the STAR file have been requested to illustrate how QUASAR handles
this situation, while a number of other items have not been requested.
Testers are encouraged to apply QUASAR to actual data files, using data
name of there own construction.
#.......................................................................
chemical_name text
3-(2,5-dihydro-4-hydroxy-5-oxo-3-phenyl-2-furyl)propionic acid
;
publication_reference char
'Acta Crystallographica (1988). C44, p512-514.'
publication_title text
Structure of WF-3681,
3-(2,5-Dihydro-4-hydroxy-5-oxo-3-phenyl-2-furyl)propionic Acid.
;
<<loop>>
publication_author_new char
publication_author_address text
'Charles R. Kissinger'
Department of Biological Structure, SM-20
university of Washington
Seattle WA 98195
U.S.A.
;
"Barry O'Connell"
Department of Chemistry
University of Kalamazoo
Michigan U.S.A.
;
'John I. Clark'
University of Washington
Seattle WA 98195 U.S.A.
;
cell_a numb 18.757(8)
cell_b numb 7.282(2)
cell_c numb 17.511(8)
cell_alpha numb 90(0)
cell_beta numb 91.20(3)
cell_gamma numb 90(0)
cell_volume numb 2391(3)
symmetry_space_group_Hall char -C2_yc
<<loop>>
symmetry_pos_in_xyz char
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
<<loop>>
atom_site_name char
atom_site_frac_x numb
atom_site_frac~y numb
atom_site_frac z numb
atom_site_occipancy numb
atom_site_U_iso numb
atom_site_U_11 numb
atom_site_U_22 numb
atom_Site_U_33 numb
atom_site_U_12 numb
atom_site_U_13 numb
atom_site_U_23 numb
C(1) .6237(1) -.2055(4) -.3119(2) 1.00 .053 .044 .036 .077 -.01 .012 .01
C(2) .6022(2) -.2468(6) -.2322(2) 1.00 .059 .047 .052 .067 .03 -.011 .01
O(5') .7504(1) .0454(3) .0417(1) 1.00 .056 .032 .024 .036 .012 -.011 .03
exptl_radiation_wave_length numb 1.54179
exptl_radiation_type char 'N-filtered Cu'
<<loop>>
exptl_crystal_face_h numb
exptl_crystal_face_k numb
exptl_crystal_face_l numb
exptl_crystal_face_dist numb cm
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
<<loop>>
atom type_sf_name char
atom_type_description char
atom_type_sf_source char
atom_type_sf_neutron_tength <<< Requested item missing from file!
atom_type_sf_delta_real numb
atom_type_sf_delta_imag numb
sf_Cromer_Mann_a1 numb
sf_Cromer_Mann_b1 numb
sf_Cromer_Mann_a2 numb
sf_Cromer_Mann_b2 numb
sf_Cromer_Mann_a3 numb
sf_Cromer_Mann_b3 numb
sf_Cromer_Mann_a4 numb
sf_Cromer_Mann_b4 numb
sf_Cromer_Mann_c numb
atom_type_contents numb
atom_type_radius numb
<<loop>>
atom_type_sf_value numb
atom_type_sint/lambda numb
C carbon 'Cromer-Mann coefficients' 0.22 0.01 1.9302 12.7181 1.8781
28.6498 1.5742 .5964 .3711 65.0337 .2464 104 0.75
* *
O oxygen 'Cromer-Mann coefficients' 0.25 0.03 2.9565 13.8964 2.4524
5.9177 1.5051 .3454 .7814 34.0811 .3041 40 0.85
* *
H hydrogen 'Stewart-Davidson form factors' 0 0 * * *
* * * * * * 96 0.5
1.00 0.00
0.97 0.0429
0.899 0.0859
0.047 1.530
<<loop>>
refln_diffrn_h numb
refln_diffrn_k numb
refln_diffrn_l numb
refln_diffrn_theta numb
refln_diffrn_omega <<< Requested item missing from file!
refln_diffrn_phi numb
refln_diffrn_chi <<< Requested item missing from file!
refln_diffrn_net_counts numb
0 0 1 6.78 68.24 45093485
0 0 2 12.73 76.20 7445
12 9 13 82.76 12.67 43782
<<loop>>
refln_refine_h numb
refln_refine_k numb
refln_refine_l numb
refln_refine_sint/lambda numb
refln_refine_multiplicity numb
refln_refine_status_code char
refln_refine_F_measured numb
refln_refine_F_calculated numb
0 0 1 .0329 4 obs 119.78 132.34
0 0 2 .0655 4 <2s 7.33 4.29
12 9 13 .5788 1 <3s 12.49 11.45
Copyright © 2005 International Union of Crystallography