[IUCr Home Page] [CIF Home Page]

Acta Cryst. (1991). A47, 655-685

STAR File concepts and syntax

A STAR File is composed of ASCII text that can be edited with a simple text editor. When viewed, its contents are easy to read and can be stored or transmitted electronically without conversion. The construction of a STAR File is simple. Each file contains a sequence of data blocks. Each data block contains a sequence of individual data items. There may be any number of data blocks and any number of data items within each data block. The data block represents the logical grouping of data that crystallographers normally associate with a `data set', but it may be used for any other purpose. The identity of each data item within a data block is determined by a unique data name which precedes it in the file. Data items may be repeated in lists by placing them within a simple data loop structure.

An important property of a STAR File is that its syntax is defined by a few simple rules (see Table 1). This ensures maximum flexibility for data exchange and wide applicability. No assumptions are made about the order of the data blocks or data items, other than the requirement that the character strings which identify data blocks, or data names within a block, must be unique. There are no restrictions regarding the placement of data names or data items within a data block, other than the requirement that the name must precede the item. Data in a STAR File are accessed simply by requesting a specific data name within a specific data block. Prior knowledge about data type (i.e. text or numbers), whether the item is looped, or whether the item exists in the file at all, is unnecessary.

The basic syntax of a STAR File is best illustrated by examples. Each data block is identified by a unique character string starting with `data_'. The string data_compound_B523 specifies the start of a data block identified by the block code `compound_B523'.

Each data item is identified by a unique data name composed of a character string starting with an underline character `_'. Three examples of data names and their associated data items are:

_cell_volume  2310(2)

_chemical_formula_moiety      'C23 H36 O7'


   Prof Barry O'Connell
   Department of Chemistry
   Building #57-M5
   University of Kalamazoo
   Michigan        USA.  

The data items above are of different types: numeric, character and text, respectively. The STAR File syntax makes no distinction between the type of data item. Each item is treated simply as a contiguous character string delimited by matching blanks, single quotes, double quotes, or semicolons as the first character of a line. The order and format of these strings in the file are irrelevant, except for the requirement that the data name precede the data item. Data on a line following a hash character `#' is considered to be a comment, except if it is contained within a text string. Examples of a hash character used as part of a data item and as a comment precursor are given above and below.

A data item, or a set of data items, may be repeated in a list. Such data items are preceded by a `loop_' string. Here is a list of data items specifying the habit of a crystal.

 _exptl_crystal_face_name        # not std name
 _exptl_crystal_face_description # not std name 
      0   0  -1 0.012 A 'well formed'
      0   0   1 0.012 B *
     -1   0   0 0.023 C uneven
      1   0   0 0.027 D 'needs further grinding'
      0   1   0 0.016 E *
      0  -1   0 0.015 F pitted

Any data item, independent of its type, may be included in a loop. The only requirement is that the number of data items in a loop must be an exact multiple of the number of data names in the loop definition.

Table 1. STAR File syntax and terminology

text string

data name data item data loop data block data file
Back to title page

On to The CIF Syntax

Copyright © 1991 International Union of Crystallography

IUCr Webmaster