The python distutils installer places three files into the python packages directory: CifFile.py, yappsrt.py and YappsCifParser.py. It is sufficient to import CifFile.py to access all PyCifRW features:
CIF files are represented in PyCIFRW as CifFile objects. These objects behave identically to Python dictionaries, with some additional methods. CIF files can be created by initialising a CifFile object with a filename:
Alternatively, a new CifFile object is created if no datasource argument is given:
cf['a_block'] = myblock
The simplest form of access is using standard Python square bracket notation. Data blocks and data names within each data block are referenced identically to normal Python dictionaries:
If a data name occurs in a loop, a list of string values is returned. However, in practice, looped data is usually only useful in combination with other values from the same loop. CifBlock method GetLoop(dataname) will return all data in the loop containing dataname in the format [(dataname,datavalues),...]. Method loops() returns a list where each item is a list of datanames occurring in a single loop of the CifBlock object.
If many operations are going to be performed on a single data block, it is convenient to assign that block to a new variable:
cb['_old_data_name'] = 'cucumber'
If a list is given as the value instead of a single string or number, a new loop is created containing this one data name, looped. Any looped data values which may have co-occurred in the loop are first deleted. As this is not necessarily the desired behaviour, you should call AddCifItem directly - this routine is always called when assigning values to a CifBlock item.
AddCifItem is called with a single tuple argument. The tuple contains either a single dataname, or a list or tuple of datanames as its first element. The second element is either a single value or list of values (in the case of a single key) or a list, each element of which is a list of values corresponding to a single dataname. Note that PyCIFRW works with columns of loop data (complete values for each data name in the loop) rather than rows (one value for each dataname in the loop).
AddCifItem will always create a new loop after deleting any datanames and values already in the data block, so it is impossible to add new data names to existing loops. Method AddToLoop(dataname,newdata) adds newdata to the pre-existing loop containing dataname, silently overwriting duplicate data. Newdata should be a Python dictionary of dataname - datavalue pairs, with datavalue a list of new/replacement values.
Note that lists returned by PyCIFRW actually access the list inside the CifBlock, and therefore any modification to them will modify the stored list. If you intend to alter any such lists, you should first copy them to avoid destroying the loop structure:
mysym.append('x-1/2,y+1/2,z')
_symmetry
x,y,z
-x,-y,-z
x+1/2,y,z
[['123.4','small cell'],
['4567.8','large cell']])
_example
_example_detail
123.4 'small cell'
4567.8 'large cell'
'_example',{'_comment':[''not that small'',''Big and beautiful'']}
)
_example
_example_detail
_comment
123.4 'small cell' 'not that small'
4567.8 'large cell' 'Big and beautiful'
_example
_example_detail
_comment
12.2 'small cell' 'not that small'
12004 'large cell' 'Big and beautiful'
PyCifRW does not (yet) directly support this: the following code shows one way to accomplish this indirectly for the above example.
'_example_detail':['medium cell','also medium'],
'_comment':['manageable','still manageable']
}
olddata = cb.GetLoop('_example') #(key,value) list
map(lambda a:newdata[a[0]].extend(a[1]),loopdata)
cb.AddCifItem((newdata.keys(),newdata.values()))
The CifFile method WriteOut returns a string which may be passed to an open file descriptor:
>>>outfile.write(cf.WriteOut())
DDL dictionaries may also be read into CifFile objects. For this purpose, CifBlock objects automatically support save frames (used in DDL2 dictionaries), which are accessed using the ``saves'' key. The value of this key is a collection of CifBlock objects indexed by save frame name, and available operations are similar to those available for a CifFile, which is also a collection of CifBlocks.
A CifDic object hides the difference between DDL1 dictionaries, where all definitions are separate data blocks, and DDL2 dictionaries, where all definitions are in save frames of a single data block. A CifDic is initialised with a single file name or CifFile object:
A top level function is provided for convenient validation of CIF files:
If a simple validation report is required, the function validate_report can be called on the output of the above function, printing a simple ASCII report. This function can be studied as an example of how to process the complex structure returned by the 'validate' function.
A ValidCifFile object behaves identically to a CifFile object with the additional characteristic that it is valid against the given dictionary object. Any attempt to set a data value, or add or remove a data name, that would invalidate the object raises a ValidCifFile error.
Additional keywords for initialisation are:
PyCIFRW provides a top-level function to merge DDL1/2 dictionary files. It takes a list of CIF filenames or CifFile objects, and a mergemode keyword argument. CIF files are merged from left to right, that is, the second file in the list is merged into the first file in the list and so on.
For completeness we list the arguments of the CifFile merge method:
In overlay mode, the COMCIFS recommendations require that, when both definitions contain identical attributes which can be looped, the merging process should construct those loops and include both sets of data in the new loop.
This is not yet implemented in PyCIFRW, as it involves checking the DDL1/DDL2 spec to determine which attributes may be looped together.
A program which uses PyCIFRW for validation, validate_cif.py, is included in the distribution in the Programs subdirectory. It will validate a CIF file (including dictionaries) against one or more dictionaries which may be specified by name and version or as a filename on the local disk. If name and version are specified, the IUCr canonical registry or a local registry is used to find the dictionary and download it if necessary.
The source files are in a literate programming format (noweb) with file extension .nw. HTML documentation generated from these files and containing both code and copious comments is included in the downloaded package. Details of interpretation of the current standards as relates to validation can be found in these files.
This document was generated using the LaTeX2HTML translator Version 2002-2-1 (1.70)
Copyright © 1993, 1994, 1995, 1996,
Nikos Drakos,
Computer Based Learning Unit, University of Leeds.
Copyright © 1997, 1998, 1999,
Ross Moore,
Mathematics Department, Macquarie University, Sydney.
The command line arguments were:
latex2html -no_subdir -split 0 -show_section_numbers /tmp/lyx_tmpdir7557e62NqG/lyx_tmpbuf0/documentation.tex
The translation was initiated by James Hester on 2005-07-22
James Hester 2005-07-22