source: trunk/doc/liveplot.html @ 465

Last change on this file since 465 was 464, checked in by toby, 11 years ago

# on 2001/10/18 23:17:12, toby did:
new key bindings for reflection labels

  • Property rcs:author set to toby
  • Property rcs:date set to 2001/10/18 23:17:12
  • Property rcs:lines set to +33 -15
  • Property rcs:rev set to 1.5
  • Property rcs:state set to Exp
  • Property svn:keywords set to Author Date Revision Id
File size: 21.7 KB
Line 
1<html>
2<head>
3   <META NAME="Author" CONTENT="Brian H. Toby">
4   <title>EXPGUI -- LIVEPLOT/BKGEDIT</title>
5</head>
6<BODY BGCOLOR="#FFFFFF">
7
8<A HREF=http://www.ncnr.nist.gov>
9<IMG SRC="http://www.ncnr.nist.gov/images/ncnrtrans.gif" 
10alt="Link to NIST Center for Neutron Research home page"
11ALIGN=RIGHT></A>
12<A HREF="http://www.nist.gov">
13<IMG SRC="http://www.ncnr.nist.gov/images/webidblue_2lineright.gif" 
14alt="Link to National Institute of Standards & Technology home page"
15ALIGN=LEFT></A>
16<CENTER>
17<A Href="http://www.ncnr.nist.gov/programs/crystallography/software/tclpkgs.html">
18<IMG SRC="tcltklogo100.gif" 
19alt="Link to Tcl/Tk information">
20</CENTER></A>
21<br clear=all><hr>
22
23<TABLE BORDER BGCOLOR="#FFFF40" ALIGN=RIGHT>
24<TR><TH><A  Href="expgui.html">EXPGUI top</A> 
25</TH><TH><A Href="excledt.html">Next page (EXCLEDT)</A>
26</TH><TH><A Href="expguic.html">Previous page</A>
27</TH></TR></TABLE><BR CLEAR=ALL>
28
29
30<center><h1>
31EXPGUI Utilities (1), LIVEPLOT and BKGEDIT
32</h1></center>
33This page documents the LIVEPLOT and BKGEDIT utility programs
34in the EXPGUI package.
35LIVEPLOT and BKGEDIT are actually the same program, but perform
36different functions, depending on how they are invoked.
37LIVEPLOT is used to display the quality of the diffraction fit, while
38BKGEDIT is used to fit a background function to fixed background points
39that have been input by the user.
40<P>
41Both LIVEPLOT and BKGEDIT get the current diffraction information
42by running the TCLDUMP program, if installed, or
43HSTDUMP otherwise. The TCLDUMP program has been optimized for use
44with LIVEPLOT and offers a number of extra
45options that are not available when HSTDUMP is used. Since TCLDUMP has been
46included in GSAS since April of 2000, it is assumed that this is now the case.
47
48<a name="liveplot"></a>
49<H3>LIVEPLOT</H3>
50LIVEPLOT is started by pressing the LIVEPLOT button on the toolbar
51or via the Graphs/liveplot menu item.
52<P>
53Some of the features available in LIVEPLOT are:
54<UL>
55<LI>The plot is updated automatically after each refinement run
56<LI>The plot can be zoomed, by clicking on the corners of the
57area to be magnified.
58<LI>
59The units used for plotting histograms can be selected. Choices are:
60native units (2Theta/TOF/KeV); d-space (A) or Q (A<sup>-1</sup>)
61<LI>
62The background (fixed plus fitted) can be plotted or can be subtracted.
63<LI>
64Reflection tickmarks can be displayed in a variety of formats
65<LI>
66LIVEPLOT can be coupled to the LOGIC or CMPR programs, so that
67peak positions from an ICDD entry or for an arbitrary unit cell and
68spacegroup can be shown superimposed on the "Rietveld plot."
69<LI>
70<IMG SRC="note.gif" alt="Note!">
71Reflection indices (<I>hkl</I> values) can be shown for tickmarks
72<LI>
73<IMG SRC="new.gif" HEIGHT=13 WIDTH=36 alt="New!">
74The cumulative chi<sup>2</sup> function can be plotted.
75</UL>
76
77<a name="bkgedit"></a>
78<H3>BKGEDIT</H3>
79<IMG SRC="new.gif" HEIGHT=13 WIDTH=36 alt="New!">
80For most refinements, it is possible to simply select a background
81function (I find that the type 1 function,
82shifted Chebyschev polynomials, work well)
83and then refine, adding terms until a good fit is obtained.
84On occasion, poor initial fits are obtained in this manner. This is
85most common in cases where large numbers of peaks are poorly fit. Since
86significant sections of the data are not well fit, the refinement results in
87an unreasonable background function, because this yields better agreement
88with the observed data.
89In these cases,
90it may be best to fix the background to follow a "reasonable" curve in the
91initial stages and then refine the background in the final stages of
92refinement, when a good model has been obtained.
93<P>
94The BKGEDIT program, as shown below, is used to input a set a background
95points via the mouse. The points are then used to determine a type 1
96(Chebyschev) background function that fits the input background points. These
97terms can then be saved in the experiment file creating a background that
98is good enough for the initial stages of refinement and that can be
99refined once the model is adequate for the task.
100<P>
101<IMG SRC="b1.gif" align=TEXTOP alt="BKGEDIT screen image">
102<H4>Steps in fitting a background function</H4>
103The BKGEDIT program is started from
104via the Powder/bkgedit menu item or by pressing the
105"Fit Background Graphically" button on the
106<A href="expgui3.html#EditBackground">"Edit Background"</A>
107dialog box (invoked from the "Edit Background" button on the
108<A href="expgui3.html">Histogram pane</A>.)
109toolbar
110or
111<OL>
112<LI><a href="#zoom">Zoom in</a> on the lower intensity section of the
113plot, so that the background is clearly discernible. In some cases, the
114data will need to be handled in sections.
115<LI>Press the "Add" button to add background points.
116Note the cursor changes from cross-hairs to an arrow,
117when the "Add" button is pressed.
118<LI>Move the mouse to the first location
119where a background point will be added and click with the left
120mouse button. A magenta triangle will appear at the location.
121Points can be added in any order. It is best to make sure that the fixed points
122are placed over the entire range of the data, e.g. near the maximum and minimum
123data points in TOF, 2theta, etc.
124<DL><DL>
125Note that it is advisable to place many background points in areas where
126the background varies greatly.
127</DL></DL>
128As background points are entered, they are saved in a file named
129<I>EXPNAM</I><tt>.bkg</tt><I>N</I>, where
130<I>EXPNAM</I> is the experiment name and <I>N</I> is the histogram number.
131If BKGEDIT is restarted at some later time, these points are reread.
132<LI>If any points are placed in incorrect positions, they can be deleted by
133pressing the "Delete" button. The mouse cursor changes to a circle. When
134the mouse left clicked, the fixed background point closest to the mouse
135position (which may be outside the zoom range) is deleted.
136<LI>Background points can also be edited by entering numbers into the
137"Background points" area.
138<LI>After enough background points have been entered, the
139"Start Fit" button turns from gray to black. When pressed, the Chebyschev
140polynomial is fitted and the resulting curve is shown as a blue dashed line.
141<DL><DL>
142It is suggested that you start with relatively few
143terms and add terms and background points as needed.
144Note that the maximum number of Chebyschev terms increases as
145more background points are entered.
146</DL></DL>
147The "Improve Fit" button is black when the fit did not
148converge or the number of terms has been changed. "Improve Fit" causes the
149fit to be refined starting from the previous values.
150<LI>Editing the Chebyschev terms is possible. The curve is reevaluated as
151changes are made.
152<LI>Once a good background function is determined, it can be saved in the
153experiment file by pressing the "Save in EXP file & Exit" button. This will
154set the background type to 1, and save the Chebyschev terms.
155It will also turn off
156the background refinement flag for the appropriate histogram so that the
157terms are not refined inadvertently.
158</OL>
159
160<P>
161Note that POWPREF must be run at least once before BKGEDIT can be used,
162however, use of
163GENLES before BKGEDIT is optional. If the data range is changed, for example
164by excluding a section of the data at the lower end, or changing tmax (dmin),
165the Chebyschev polynomial terms must change to generate the same
166background values, so both POWPREF and BKGEDIT should be rerun to
167regenerate the Chebyschev terms.
168
169<H4>Why not use fixed background points?</H4>
170I personally feel that
171a refined background function is preferrable to use of a fixed model,
172if at all possible.
173One reason for this is that Rietveld refinements usually achieve better fits
174when the background is optimized. A second reason refining the background
175provides a
176feel for the interaction between background values and displacement
177(thermal) parameters.
178Usually, background and displacement parameters are fairly independent, but
179for some materials, where the high Q (high 2theta) portion of the pattern
180has many completely overlapped peaks, it is impossible to uniquely
181determine where the
182background should be placed, either by refinement or by manual placement.
183Under these circumstances, the background should be refined with the
184displacement parameters fixed at an appropriate value for the material. The
185background should then be fixed for all future refinements
186and the displacement parameters can then be refined. <I>Of course this
187means you have predjudiced the refinement to result in the expected
188average displacement parameter and this </I><B>must</B><I> be noted
189any publication. However, if this is necessary, the data simply do not
190contain sufficient information to independently determine
191background and displacement parameters. Use of fixed background points
192would not demonstrate this and would lead the researcher to a false
193sense of security (or fear, if the values are unreasonable)
194that the displacement parameters actually mean something.</I>
195<P>
196If you still want to use fixed background points, despite this tirade,
197be sure to set the estimated
198error on those points to be 0.0. Use of non-zero estimated errors, can
199result in artificially lowered R-factors and chi-squared values.
200In one test, I was able to lower the R<sub>wp</sub> and
201reduced chi<sup>2</sup> values,
202from the correct values of 0.042 and 3.0, respectively, to misleading
203values of 0.036 and 0.8,
204respectively. [As expected, the R(F<sup>2</sup>) stayed constant at 0.045;
205FYI, refining the background caused R(F<sup>2</sup>) to drop to 0.036.]
206<P>
207If the background is so truly irregular that only use of fixed background
208points will do,
209BKGEDIT can be used to generate these fixed background points.
210The file used by BKGEDIT to save these points,
211<I>EXPNAM</I><tt>.bkg</tt><I>N</I>,
212can be read into EXPEDT by typing "@R" at the initial prompt
213in EXPEDT:
214<PRE>
215   Is this the file you wish to use? (<?>,D,K,Q,R,Y) ><u>@r</u>
216</PRE>
217prompt and then supplying the name of the file, in response to the next prompt:
218<PRE>
219   Enter the name of your macro file: <u>GARNET.bkg1</u>
220</PRE>
221And this will enter the background points entered into BKGEDIT as GSAS
222fixed background points. If you do this you do not want to fit and enter
223Note that you are allowed to use both fixed and a refined background together,
224though this is seldom done.
225
226<hr><h2>LIVEPLOT/BKGEDIT Features</h2>
227<a name="zoom"></a>
228<B>Plot zooming</B>
229When the left (usual) mouse button is pressed, this defines one corner
230of a region to be magnified, as is shown to the right.
231If the mouse is then moved, the diagonal
232corner of this magnification region is defined. When the left mouse button
233is pressed a second time, the selected section of the plot is magnified to
234fill the entire plot.
235<P>
236Zoom settings are saved.
237If the right mouse button is pressed, the previous zoom setting is used,
238so that the left mouse button is used to "zoom in" and the right mouse
239button is used to "zoom out."
240
241<P>
242<h2>Features in LIVEPLOT only</h2>
243<img SRC="lz.gif" BORDER=3 align=RIGHT alt="LIVEPLOT Screen snapshot">
244<a name="Cchi2"></a>
245<B>The cumulative chi<sup>2</sup></B>
246function was first suggested by
247Bill David as a way to see which reflections have the greatest influence on
248chi<sup>2</sup> [W.I.F. David, <I>Accuracy in Powder Diffraction-III</I>, 2001].
249It is defined for point j as
250<IMG SRC="cchi2.gif" alt="equation for cumulative chi2 function" ALIGN=TOP>
251where y<sub>obs,i</sub> and y<sub>calc,i</sub> are the observed and computed
252data points and sigma<sub>i</sub> is the expected error. Thus, the statistically
253expected value for
254[(y<sub>obs,i</sub>-y<sub>calc,i</sub>)/sigma<sub>i</sub>]<sup>2</sup> is 1
255and this function should rise in a smooth line if all points are fitted as
256statistically expected.
257<P>
258In the plot to the right, the cumulative chi<sup>2</sup> function is shown in
259purple. Note that first peak is not well fit, but the low angle "shoulder" is
260as important as the peak misfitting, with respect to the chi<sup>2</sup>.
261<br clear=all>
262<P>
263<img SRC="lind.gif" BORDER=3 align=RIGHT alt="LIVEPLOT Screen snapshot">
264<B>Reflection indices</B>
265are be displayed by pressing "H" or "h" while the
266mouse is near a reflection (holding the shift key while
267pressing the left mouse button also works, but sometimes interferes with the
268zoom feature).
269Pressing "A" or "a" shows all reflections in the displayed region.
270The indices are shown
271on the screen for phases with tickmarks (as shown to the right).
272Indices are listed in the "Separate window for <I>hkl</I> labels"
273(as seen below) for all phases, regardless of the tickmark settings.
274Displayed indices will remain on the screen for a preset time and
275then will be deleted; alternately, pressing "D" or "d" deletes the hkl labels.
276Several aspects of reflection labeling can be customized,
277see the <a href="#hklOpts">HKL labeling options</a> for further information.
278
279<img SRC="lind1.gif" align=LEFT alt="LIVEPLOT Screen snapshot">
280<P>
281<br clear=all>
282
283<hr><h2>LIVEPLOT/BKGEDIT Menu Contents</h2>
284A few of these options are omitted from BKGEDIT.
285<img SRC="lm1.gif" align=RIGHT alt="LIVEPLOT Menu">
286<H3>File Menu</H3>
287<DL><DL>
288<DT>Tickmarks
289<DD>Checkbuttons are provided for each phase to determine if tick marks
290are shown. See the Options/"Configure Tickmarks"menu item for information
291on tickmarks
292<DT>Histogram
293<DD>This allows a histogram to be selected to be loaded
294<DT>Update Plot
295<DD>The causes LIVEPLOT to read read the current histogram again from
296the datafile
297<DT>Make PostScript
298<DD>Creates a low quality PostScript file containing the LIVEPLOT
299output. See the Options/"Set PS output" button for where the file is created.
300<DT>Quit
301<DD>Exits BKGEDIT/LIVEPLOT.
302</DL></DL>
303<br clear=all>
304<img SRC="lm2.gif" align=RIGHT alt="LIVEPLOT Menu">
305<H3>Options Menu</H3>
306<DL><DL>
307<DT>Configure Tickmarks
308<DD>Tickmarks can be placed automatically, similar to their
309 placement in POWPLOT or can be drawn one height to another. The default
310is for lines to be draw from "-Inf" to "Inf", which creates lines from the
311bottom to the top of the plot. The options for each phase allow the line to be changed between solid and dashed, color of the line can be specified and
312the vertical placement of the tickmarks can be specified. The "show" flag,
313set in the File/Tickmarks menu can also be changed here.
314<DT>Obs Symbol (Symbol Type)
315<DD>This brings up a menu where the symbol type and size for the
316observed data points (and for BKGEDIT, the fixed background points)
317can be selected.
318<DT>Symbol Color
319<DD>The colors for all the displayed lines and symbols can be changed here.
320<DT>X units
321<DD>The x units can be selected here. The choices are
322"as collected" (2Theta/TOF/KeV), d-space (A) or Q (A<sup>-1</sup>)
323<DT>Y units
324<DD>The intensity values can be normalized by the incident spectrum
325(for energy dispersive methods).
326</DL></DL>
327<br clear=all>
328<img SRC="lm3.gif" align=RIGHT alt="LIVEPLOT menu">
329<a name="hklOpts"></a>
330<DL><DL>
331<DT>HKL labeling
332<DD>This brings up a menu that selects
333<UL><LI>Erase time:
334how long in seconds that <I>hkl</I> values are shown
335before they are erased (0 means that they are not erased),
336<LI>Label size: the size of the
337labels in pixels,
338<LI>Search Region: only reflections within this number of pixels of the mouse,
339when the "h" key is pressed (if any) are labeled,
340<LI>Separate window: when this
341option is selected, reflection labels are shown in a text window
342</UL>
343<DT>Subtract background
344<DD>The background is always shown, even when subtracted
345<DT>Include legend
346<DD>The legend is the optional box in the upper left that defines the
347plot entries
348<DT>Set PS output
349<DD>For UNIX this allows the file to be sent directly to a printer
350or can be saved in a file. For Windows, a file must be written.
351<DT>Set screen font
352<DD>This option is used to control the font used for menus, graphics and
353other aspects of windows.
354<DT>Raise on update
355<DD>This causes the plot to be placed on top of other windows, if partially
356obscured, when the plot is updated. At this time, this option does not
357work in Windows-NT and -2000.
358<DT>Cumulative Chi2
359<DD>The causes the Cumulative chi<sup>2</sup> function to be displayed
360(as <a href="#Cchi2">presented above</a>).
361<DT>Save Options
362<DD>Causes many of the options set in this menu to be saved in the <TT>.gsas_config</TT> file.
363</DL></DL>
364<br clear=all>
365
366<P>
367<hr><H2>Customization of LIVEPLOT & BKGEDIT</H2><A NAME="customize"></A>
368The <TT>localconfig</TT> and <TT>.gsas_config</TT> files are read, if present.
369The following variables control how LIVEPLOT, and in most cases BKGEDIT,
370function and can be
371customized by changing their values in the
372<TT>localconfig</TT> and <TT>.gsas_config</TT> files.
373Note that some of these options are relevant only if the tcldump program is
374present.
375<DL><DL>
376<DT><TT>peakinfo(flag<i>n</i>)</TT><DD>
377These variables define if peak positions will be shown
378for reflections in phase "<i>n</i>". Reflections will be shown if
379the value is non-zero.
380
381<DT><TT>peakinfo(color<i>n</i>)</TT><DD>
382These variables define the default colors for
383reflections in phase "<i>n</i>"
384
385<DT><TT>peakinfo(dashes<i>n</i>)</TT><DD>
386These variables define if peaks will be dashed for
387reflections in phase "<i>n</i>" (UNIX only). Lines will be dashed if
388the value is non-zero.
389
390<DT><TT>peakinfo(min<i>n</i>) and peakinfo(max<i>n</i>)</TT><DD>
391These variables dictate the placement vertical position for reflection
392markers, when manually placed (see expgui(autotick), below). To draw
393to the edge of the screen, use -Inf and Inf.
394</DL></DL>
395
396The following variables are written to <tt>.gsas_config</tt> when
397"Save Options" is used. These variables are all set from the GUI and therefore
398do not need to be edited manually.
399
400<DL><DL>
401<DT><TT>graph(printout)</TT><DD>
402This is set to 1 if PostScript files
403will be printed and 0 if they will be written to disk (for Windows all
404files should be written to disk).
405
406<DT><TT>graph(outname)</TT><DD>
407This is the default for the file name used
408when PostScript files will be written to disk.
409
410<DT><TT>graph(outcmd)</TT><DD>
411This is the default for the command used
412to print PostScript files (Unix only).
413
414<DT><TT>graph(legend)</TT><DD>
415Sets the default value for display of the legend in LIVEPLOT and WIDPLT.
416
417<DT><TT>graph(autoraise)</TT><DD>
418This option shows up in the options menu item as "Raise on update."
419When set to non-zero, the LIVEPLOT window is raised
420(placed on top of any other overlapping) windows
421each time it is updated.
422This option does not seem to work in Windows-NT, but this may depend on
423the version of Tcl/Tk.
424
425<DT><TT>peakinfo(obssym)</TT><DD>
426Symbol for observed data points. Valid choices are square, circle, diamond,
427plus, cross, splus and scross.
428
429<DT><TT>peakinfo(obssize)</TT><DD>
430Size for the symbol for observed data points. A value of 1 corresponds to about 1/8 inch
431(about 3 mm).
432
433<DT><TT>expgui(pixelregion)</TT><DD>
434When hkl values are loaded (using tcldump) and reflections are labeled, reflections
435can be labeled using a Shift-Left-Mouse click. All labeled reflections within expgui(pixelregion)
436pixels of the mouse position are assumed to be overlapped and are labeled.
437
438<DT><TT>expgui(fadetime)</TT><DD>
439The time in seconds before reflection labels are removed. A value of zero means that reflections
440must be deleted manually (Shift-Right-Mouse).
441
442<DT><TT>expgui(lblfontsize)</TT><DD>
443A size for reflections labels in pixels.
444
445<DT><TT>expgui(hklbox)</TT><DD>
446If this variable is non-zero, reflection indices are shown in a box.
447
448<DT><TT>expgui(autotick)</TT><DD>
449If this variable is non-zero, reflection markers positions are
450set automatically.
451</DL></DL>
452<P>
453<hr><H2>Installation details/External Programs</H2>
454<B>Using TCLDUMP with LIVEPLOT.</B>
455LIVEPLOT works with the standard GSAS program HSTDMP, but it works faster and is more
456powerful when used with the TCLDUMP program.
457Note that as of the April 2000 releases, GSAS is now distributed with TCLDUMP
458included. For older versions of GSAS, note the
459instructions for downloading this file can in the installation notes for
460<A HREF="expgui_Win_readme.html">
461Windows</A> and
462<A HREF="expgui_Unix_readme.html">
463UNIX</A>.
464<P>
465
466<B>Combining CMPR and LIVEPLOT.</B>
467If you have <A HREF="http://www.ncnr.nist.gov/programs/crystallography/software/cmpr.html">CMPR</A>
468installed on your computer, you can use superimpose on the GSAS results
469the peaks for an arbitrary unit cell. If desired, space group extinctions
470can even be shown.
471This is pretty neat! To enable this feature, you must have a version
472of CMPR downloaded after 4 May 1998
473<A HREF="http://www.ncnr.nist.gov/programs/crystallography/software/cmpr.html">
474(see the CMPR installation instructions.)</A>
475<UL><LI>
476For UNIX, create a link from in the EXPGUI
477directory to file cellgen.tcl in the CMPR directory. For example:
478<PRE>
479   ln -s /usr/local/cmpr/cellgen.tcl /usr/local/gsas/expgui/cellgen.tcl
480</PRE>
481<LI>For Windows, copy all the .tcl and .exe files from the CMPR directory
482into the EXPGUI directory.
483</UL>
484<P>
485
486<B>Combining LOGIC and LIVEPLOT.</B>
487If you have <A HREF="http://www.ncnr.nist.gov/programs/crystallography/software/logic.html">LOGIC</A>
488installed on your computer, you can superimpose peaks
489for a entry from the ICDD/JCPDS database on a pattern in LIVEPLOT.
490This is also pretty neat!
491To enable this feature, you must have
492a version of LOGIC downloaded after 4 May 1998
493<A HREF="http://www.ncnr.nist.gov/programs/crystallography/software/logic.html">
494(see the LOGIC installation instructions.)</A>
495<UL><LI>
496For UNIX, create a link from in the GSAS GUI
497directory to file icddcmd.tcl in the LOGIC directory. For example:
498<PRE>
499   ln -s /usr/local/powdersuite/icddcmd.tcl /usr/local/gsas/expgui/icddcmd.tcl
500</PRE>
501<LI>For Windows, copy all the LOGIC files into the EXPGUI directory.
502</UL>
503<hr>
504<TABLE BORDER BGCOLOR="#FFFF40" ALIGN=RIGHT>
505<TR><TH><A  Href="expgui.html">EXPGUI top</A> 
506</TH><TH><A Href="excledt.html">Next page (EXCLEDT)</A>
507</TH><TH><A Href="expguic.html">Previous page</A>
508</TH></TR></TABLE><BR CLEAR=ALL>
509
510<a href="http://www.ncnr.nist.gov/staff/toby/">Brian Toby</a> (<a href="mailto:brian.toby@nist.gov">Brian.Toby@NIST.GOV</a>)
511<br>
512$Revision: 464 $ $Date: 2009-12-04 23:06:36 +0000 (Fri, 04 Dec 2009) $
513</body>
514</html>
Note: See TracBrowser for help on using the repository browser.