Discussion List Archives

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

Recent changes to CoreCIF

  • Subject: Recent changes to CoreCIF
  • From: David Brown <idbrown@xxxxxxxxxxx>
  • Date: Fri, 28 Jan 2005 14:09:07 -0500
I have appended to this email a document that outlines some of the 
recent changes to the coreCIF dictionary and explains some CIF 
conventions.  I hope this will prove useful to those of you writing 
software that uses the coreCIF dictionary.

It is inevitable that CIF will evolve, even though we are committed to 
retain the earlier dictionary versions needed to read archival CIFs.  
Software should be designed to allow for this evolution, for example, by 
reading a CIF together with the version of the dictionary that was used 
to create it.

Let me know if you have any comments

David Brown
Chair of COMCIFS

++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++

                   SOME NOTES ON THE USE OF CORE CIF (2005-01-28)

by I.D.Brown  idbrown@mcmaster.ca (Chair of COMCIFS)

1. SUMMARY
----------
These notes are designed to assist those who write software or prepare
templates for reading and writing CIFs.  They draw attention to recent 
changes
in the core CIF dictionary and clarify some matters of usage.

2. INTRODUCTION
---------------
The CORE CIF DICTIONARY version 2.3 was released in October 2003.  In 
addition
to defining a number of new items requested for special uses, it includes a
number of changes that are of more general interest.  The IUCr 
recommends that
these changes be adopted in any software and templates designed for reading
and writing CIFs that use the core CIF dictionary.  Most of the change are a
response to the development of editors such as enCIFer and CIFEDIT that 
check
the items in the CIF against the dictionary used to construct the CIF to
ensure proper conformity.  These changes look forward to the day when 
CIF will
be used as the language of many crystallographic application such as the
proposed interactive on-line version of International Tables. 

The principal change in version 2.3 is the replacement of the SYMMETRY
categories by SPACE_GROUP categories taken from the new symmetry CIF
dictionary.  The other changes fall into two classes, new items and 
items that
replace existing items.  All of the items that have been replaced are still
retained in version 2.3 to facilitate the change over, but there is no
guarantee that they will be included in future releases.  It is strongly
recommended that the obsolete items be replaced by the new items in any new
software or template.  Full details of the changes can be found in 
version 2.3
of the core CIF dictionary which is available on the IUCr web site:
ftp://ftp.iucr.org/pub/cif_core.2.3.dic.  Check the _dictionary_history 
items
at the beginning of the dictionary to identify the changes.

Because there are several version of the core CIF dictionary, this document
recommends that every CIF identify the dictionary and version that was 
used in
its creation (see below).  In this way software will be able to recognize
which dictionary should be used to interpret the CIF.

3. SYMMETRY AND SPACE_GROUP CHANGES
----------------------------------- 

The SYMMETRY categories as included in earlier versions of the 
dictionary have
a number of weaknesses.  For example _symmetry_cell_setting is an incorrect
and misleading name for the crystal system, and the rules for 
construction of
the Herman-Mauguin symbol given in the dictionary have (perhaps for good
reasons) rarely been followed in practice.  Further, the early versions 
of the
dictionary did not provide for the labelling of the different symmetry
operations with a unique identifier.  According to CIF rules all loops 
require
an item with a unique value to identify each line in the loop.  The GEOM 
loops
make use of an implicit symmetry operation identifier based on the order in
which the symmetry operations are listed in the loop, but according to CIF
rules this order can be changed during subsequent processing of the CIF.  If
this happens the information about symmetry relationships given in the GEOM
loops is lost.  A further weakness is that the SYMMETRY items are not 
readily
extendable to describe more advanced concepts such as special positions and
modulated structures, or to allow on-line access to information available in
International Tables.  As a result of these weaknesses, the symCIF 
dictionary
was created to provide a more rational basis for the description of 
symmetry.
Some of the items in this dictionary have now been incorporated into version
2.3 of the core CIF dictionary.  Software should switch to using the
SPACE_GROUP datanames described below in order to allow for the better
handling of symmetry information in the future.

The definitions of the items listed below have not changed except for the
Hermann-Mauguin symbol.  The symCIF dictionary defines several different 
forms
for the Hermann-Mauguin space group symbol, the most flexible of these,
_space_group_name_H-M_alt, corresponds to the current CIF practice in 
the use
of _symmetry_space_group_name_H-M.  It allows the author to use any desired
form or setting of the Hermann-Mauguin symbol.

The following SYMMETRY items are now obsolete:

   _symmetry_cell_setting           monoclinic
   _symmetry_space_group_name_H-M    'C 2/c'
   _symmetry_space_group_name_Hall   '-C 2yc' 
  loop_
   _symmetry_equiv_pos_as_xyz
          x,y,z         
         -x,-y,-z       
         -x,1/2+y,1/2-z 
          x,1/2-y,1/2+z 

The corresponding SPACE_GROUP names having essentially the same definitions
are:

    _space_group_crystal_system     monoclinic
    _space_group_name_H-M_alt       'C 2/c'
    _space_group_name_Hall          '-C 2yc'
   loop_
    _space_group_symop_id
    _space_group_symop_operation_xyz
      1    x,y,z         
      2   -x,-y,-z       
      3   -x,1/2+y,1/2-z 
      4    x,1/2-y,1/2+z 


NEW ITEMS IN VERSION 2.3
------------------------

Some of the new items added to version 2.3 of the core CIF dictionary 
that may
be of interest to those preparing software or templates are:
 
                     _chemical_properties_biological
                     _chemical_properties_physical
                     _chemical_temperature_decomposition
                     _chemical_properties_sublimation
                     _refine_ls_shift/su_max_lt
                     _refine_ls_shift/su_mean_lt

The first two items have text fields, the remainder are numeric.  The 
last two
items are designed to avoid the problem that a 'less than' sign (< ) is not
allowed in numeric fields.

4. ITEMS REPLACING EXISTING ITEMS
--------------------------------- 

The replacement items generally have better or more appropriate 
definitions.
In each case the reasons for the change are given.

 _atom_site_refinement_flags is replaced by

                     _atom_site_refinement_flags_posn
                     _atom_site_refinement_flags_adp
                     _atom_site_refinement_flags_occupancy

REASON: Splitting the refinement_flags into three groups makes it 
possible to
list the permitted combinations of flags in the dictionary.  This allows
editors and browsers to check the validity of the flags against the
dictionary.

The new items:
                     _diffrn_reflns_resolution_full
                     _diffrn_reflns_resolution_max

may be used as an alternative to:

                     _diffrn_reflns_theta_full
                     _diffrn_reflns_theta_max

REASON: Resolution in reciprocal Angstroms is a more fundamental 
property than
the maximum diffraction angle which depends on the wavelength used.

_exptl_crystal_colour is replaced by

                     _exptl_crystal_colour_primary
                     _exptl_crystal_colour_modifier
                     _exptl_crystal_colour_lustre

REASON: Version 2.3 contains an enumeration list of the allowed colours
following the conventions adopted in the Powder Diffraction File.  Splitting
the colour into three components allows editors to check that correct flags
are used. (N.B. 'colour' and 'colourless' are spelled according to English
spelling convention.)

5. NOTES ON SOME CIF CONVENTIONS
-------------------------------- 

Default values
--------------
In some cases if an item is not given, the dictionary provides a default
value, that is, a value that can be assumed.  Only a few items have defaults
and some of the defaults given in the earlier versions of the core 
dictionary
have been removed.  One example where a default value is necessary is
_atom_site_occupancy whose default value is 1.0.  In cases where no 
default is
specified in the dictonary the value is undefined and a default value should
not arbitrarily be assumed.

What to use if the value of a field is unknown or meaningless.
--------------------------------------------------------------
When no value can be given for an item there are two symbols that may be 
used,
the period (.) and the question mark (?). 

The PERIOD indicates that the concept is undefined and has no value in the
present context.  An example is the item _diffrn_standards_interval_count in
the case where standard reflections were not used to monitor the decay 
of the
diffraction intensities.  It can also be used to indicate a defaulted value
where such exists though it is better to give the value explicitly.  It even
sometimes used where no default is formally defined as in the
_geom_*_site_symmetry items where 1_555 is generally assumed (though not
defined in the dictioanry). 

The QUESTION MARK is used when the item has a value, but the value is not
known or not needed.  An example is _exptl_crystal_density_meas when the
density has not been measured.  The quesion mark may also indicate an unused
text field, but in this case it should not be delimited by quotes or
semicolons since this converts it to a text character, and placing the
question mark in such a text field will result in it being displayed or
printed as a question mark.

Permitted ranges of experimental values with standard uncertainties.
--------------------------------------------------------------------
Measured values may, because of experimental uncertainties, occasionally lie
outside the ranges specified in the dictionary.  In such cases, the allowed
range should be extended by three standard deviations.  Thus the dictionary
defines the permitted range for occupation numbers as 0 to 1.0, but 
values of
-0.1(1) and 1.2(1) are permissible since the standard uncertainty 
extends the
range from -0.3 to 1.3.  Software testing the validity of the value of any
number with a standard uncertainty should extend the range given in the
dictionary by three standard uncertainties.  Standard uncertainties can be
used on occasions when one might otherwise use a less-than symbol.  For
example the item _diffrn_standards_decay_% is often given a value such as <2
which is illegal because numeric fields may not contain the < sign.  The 
same
information should more correctly be given as 0.0(7). 

Identifying the dictionary version used to generate the CIF.
------------------------------------------------------------ 
With the advent of CIF editors and browsers, such enCIFer and CIFEDIT, that
check the CIF directly against the core dictionary, it is becoming necessary
to identify which version of the core CIF dictionary (or other 
dictionary) was
used to prepare the CIF.  This information should be included in the CIF,
preferably at the beginning, using the AUDIT_CONFORM items:

_audit_conform_dict_name               cif_core.dic
_audit_conform_dict_version            2.3
_audit_conform_dict_location           
ftp://ftp.iucr.org/pub/cif_core.2.3.dic

It is expected that future editors and browsers will check these items 
in the
CIF in order to load the version of the dictionary that was used to 
create the
CIF, if necessary downloading the dictionary from the IUCr web site.  These
items may be looped if more than one dictionary was used.

begin:vcard
fn:I.David Brown
n:Brown;I.David
org:McMaster University;Brockhouse Institute for Materials Research
adr:;;King St. W;Hamilton;Ontario;L8S 4M1;Canada
email;internet:idbrown@mcmaster.ca
title:Professor Emeritus
tel;work:+905 525 9140 x 24710
tel;fax:+905 521 2773
version:2.1
end:vcard

_______________________________________________
cif-developers mailing list
cif-developers@iucr.org
http://scripts.iucr.org/mailman/listinfo/cif-developers

Reply to: [list | sender only]
International Union of Crystallography

Scientific Union Member of the International Council for Science (admitted 1947). Member of CODATA, the ICSU Committee on Data. Member of ICSTI, the International Council for Scientific and Technical Information. Partner with UNESCO, the United Nations Educational, Scientific and Cultural Organization in the International Year of Crystallography 2014.

ICSU Scientific Freedom Policy

The IUCr observes the basic policy of non-discrimination and affirms the right and freedom of scientists to associate in international scientific activity without regard to such factors as ethnic origin, religion, citizenship, language, political stance, gender, sex or age, in accordance with the Statutes of the International Council for Science.