Section 2.5.5. The structure of DDL1 definitions

A definition for formula units in a crystal unit cell (Z) is shown in Fig. 2.5.5.1. The definition includes only the attributes _name, _category, _type, _enumeration_range and _definition. These identify the item's unique properties and enable its validation. The _category attribute indicates the class of the defined data item. Since lists may contain only items of one category type, this attribute is critical to data items appearing in lists (see Section 2.5.5.5). The attribute _enumeration_range has the value ` 1:' which stipulates that the item must be `one or a higher number'.

Figure 2.5.5.1 | top | pdf | DDL1 definition with a few attributes.

A CIF dictionary file contains, in addition to the data definitions, information about the nature of the dictionary. Fig. 2.5.5.2 shows the typical organization of definitions in a dictionary. Each dictionary starts with the audit information giving its version and creation history. This is followed by definitions in separate data blocks. The name of a data block matches the defined data name or the initial portion thereof. Each definition data block contains a sequence of data declarations, one for each attribute. The attributes within a data block constitute the total definition information, and only those attributes appropriate to a given defined item need be specified.

Figure 2.5.5.2 | top | pdf | DDL1 definition showing basic dictionary organization.

Some data items are closely related to other data items. Fig. 2.5.5.3 shows the definition of the length components _cell_length_a, *_b and *_c of the crystal unit-cell metric tensor. Because of their different enumeration and units attributes, the definition blocks for cell lengths and angles are specified separately. This definition shows how data items closely related in function may be defined in the same data block. The loop_ command is used to list the multiple _name values. The attribute _type_conditions is used to indicate that these values are measurements and can have a standard uncertainty (`s.u.') value appended in parentheses e.g. 7.254(2). (The label `esd' reflects the historical but inaccurate terminology `estimated standard deviation'.) The _units and _units_detail attributes stipulate that the measurement unit of length is ångströms.

Figure 2.5.5.3 | top | pdf | DDL1 definition of irreducible data items.

The definition of the number of hydrogen atoms attached to an atom site is shown in Fig. 2.5.5.4. The attributes _list and _list_reference signal whether the item is used in a list and what key item is in that list. As described in Chapters 2.1 and 2.2 , a CIF list is a two-dimensional table where data items are in the columns (headed by the data names) and the values are the rows. The attribute _list is yes if a data item may be used in a list. The attribute _list_reference specifies the key item as _atom_site_label. Each value of a key item must be unique so that the row of associated items can be accessed unambiguously. The attribute _enumeration_default specifies a default value for the defined item if it is absent from the data file.

Figure 2.5.5.4 | top | pdf | DDL1 definition of a `list' data item.

Each CIF dictionary also contains example applications of defined data items, grouped according to category. Fig. 2.5.5.5 shows these for the category ATOM_SITE, as defined in the core dictionary (see Chapter 3.2 ). A _type attribute with a value of null specifies that a data block contains no definition information. The particular examples shown here illustrate that the reference key for the ATOM_SITE category is _atom_site_label. This data item is present in both examples shown, and in each packet the label is unique.

Figure 2.5.5.5 | top | pdf | DDL1 overview of a category of items.

The example definition in Fig. 2.5.5.6 shows the attributes for the item _atom_site_label. As illustrated in Section 2.5.5.5, this item is the reference key to a list of items belonging to the category ATOM_SITE. The attribute _list_mandatory, which is set to a value of yes, specifies that this item is a mandatory item to a list of category ATOM_SITE items. The attribute _list_link_child identifies items in other categories that are `linked' by derivation to this item and therefore share the same data values. This dependency is known as a child dependency. The definition shows that data items describing the labels of atom sites in a list of angular geometry, i.e. _geom_angle_atom_site_label_1 and _geom_angle_atom_site_label_2, are the same labels described by _atom_site_label in the atom-site list. This is because the geometry is derived directly from the atom-site data. Note that this dependency requires that the ATOM_SITE list be present in the same CIF as the GEOM_ANGLE list, otherwise the molecular geometry information cannot be linked to the three-dimensional structural information.

Figure 2.5.5.6 | top | pdf | DDL1 definition of a `mandatory' data item.

In the example definition shown in Fig. 2.5.5.7, the key item _atom_site_aniso_label is shown to have a special relationship with the key item _atom_site_label. This is because the data items in the list category ATOM_SITE_ANISO may be merged with (i.e. joined to) items in the list category ATOM_SITE. If this happens, the item _atom_site_label assumes the role as the key to the merged packets and this is signalled using the attribute _list_link_parent. When these two categories appear in separate lists, the category ATOM_SITE_ANISO data require the category ATOM_SITE data to be present in the data instantiation, but not vice versa. Note that the parent relationship, unlike that in the example of Section 2.5.5.6 arising from a derivation dependency, is because ATOM_SITE_ANISO is a subcategory of ATOM_SITE.

Figure 2.5.5.7 | top | pdf | DDL1 definition of a `parent' data item.

As with the preceding example definition, this example concerns anisotropic atomic displacement parameters. Fig. 2.5.5.8 shows the definition of the component items _atom_site_aniso_U_ that comprise an irreducible set of matrix elements. The key item in a list of ATOM_SITE_ANISO items is _atom_site_aniso_label. This definition illustrates how the attributes _related_item and _related_function are used to identify the similar data items _atom_site_aniso_B_ that are atomic displacement parameters related by a simple conversion factor. Other attributes used to specify data relationships are described in Section 2.5.6 below.

Figure 2.5.5.8 | top | pdf | DDL1 definition showing `related' data items.

The last example, in Fig. 2.5.5.9, shows the definition of an item whose value is restricted to a predictable set of values known as enumeration states. The attributes _enumeration and _enumeration_detail are used to specify which enumeration states are permitted for the defined data item. Only one of these states may appear as the value for the defined item in a CIF. The attribute _enumeration_default specifies the state value that is used if an item is not instantiated.

Figure 2.5.5.9 | top | pdf | DDL1 definition showing enumeration states.