Difference between revisions of "CMPR"

From Ug11bm
Jump to navigationJump to search
 
(40 intermediate revisions by the same user not shown)
Line 3: Line 3:
CMPR is a free multipurpose program for powder diffraction data.   
CMPR is a free multipurpose program for powder diffraction data.   


11-BM staff routinely use it to examine & compare ('''''C'''o'''MP'''a'''R'''e'') powder XRD data at the beamline. It is a great too for manipulating and converting multiple datasets, and can also be used to fit or index diffraction peaks.
11-BM staff routinely use it to examine & compare ('''''C'''o'''MP'''a'''R'''e'') powder XRD data at the beamline. It is a handy tool for manipulating and converting multiple datasets, and can also be used to fit and index diffraction peaks.


The program works well with 11-BM's [http://11bm.xor.aps.anl.gov/filetypes.html .fxye GSAS format], but can be used with nearly any powder XRD data.
The program works well with 11-BM's [http://11bm.xray.aps.anl.gov/filetypes.html .fxye GSAS format], but can be used with nearly any powder XRD data.


See the [https://subversion.xor.aps.anl.gov/trac/CMPR/wiki CMPR subversion page] for download links, installation notes, and full documentation.  (
See the [https://subversion.xray.aps.anl.gov/trac/CMPR/wiki CMPR subversion page] for download links, installation notes, and full documentation.  (
https://subversion.xor.aps.anl.gov/trac/CMPR/wiki)
https://subversion.xray.aps.anl.gov/trac/CMPR/wiki)


Some of CMPR's basic features are described below.


== Getting Started ==  
== Getting Started ==  
=== CMPR Windows ===


CMPR launches 2 windows: the main GUI '''Control''' window and the '''Plotting''' window.   
CMPR launches 2 windows: the main GUI '''Control''' window and the '''Plot''' window.   


[[image:cmprintro.png|500px|CMPR Windows]]
[[image:cmprintro.png|500px|CMPR Windows]]


Functions on the Control window are organized into multiple menu tabs.  For example, the ''Read'' new file tab is highlighted below. You may need to expand the GUI window to see all tabs at once.


[[image:cmprtabs.png|500px|CMPR tabs]]


=== 1 ===
Left-click with a mouse in the '''Plot''' window to define a zoom window, right-click to un-zoom.  The key "L" shows/hides a cursor mode to read values from the plot window. 
=== 2 ===


[[image:cmprplotzoom.png|250px|CMPR plot zoom]]


=== Opening files ===
On the ''Read'' tab, first select the file format to be read (1).  More formats can be found by scrolling down (red arrow).  Navigate to the desired folder or directory (2).  Select (hightlight) the file or files to be read (3).  Click the READ button (4) to open the file(s).


[[image:cmprread.png|500px|CMPR OpeningFiles]]


== More ==  
Successfully opened files will be listed in the "Datasets Read" panel (1) and will appear in the '''Plot''' window (2).
=== 3 ===
 
[[image:cmpropned.png|500px|CMPR tabs]]
 
=== Closing files ===
 
To remove files from the list of read datasets, use ''Control-right-click'' (PC) or ''control+Command+mouse'' (Mac) to remove selected files from the active CMPR window (don't worry - this does *not* deleted from disk).
 
=== Plotting Data ===
By default, the '''Plot''' window will display the most recently opened file(s).  On the ''Plot'' tab of the '''Control''' window (1), modify which files are plotted.    Highlight the desired file(s) (2), then click "Update Plot" (3).
 
One can also change the color or size of the data lines and markers (4).  Select the desired files, then click "Set Sequence" or "Apply all Changes".
 
It is also possible to export the current Plot window contents to a pdf or postscipt image; or to Grace or .csv data outputs (5).
 
[[image:cmprplottab.png|500px|CMPR plot window]]
 
== Data Manipulation ==
=== File Titles, Labels, and Wavelength ===
On the ''EditFile'' tab of the '''Control''' window, view and modify the titles, labels, and wavelength(s) for a selected dataset (1).
 
When opening certain data formats (like the 11-BM .fxye format), fields such as the wavelength (2) will be automatically read from the file header.  For other formats, this information needs to be manually entered.
 
[[image:cmprEditFiletab.png|500px|CMPR EditFile tab]]
 
=== Rescaling & Data Conversion ===
On the ''Rescale'' tab of the '''Control''' window one can change the X and/or Y scale units for selected file(s).
 
In addition to the "as collected" units, the X-axis for a dataset can be re-plotted in units of d-spacing, [http://11bm.xray.aps.anl.gov/faq.html#Q11 Q], or 2theta at different wavelength.  Select the target file(s) (1), desired X-Units (2), then click "Rescale" (3).  This conversion requires a wavelength in the 'EditFile' tab (see above), if no wavelength is found CMPR will prompt the user to enter a wavelength value.
 
The Y-axis units or scaling can similarly be modified.  Use "X-stagger %" and "Y-stagger %" to quickly create waterfall-style stacked plots for multiple datasets. (4)
 
Multiple files can easily be intensity normalized (to I = 1000).
 
Note that rescalings are applied consecutively (so scaling x5, then x2 is equal to a single x10 rescale). To remove all applied user rescalings, tick the "reset" box (5), set all multipliers to 1 and offsets to 0, then click "Rescale".  This returns all data to the original values.
 
[[image:cmprReScaletab.png|500px|CMPR ReScale tab]]
 
=== Combining Data ===
On the ''Combine'' tab of the '''Control''' window, one can combine multiple datasets.  One can add (times +1) or subtract (times -1) files. Note that files must have the same number of data points and scan range.
 
This is used at 11-BM to combine several identical scans into a single dataset with better counting statistics.
 
== Saving Files ==
 
=== Write Data Tab ===
Convert original files to a new format, or save modified datasets on the ''Write'' tab of the '''Control''' window.
 
Select the file(s) to be saved (1) and target directory location for the saves file(s) (2).  Next select the file format. (3) Scroll down to see all available formats.  Then click "Write Selected Datasets" to write the files. (4) Note that is straightforward to add a new read or write format if desired (see full CMPR documentation for help here).
 
[[image:cmprwritefiles.png|500px|CMPR Write]]
 
== Advanced Topics ==
 
See the [https://subversion.xray.aps.anl.gov/CMPR/trunk/doc/cmprdoc.html CMPR documentation] for more information. (https://subversion.xray.aps.anl.gov/CMPR/trunk/doc/cmpr.html)
 
== Defining Custom Data Read Formats ==
 
On Apr 4, 2013, Brian Toby <[email protected]> wrote:
 
Dear CMPR Users
 
I've recently be asked the following question:: " In CMPR is there any way of importing a 4 column file and plotting columns 3 and 4 (I think CMPR can open it, but the default is to plot columns 1 and 2)?"
 
This is easy to do yourself.
 
Locate the read_xypair.tcl file and make a copy of it. The name must start with "read_" and end with ".tcl", say "read_34.tcl". On windows you can do this editing with wordpad or textpad, but be careful about extensions. They love to change the file extension to .txt and that will not be found by CMPR.
 
The first thing that needs to be done is to change some names In that new file to not conflict with the read_xypair.tcl routines. Do this by changing the string "readXYd" to something different, say "readXY34d" with a global search and replace. If case is ignored, there are 14 places where this gets changed.
 
Also that new file, change the line near the top to be slightly different, such as:
 
# menu label
lappend command(readtypes) "XY data (cols 3&4)"
 
Then near the end of the file you will find these lines:
 
set yyyy -1
catch {
    set xxxx [expr [lindex $line 0]]
    set yyyy [expr [lindex $line 1]]
}
set yyyyesd -1
catch {
    set yyyyesd [expr [lindex $line 2]]
}
The 0 means use the first column, 1 the second. Change them to
 
    set xxxx [expr [lindex $line 2]]
    set yyyy [expr [lindex $line 3]]
 
I am assuming that your file does not have a column of esd's for the intensities (it is expected as column 3, if present), so comment out the line that reads the esd
 
    #set yyyyesd [expr [lindex $line 2]]
 
or you could change it to read column 5 (if present) by changing the 2 to 4.
 
If you restart CMPR, your new format should show up in the list of formats. You can control where if you read the configuration documentation.
 
There is a CMPR main folder - and a "development" version folder - might make sure your new .tcl file is in both places so it shows up on both running versions of CMPR!
 
Hope this helps.
 
Brian
 
== CMPR Citation ==
 
If you use CMPR in a project, please cite:
 
Toby, B. H. (2005). "CMPR - a powder diffraction toolkit," Journal of Applied Crystallography 38, 1040-1041.
xray

Latest revision as of 15:39, 5 April 2014

About CMPR

CMPR is a free multipurpose program for powder diffraction data.

11-BM staff routinely use it to examine & compare (CoMPaRe) powder XRD data at the beamline. It is a handy tool for manipulating and converting multiple datasets, and can also be used to fit and index diffraction peaks.

The program works well with 11-BM's .fxye GSAS format, but can be used with nearly any powder XRD data.

See the CMPR subversion page for download links, installation notes, and full documentation. ( https://subversion.xray.aps.anl.gov/trac/CMPR/wiki)

Some of CMPR's basic features are described below.

Getting Started

CMPR Windows

CMPR launches 2 windows: the main GUI Control window and the Plot window.

CMPR Windows

Functions on the Control window are organized into multiple menu tabs. For example, the Read new file tab is highlighted below. You may need to expand the GUI window to see all tabs at once.

CMPR tabs

Left-click with a mouse in the Plot window to define a zoom window, right-click to un-zoom. The key "L" shows/hides a cursor mode to read values from the plot window.

CMPR plot zoom

Opening files

On the Read tab, first select the file format to be read (1). More formats can be found by scrolling down (red arrow). Navigate to the desired folder or directory (2). Select (hightlight) the file or files to be read (3). Click the READ button (4) to open the file(s).

CMPR OpeningFiles

Successfully opened files will be listed in the "Datasets Read" panel (1) and will appear in the Plot window (2).

CMPR tabs

Closing files

To remove files from the list of read datasets, use Control-right-click (PC) or control+Command+mouse (Mac) to remove selected files from the active CMPR window (don't worry - this does *not* deleted from disk).

Plotting Data

By default, the Plot window will display the most recently opened file(s). On the Plot tab of the Control window (1), modify which files are plotted. Highlight the desired file(s) (2), then click "Update Plot" (3).

One can also change the color or size of the data lines and markers (4). Select the desired files, then click "Set Sequence" or "Apply all Changes".

It is also possible to export the current Plot window contents to a pdf or postscipt image; or to Grace or .csv data outputs (5).

CMPR plot window

Data Manipulation

File Titles, Labels, and Wavelength

On the EditFile tab of the Control window, view and modify the titles, labels, and wavelength(s) for a selected dataset (1).

When opening certain data formats (like the 11-BM .fxye format), fields such as the wavelength (2) will be automatically read from the file header. For other formats, this information needs to be manually entered.

CMPR EditFile tab

Rescaling & Data Conversion

On the Rescale tab of the Control window one can change the X and/or Y scale units for selected file(s).

In addition to the "as collected" units, the X-axis for a dataset can be re-plotted in units of d-spacing, Q, or 2theta at different wavelength. Select the target file(s) (1), desired X-Units (2), then click "Rescale" (3). This conversion requires a wavelength in the 'EditFile' tab (see above), if no wavelength is found CMPR will prompt the user to enter a wavelength value.

The Y-axis units or scaling can similarly be modified. Use "X-stagger %" and "Y-stagger %" to quickly create waterfall-style stacked plots for multiple datasets. (4)

Multiple files can easily be intensity normalized (to I = 1000).

Note that rescalings are applied consecutively (so scaling x5, then x2 is equal to a single x10 rescale). To remove all applied user rescalings, tick the "reset" box (5), set all multipliers to 1 and offsets to 0, then click "Rescale". This returns all data to the original values.

CMPR ReScale tab

Combining Data

On the Combine tab of the Control window, one can combine multiple datasets. One can add (times +1) or subtract (times -1) files. Note that files must have the same number of data points and scan range.

This is used at 11-BM to combine several identical scans into a single dataset with better counting statistics.

Saving Files

Write Data Tab

Convert original files to a new format, or save modified datasets on the Write tab of the Control window.

Select the file(s) to be saved (1) and target directory location for the saves file(s) (2). Next select the file format. (3) Scroll down to see all available formats. Then click "Write Selected Datasets" to write the files. (4) Note that is straightforward to add a new read or write format if desired (see full CMPR documentation for help here).

CMPR Write

Advanced Topics

See the CMPR documentation for more information. (https://subversion.xray.aps.anl.gov/CMPR/trunk/doc/cmpr.html)

Defining Custom Data Read Formats

On Apr 4, 2013, Brian Toby <[email protected]> wrote:

Dear CMPR Users

I've recently be asked the following question:: " In CMPR is there any way of importing a 4 column file and plotting columns 3 and 4 (I think CMPR can open it, but the default is to plot columns 1 and 2)?"

This is easy to do yourself.

Locate the read_xypair.tcl file and make a copy of it. The name must start with "read_" and end with ".tcl", say "read_34.tcl". On windows you can do this editing with wordpad or textpad, but be careful about extensions. They love to change the file extension to .txt and that will not be found by CMPR.

The first thing that needs to be done is to change some names In that new file to not conflict with the read_xypair.tcl routines. Do this by changing the string "readXYd" to something different, say "readXY34d" with a global search and replace. If case is ignored, there are 14 places where this gets changed.

Also that new file, change the line near the top to be slightly different, such as:

# menu label
lappend command(readtypes) "XY data (cols 3&4)"

Then near the end of the file you will find these lines:

		set yyyy -1
		catch {
		    set xxxx [expr [lindex $line 0]]
		    set yyyy [expr [lindex $line 1]]
		}
		set yyyyesd -1
		catch {
		    set yyyyesd [expr [lindex $line 2]]
		}

The 0 means use the first column, 1 the second. Change them to

		    set xxxx [expr [lindex $line 2]]
		    set yyyy [expr [lindex $line 3]]

I am assuming that your file does not have a column of esd's for the intensities (it is expected as column 3, if present), so comment out the line that reads the esd

		    #set yyyyesd [expr [lindex $line 2]]

or you could change it to read column 5 (if present) by changing the 2 to 4.

If you restart CMPR, your new format should show up in the list of formats. You can control where if you read the configuration documentation.

There is a CMPR main folder - and a "development" version folder - might make sure your new .tcl file is in both places so it shows up on both running versions of CMPR!

Hope this helps.

Brian

CMPR Citation

If you use CMPR in a project, please cite:

Toby, B. H. (2005). "CMPR - a powder diffraction toolkit," Journal of Applied Crystallography 38, 1040-1041.

xray