|
INTERNATIONAL TABLES for CRYSTALLOGRAPHY |
Volume G |
Definition and Exchange of Crystallographic Data |
Less than a month after the September 1989 draft, the decision had been taken to drop the two-part file format in which the data structure was pre-declared in a header section, and to move the identifying tags to positions immediately preceding the relevant data values. Now the tags are distinguished by a leading underscore character, and the quoting of text strings with included white space has been formalised. The syntax is now very close to the final version (but note the presence of a trailing units attribute in some of the loops; this was subsequently transferred to the form of the individual data names and then eventually dropped altogether).
CIF Documents: #1 Version: Oct22-89
##########################################################
##########################################################
### The Definition of a Self-defining Text Archive ###
### and Retrieval (STAR) File ###
##########################################################
##########################################################
S.R. Hall*
Roentgenlabor, Max-Planck-Institut fuer Kohlenforschung,
D-4330 Muelheim/Ruhr, FRG. ([email protected])
[*On leave: Crystallography Centre, University of Western
Australia, Nedlands 6009, Australia. ([email protected])]
Abstract
--------
A file with a new type of data structure is proposed for the computer
archiving and electronic publication of text and numerical data. The
file contains an inbuilt description of the data structure and has a
format which permits the storage of any data type in any order.
Introduction
------------
The standard approach to the computer archiving of text and numerical data
is to use fixed format files. Such files employ a fixed data structure based
on current data requirements. Subsequent changes in archival requirements
are difficult for this type of approach, as changes to the data structure
will often make previously archived files inaccessible.
Upwards compatability and flexibility are therefore two very desirable
properties of any archival format. They are especially important when there
is a wide diversity of data types, or when the data requirements vary depending
on the point of application. Archival files must be portable so that commonly
used data are accessible independent of the data structure or origin. It is
also essential that an archive file format be flexible enough to incorporate
future data requirements without the need to modify existing files. The
Self-defining Text Archive and Retrieval (STAR) file structure is designed
to meet these requirements. The STAR format is intended for archiving text and
numerical data of any type and in any order. It is particulatly suitable for
electronic publication purposes.
Data 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 is sub-divided
into any number of separate data blocks. Each data block starts with the
string 'data_xxxx' where 'xxxx' is the block name.
The text following the 'data_' string specifies both the 'structure' (i.e.
layout) of the data, as well as the data items contained therein. All
information is machine-readable, as well as being intelligible as text.
The identity of each data item within a data block is specified with a unique
'data name'. A data name is a single character string starting with an
underline '_'. Each data item must be preceded by a data name and, if necessary,
a units attribute code which specifies the units of the data item. In addition
to the data names and data items, there is a command to indicate if data
items are repeated or 'looped'. This is the 'loop_' command. Repeated data is
terminated when another data name is encountered or the block is finished.
Only one level of looped data is permitted but higher levels of repeated lists
may be incorporated within text data.
The syntax of a STAR file is straightforward.
** Any data following a sharp '#' on a line is ignored, except if
contained within text data (see definition below).
** A single character string may NOT contain imbedded blanks,
unless surrounded by matching single or double quotes,
** A 'data name' is a single character string starting with an
underline '_' and not exceeding 32 characters in length.
** Each 'data name' MUST be unique within a given data block.
** The characters in a 'data name' are case-insensitive.
** A 'data name' must precede each data item, except for 'loop' data
where the data names and items are grouped in lists.
** A 'data name' may be followed by a units attribute code of up
to five (5) characters. The first character of this code must be
an underline '_'. Units codes are usually listed in a STAR
glossary and the first code is assumed to be the default.
** A data item is assumed to be a NUMBER if it is NOT surrounded
by matching single or double quotes, and starts with either a
digit '0-9', a plus '+' a minus '-', or a period '.'. A number
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.nnn(m)].
** A data item is assumed to be line TEXT data if it starts and finishes
with a semicolon ';' as the first character in a line. Text data
interpreted as complete lines.
** A data item is assumed to be CHARACTER string if it is surrounded
by matching single and quotes, or is not NUMBER or TEXT data.
A character string must be less than 80 characters in length and
may not straddle two lines.
** At least one blank character must separate data items in a 'loop_'
list.
** Only one level of 'loop_' data is permitted. Variable lists within
a 'loop_' list should be stored and retrieved as text data.
Example of a STAR File
---------------------
The following is an example of a small STAR file containing two data
blocks named 'manuscript' and 'crystal_structure'.
PLEASE NOTE that although this example uses crystallographic data
it is NOT intended to match names defined in the Crystallographic
Information File (CIF) glossary.
#.............................................................................
data_manuscript
_manuscript_summary
;
This is some dummy text to show how a multiple data-block STAR file works!
;
data_crystal_structure
_chemical_formula 'C13 H12 05'
_chemical_name
;
3-(2,5-dihydro-4-hydroxy-5-oxo-3-phenyl-2-furyl)propionic acid
;
_publication_title
;
Structure of WF-3681,
3-(2,5-Dihydro-4-hydroxy-5-oxo-3-phenyl-2-furyl)propionic Acid.
;
loop_
_publication_author_name
_publication_author_address
"O'Connell, Barry"
; Department of Chemistry
University of Kalamazoo
Michigan U.S.A.
;
'Clark, Joan I.'
; University of Washington
Seattle WA 98195 U.S.A.
;
_cell_a 18.757(8)
_cell_b 7.282(2)
_cell_c 17.511(8)
_cell_alpha 90
_cell_beta 91.20(3)
_cell_gamma 90
_cell_volume 2391(3)
_symmetry_space_group '-C 2yc'
loop_
_symmetry_pos_in_xyz
'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'
_exptl_radiation_wave_length 1.54179
loop_
_exptl_crystal_face_h
_exptl_crystal_face_k
_exptl_crystal_face_l
_exptl_crystal_face_distance _mm
0 0 -1 0.012
0 0 1 0.012
1 0 0 0.023
-1 0 0 0.023
loop_
-atom_site_label
_atom_site_x/a
_atom_site_y/b
_atom_site_z/c
_atom_site_U_iso
# atom x/a y/b z/c U
C1 .6237(1) -.2055(4) -.3119(2) .053
C2 .6022(2) -.2468(6) -.2322(2) .059
O5' .7504(1) .0454(3) .0417(1) .056
#.............................................................................
Retrieving Data from a STAR File
--------------------------------
Data may be retrieved 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 is intended to provide a template to developing other software
for accessing a STAR file [QUASAR is available from the authors (Hall and
Sievers) on request].
The program QUASAR retrieves data from a STAR archive file according to a
list of requested data names. The output data is also in STAR format.
The request list also contains the names of the data blocks to be searched,
and the filenames of the archive and output files (these are specified as
extensions to the commands 'star_arc_' and 'star_out_' respectively). If the
archive and output files are not specified they are assumed to have the
filenames 'STARIN' and 'STAROT'. Requested data items and data blocks are
output in the order requested. Within each data block the same data item may
be requested up to five times. The program QUASAR will also check the archive
file for logical integrity if the string 'star_log' is entered in the request
list. No data items will be output in this case. The 'loop_' commands and unit
attribute codes are not needed in a request list and will be ignored.
Requested items that are missing from the archive file are flagged with '??'.
Note that the example request list below contains a number of redundant data
requests in different orders. This is intended to demonstrate various aspects
of QUASAR processing and is not necessarily typical of a request list. The
example archive file given above is named 'qtest.arc' and the resulting
output file is named 'qtest.out' (this is listed below).
#-........................................................................
star_arc_qtest.arc
star_out_qtest.out
data_manuscript
_manuscript_summary
data_crystal_structure
_chemical_name
_publication_title
_publication_author_name
_publication_author_address
_cell_a
_cell_b
_cell_c
_cell_alpha
_cell_beta
_cell_gamma
_chemical_name
_symmetry_space_group
_symmetry_pos_in_XYZ
_atom_site_label
_atom_site_x/a
_atom_site_y/b
_atom_site_z/c
_atom_site_U_iso
_atom_site_label
_exptl_radiation_wave_length
_exptl_radiation_type
_exptl_crystal_face_distance
_exptl_dummy
_exptl_crystal_face_h
_exptl_crystal_face_k
_exptl_crystal_face_l
_atom_site_label
_atom_site_U_iso
_publication_author_name
data_manuscript
_manuscript_summary
#........................................................................
The following sequence of lines is the file 'qtest.out' output from QUASAR
after entering the above request list. Note that 'qtest.out' is also in
STAR format and may also used as an input file to QUASAR. Note how QUASAR
handles data that has been requested but is missing from the archive file.
#.........................................................................
data_manuscript
_manuscript_summary
;
This is some dummy text to show how a multiple data-block STAR file works!
;
# ----- end-of-data-block ----
data_crystal_structure
_chemical_name
;
3-(2,5-dihydro-4-hydroxy-5-oxo-3-phenyl-2-furyl)propionic acid
;
-publication_title
;
Structure of WF-3681,
3-(2,5-Dihydro-4-hydroxy-5-oxo-3-phenyl-2-furyl)propionic Acid.
;
loop_
_publication_author_name
_publication_author_address
"O'Connell, Barry"
; Department of Chemistry
University of Kalamazoo
Michigan U.S.A.
;
'Clark, Joan I.'
; University of Washington
Seattle WA 98195 U.S.A.
;
_cell_a 18.757(8)
_cell_b 7.282(2)
_cell_c 17.511(8)
_cell_alpha 90
_cell_beta 91.20(3)
_cell_gamma 90
_chemical_name
;
3-(2,5-dihydro-4-hydroxy-5-oxo-3-phenyl-2-furyl)propionic acid
;
_symmetry_space_group '-C 2yc'
loop_
_symmetry_pos_in_xyz
'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_label
_atom_site_x/a
_atom_site_y/b
_atom_site_z/c
_atom_site_U_iso
_atom_site_label
C1 .6237(1) -.2055(4) -.3119(2) .053 C1
C2 .6022(2) -.2468(6) -.2322(2) .059 C2
O5' .7504(1) .0454(3) .0417(1) .056 O5'
_exptl_radiation_wave_length 1.54179
_exptl_radiation_type ?? # requested item not present
loop_
_exptl_crystal_face_distance _mm
_exptl_dummy # ?? requested item not present
_exptl_crystal_face_h
_exptl_crystal_face_k
_exptl_crystal_face_l
0.012 ?? 0 0 -1
0.012 ?? 0 0 1
0.023 ?? 1 0 0
0.023 ?? -1 0 0
loop_
_atom_site_label
_atom_site_u_iso
C1 .053
C2 .059
O5' .056
loop_
_publication_author_name
"O'Connell, Barry"
'Clark, Joan I.'
# -----end-of-data-block-----
data_manuscript
_manuscript_summary
;
This is some dummy text to show how a multiple data-block STAR file works!
;
# -----end-of-data-block-----
#.............................................................................
Acknowledgements
----------------
The author wishes to acknowlege the assistance of the large number of
crystallographers who have contributed to the design and specification of
the STAR file format. To Howard Flack whose insistence that diffractometer
data must be stored in an archive file catylised the initial design of the
STAR format. To Jim Stewart and Bob Munn whose original collaboration with
the development of the directory-driven binary files for the XTAL System
proved the importance of a having a self-defining and flexible file structures.
To the IUCr for the support during the development and testing of the STAR
concepts for application to the publication and archiving of a crystallographic
information file (CIF). To Frank Allen and David Brown whose expert advice and
guidance was instrumental in many of the refinements to STAR syntax presented
here. To Richard Goddard for the preparation of the first manuscripts used to
test the application of the STAR format to electronic publishing, and also for
his continual probing into the why's and wherefore's of STAR and QUASAR which
led to many of its simplifications. To Rolf Sievers for his collaboration in
the development of the QUASAR program for processing STAR files. To Mike
Dacombe and Brian McMahon at the Acta Crystallographica office in Chester whose
enthusiasm and assistance has been invaluable to the STAR and CIF development.
To George Sheldrick whose cooperation and discussions were important to ensuring
the practicality of the STAR data structure. To the many sites and people who
have implemented and tested the STAR processing software QUASAR. And to Carl
Krueger for his support at the Max-Planck-Institut fuer Kohlenforschung where
much of the STAR development took place. The simplicity and flexibility of the
STAR file has resulted largely from the contributions of all these people.
----------------------------------------------------------------------------
end-end-end-end-end-end-end-end
Copyright © 2005 International Union of Crystallography