Using pdCIFplot to display Rietveld refinement results

The crystallographic information file, (CIF) was developed by the IUCr in the early 1990's as a standardized format to document single-crystal structure determinations and to exchange the results between laboratories. In the late 1990's, the pdCIF dictionary was developed to allow CIF to document powder diffraction measurements, as well as Rietveld results. The pdCIFplot program is used to plot diffraction data stored in CIFs, with particular emphasis on the display of Rietveld refinement results. This web page documents how the program is used.


Running pdCIFplot

On Windows and Macintosh computers,pdCIFplot will usually be invoked by dragging a CIF onto the icon for pdCIFplot. Alternately, one can click on the icon and then locate the appropriate file via a file open window. One can also configure the operating system to associate a file extension (such as .CIF), so that double clicking (or in Windows left-clicking) on such a file will open that CIF in pdCIFplot. This configuration can be selected for Windows during installation. For Macintosh, the user must do this for themselves.

The pdCIFplot program is typically started on Unix computers by typing command

     pdCIFplot [file.cif]
where optionally the name of a file, file.cif, to be read is listed on the command line. If no CIF file is specified, the program will open a file browser to select a file.

example pdCIFplot screen display In windows, several mechanisms can be used to start the program, but the most convenient will likely be either clicking on the pdCIFplot icon in the start menu or desktop, depending on the software installation options. The pdCIFplot program will then open a file browser to select a file to plot. One can also configure the software so that either double clicking or left-clicking on a .CIF or .RTV file will open the CIF file in pdCIFplot.

While the CIF is being read, a message such as the one to the right will be seen.

example pdCIFplot screen display After the CIF has been read, a window listing the CIF data blocks will be shown, as is seen to the right. Note that in this example, the radiobuttons have been disabled for the first four blocks. This is because these blocks to not contain diffraction data to plot.

Menu Contents

The menu buttons have the following buttons defined:


This is the usual sort of thing found in a GUI program.
Opens a new CIF to plot.
Ends the program.


These menu items are used to create and manipulate plots.
Rietveld Plot
The "Rietveld Plot" creates a set of plot windows that show an observed and computed diffraction pattern, as well as differences and related options. Note that this option can be used with pdCIFs that contain only observed or only computed data. This option is described below in more detail.
Custom Plot
The "Custom Plot" creates a plot based on the observed or computed diffraction data, or a function of these data. The user has considerable control over what is plotted This option is also described below in more detail.
The "Export" option is used to save an image of the current plot data in a format that can be read by other programs. At present, two export formats are implemented:
  • Grace (aka xmgr and xmgrace) is a general-purpose plotting program for Unix and windows. The exported image is a close facsimile to what is seen in the selected window. However, grace can be used to annotate & customize the display further.
  • PostScript can be read by a number of programs, but these images are direct "screen dumps" and are not very high quality.


These menu items are used to display and hide special purpose windows.
Show CIF Browser
The "Show CIF Browser" button creates a separate window where the data items in the CIF can be viewed. The CIF browser is similar to that in Program CIFEDIT. However, CIFEDIT can both view and change the CIF contents while in pdCIFplot the CIF can only be viewed.
Show CIF Contents
The "Show CIF Contents" button creates a separate window that shows the actual contents of the CIF. This is also similar to that in Program CIFEDIT. However, CIFEDIT can both view and change the CIF contents from this window while in pdCIFplot the CIF contents can only be viewed.


Note the the options in this menu may be saved in a file, which will then override the default setting on future occasions when the program is run. The name of the file is .pdcifplot_cfg
on MacOS X and Unix or pdcifplot.cfg on Windows. The file is located in the user's home directory in Unix/OS X, or "C:\Documents and Settings\{username}" in Windows-2000 and -XP, but in some of the older versions of Windows (I'm not sure which), the file will be placed in C:\.
Select Dictionaries
The "Select Dictionaries" menu command is used to determine which dictionaries will be used to process the CIF. The dictionary is used in pdCIFplot primarily for showing data item definitions, so this option will not commonly be used. For more information on this option, refer to documentation for Select Dictionaries in CIFEDIT.
Screen Font
The size of the fonts used in the program can be adjusted to suit the computer display and the user preferences.
Show Duplicate Dict. defs.
When dictionaries are read, a check is made to see if data items are defined in more than one dictionary. When this occurs, the last definition that is processed is the one that is used. When the "Show Duplicate Dict. defs." data item is checked, a warning message is displayed when duplicate dictionary definitions are encountered; the message is shown every time the dictionaries are read.
Maximum data items
The pdCIFplot program reads the entire CIF into memory. This means that if a very large CIF is read, the operating system can start to "gasp for breath" (what really happens is called "churning", where the computer spends all its time page-faulting and gets nothing done.) To prevent this from happening, there is a limit on the number of CIF data items (each value in a loop is counted as an item) that will be read from a CIF. If more than this number of items is encountered, processing of the CIF is stopped and a warning message is displayed.

The maximum CIF that can be handled will depend on the capabilities of your operating system, the amount of memory and the number of other programs that are running. By default, the maximum number of data items is set to 100,000 -- which seems fine for most computers and allows CIFs as large as 0.5Mb to be read. If you have a lot of memory and want to work with big CIFs, you can raise this limit or even disable it using the "Maximim data items" option.

Save options
The "Save options" menu items causes the current dictionary settings, as well as the other option values in this menu, to be saved as described above.


Shows the version number for pdCIFplot
Web Page
Shows displays this page.

Rietveld Plot

When the "Rietveld Plot" button is pressed, a window is created, as is shown below: example pdCIFplot screen display
Note in the center, in yellow, a list of quantities, which are defined as follows
The "independent" variable, such as 2theta, TOF or some function of that variable, such as d-space or Q. All the subsequent quantities are plotted against this variable.

The the observed intensity.

The estimated error (standard uncertainty) in the observed intensity.

The computed intensity from the Rietveld structural model

The computed background intensity

The difference between the observed and computed diffraction data

The difference between the observed and computed diffraction divided by the uncertainty, so that the statistical expectation value for this quantity is 1. Note that the (obs-calc)/sig values are plotted in a separate window from the other intensity values.

Cumulative Chi
equation for cumulative chi2 functionA running sum of [(obs-calc)/sig]2 (see equation to right) that shows the sections of the pattern that have the greatest influence on chi2 and the weighted profile R-factor, Rwp. The cumulative Chi2 was introduced by W.I.F. David, in the Accuracy in Powder Diffraction-III symposium in 2001. The cumulative Chi2 is superimposed on the observed and computed pattern.

The normalization constant, n, is the scale factor that must be applied to each point so that
       n y(obs) = [n sigma(y)]2,

i.e. the value of n will be 1 for data in counts and n will be less than 1 if data have been averaged. Note that the normalization values are plotted in a separate window.

Data Items

example pdCIFplot screen display To the left of the first five quantities is a menu buttons that shows the CIF data item where the quantity is obtained. If there is only one choice to obtain a particular quantity (for example, _pd_meas_intensity_total for y(obs) in the above display), then that value is selected automatically. If there is more than one choice, for example, the x-axis in the above example, the menu button can be used to select a choice, as is shown to the right.

Plot Formatting

To the right of each of these quantities is a set of menu buttons that determines how each quantity is displayed. Note that if the symbol is set to "none" and the line is set to "no line", the quantity is not displayed.

The other controls in the right-hand column determine if error bars are shown for each observed data point, if background is subtracted from the observed and computed patterns prior to display. By default, the obs-calc data are displayed with the zero value for the obs-calc value at zero (unless automatic tick marks are used). However, if the "Offset difference plot" option is set, the difference plot is placed as close as possible to the observed and computed data without the plots overlapping.

The "Intensity rescaling" option offers four choices for use of the normalization values:

Don't renormalize
The intensity values are unmodified

Renormalize to counts
Each intensity value is multiplied by ni

Average & Renormalize
The average value of n is determined (navg) and all intensity values are is multiplied by this one navg value.

Smooth & Renormalize
The n values are smoothed, to remove any point-to-point changes and then intensity values are multipled by the the smoothed normalization values.

Reflection Locations

The section in the lower left determines if reflections positions are shown on the plot and, if they so, where they are displayed. The "Show Tickmarks" checkbox can be used to select the display of tickmarks. The "automatic" checkbox causes tickmarks to be placed directly under the observed and computed data and directly above the difference plot. When the "automatic" box is selected, an offset is applied to move the difference plot as close as possible to the tickmarks with out overlap, thus the "Offset difference plot" option is ignored. If the "automatic" box is not selected, the Ymin and Ymax values for each phase dictate where the lines are drawn. Values can be input for Ymin and Ymax as intensity values, or as a percentage of the full intensity scale, e.g. a value of 50% places a tickmark in the middle of the screen. A menu button is also available to select the color of the tickmarks.

example pdCIFplot screen display The "Reflection Index Browser" option, when selected, provides a window to show reflection indices. An example of this window is shown to the right. The window is created and reflections are added to the browser window when the mouse is moved over a reflection marker. The reflection list can be sorted using the buttons at the top of the window. The checkbuttons for each reflection allow specific reflections to be highlighted, either by having reflection indices placed on the plot window or by having a vertical line drawn, as selected by the checkbuttons at the bottom of the window.

If more than one phase is present, notebook tabs are placed in section the window so that options can specified for each phase (as can be seen below). Note that there is a color value and a Ymin and Ymax value for each phase.

Sample Plots

example pdCIFplot screen display
Plot of y(obs) [black + symbols], y(calc) [red line], obs-calc [blue line], cumulative Chi2 [cyan dashed line] and reflection positions [vertical lines].

example pdCIFplot screen display

Plot of (obs-calc)/sigma.

example pdCIFplot screen display

Plot of the normalization values, n

Multiple Data Loops

Note that there must be the same number of values for data to be plotted together. In the following example, there are two data loops, one for raw data, with 5120 data points, and one for processed and computed data, with 1648 data points. When this occurs, the Rietveld Plot window has notebook tabs for each set of data, as is seen at the top of the window shown below and either set can be selected by clicking on the tab. example pdCIFplot screen display
Note that if there are no applicable data items for a category, as is true in the above example for y(calc) and y(bck), the appropriate menu buttons are disabled and the corresponding data cannot be plotted.

Custom Plot

The "Custom Plot" option allows for plotting data in various combinations. For example, in the screen below, _pd_meas_intensity_total minus _pd_proc_intensity_bkg_calc versus _pd_proc_d_spacing will be plotted. It is possible to select what window the plot will appear. example pdCIFplot screen display


The pdCIFplot and CIFEDIT programs have been combined into a single distribution, CIFTOOLS. The executable code is the same on all platforms, however, for many common operating systems, a platform-specific Tcl/Tk shell is included in a platform-specific release. Please refer to the CIFTOOLS installation instructions for download and installation details.

The author of pdCIFplot is a U.S. Government employee, which means that pdCIFplot is not subject to copyright. Have fun with it. Modify it. Please add new features and make them available to the rest of the world.

Neither the U.S. Government nor the author makes any warranty, expressed or implied, or assumes any liability or responsibility for the use of the software or information described here. Brand names cited herein are used for identification purposes and do not constitute an endorsement by NIST.

Comments, corrections or questions:
$Revision: 1.5 $ $Date: 2003/12/29 23:31:20 $