BT7 PSD Data Reduction

The BT7 PSD Data Reduction program is part of the Data Analysis and Visualization Environment (DAVE) application suite. Since neutron scattering instruments are usually unique in some way, it is typical to have a custom reduction program to handle the data generated from each instrument supported in DAVE. In a reduction module a user is able to load the instrument raw file, perform all necessary instrument-specific corrections and then produce an output which can be analyze further in a general way without much reference to how the data was initially collected.

The main difference between this module and the previous BT7 Reduction module is the fact this one is designed to handle the multi-channel detector analyzer package. The previous module reduces data generated using the old single detector. The new program includes the following major capabilities:

The end result is intensity as a function of wavevector transfer and/or energy transfer and/or other environment variables such as temperature depending on the sample and nature of the scan. The program requires detector channel efficiencies, angle and energy calibrations previously determined from measured calibration files.

The Main Application Window

The BT7 PSD Reduction program is a typical GUI application which consists of the following main components.

BT7PSD main window

Figure 1: BT7 PSD Data Reduction


Menus

Menus can be accessed from a menu bar. The File menu provides printing, session and preferences management menu items. Data loading into the application is accomplished through the Data Input menu while exporting or saving data menu items are located underneath Data Output menu. The Insert menu contains menu items that can be used to insert a colorbar and legend to visualizations while this User Manual is available from the Help menu. Frequently used actions or tasks can be launched from the available toolbar.

Data Browser

When raw BT7 instrument data are read into the application, they are represented as entries in the tree widgets located in the top left section the main window interface - this is the Data Browser. The way the data are initially processed depends on whether the measured sample was a single crystal or powder - this is the sample type property which will be addressed further later on.

Plot Window

The application is dominated by a Plot or Graphics window in which data visualization is presented. Plots are generated whenever a dataset is selected from the Data Browser section. The plots are fully customizable and annotations such as text can even be added.

Preferences

There are several options available to customize the application's behavior ranging from the Sample Type to what corrections are to be applied. These options are grouped together into a single property sheet located just below the Data Browser. The Preferences section enables the user to make changes while easily keeping track of the current settings.

Status Bar

The Status Bar section provides feedback to the user. It is split into a left and a right text box. The feedback provided in the left text box may be instruction or basic status information. The right text box provides the x and y coordinates of the mouse location in the plot or graphics window. The coordinates are either in data or pixel units depending on whether the mouse is directly above a plot or not.

Loading and Viewing Datasets

Using this program is quite straightforward. Essentially, data from an instrument raw file is loaded. Various instrument dependent corrections are applied some of which are based on user-specified preferences. A plot of the reduced intensity can be viewed as a function of various selectable independent variables and finally it can be exported into other DAVE program modules for further analysis.

The program is designed to use sensible defaults so it is relatively easy to get started. However, there are a minimum of two settings that must be specified by the user. First, the type of sample that was measured must be explicitly specified by the user as there is no way of determining this from the contents of the raw data file. Please see the discussion on Sample Type below. Second, a calibration parameter file must also be specified in order to properly treat the intensities measured by the position sensitive detector (PSD). Please see the discussion on PSD Calib Parameter File below. This module can only read raw BT7 files (*.bt7). The raw files can be located either on your local computer or on the network at the NCNR ftp server. Depending on the location select one of the following menu items to load your raw data file:

Data Input -> Load Sample Data -- to load files from your local computer

Data Input -> Load Sample Data (NCNR ftp server) -- to load files directly from the public NCNR ftp server

Loaded datasets appear as nodes in the tree view of the Data Browser. To display a dataset in the graphics window, select it from the Data Browser tree. A visualization will be created that reflects the currently selected user preferences such as the corrections applied and which independent variable(s) to display. To display multiple datasets, simply select them from the Data Browser tree by holding down the CTRL key while selecting or deselecting additional datasets (use the SHIFT key to select a range of datasets).

The screenshot below shows a plot of all the 5 datasets loaded in the Data Browser. These are single crystal data as seen in the Preferences section as well as the following settings: the horizontal and vertical axes are respectively set to QX and QY; the lattice parameters were taken from the data; no detector channels were masked; the maximum and minimum intensities for the plot are set to 200 and 20 respectively; etc.

BT7PSD New Plot

Figure 2: Visualize dataset by clicking on entries in the Data Browser tree widget. The plot shows data from all 5 selected datasets and reflects the settings shown in the Preferences. The slightly darker strips or bands shows where datasets overlap.



User Preferences

You can modify or alter the behavior of the application by customizing the preferences from the propertysheet section of the main window. The propertysheet widget contains several rows of user customizable properties each consisting of two columns - a label and a field. The label specifies the name of the property and field its value. In most cases the value is specified by selecting from a predefined set while in some cases it is simply an editable text field. For text fields, after modification, use the ENTER or RTRN key to accept the change! A brief description of each available property is now given together with a guide on how it can be modified.
Note
Changes to your preferences are saved automatically when you exit a session and restored when you start a new session! In addition, you can explicitly save the current preferences using the File->Save Preferences menu or restore the default preferences using the File->Reset Preferences (Default Values) menu. When a saved session is loaded, the preferences that were stored with that session will become current.


Sample Type
This is a droplist field that has the following options available for the user to select from: This option enables you to specify the nature of the measured sample. It is necessary to make this selection before loading your data because the data processing is very dependent on the sample type and results in very different reduced data. Unfortunately, there is no way of automatically determining the sample type from the file contents and because it is possible to treat the same dataset either as a Single Crystal or Powder, the user has the responsibility to correctly specify the sample type. If the sample type is incorrectly specified then then the reduced data will be rubbish! When a dataset is loaded, it is tagged with the current setting of the Sample Type property. Subsequently, if the active Sample Type property does not match a loaded dataset's sample type, that dataset will be ignored! It is a safety measure that prevents the accidental merging of distinct reduced data.
Note
If a loaded dataset's sample type does not match the value of Sample Type property, it will be ignored from further consideration. It cannot be plotted or exported to other DAVE modules!
If an attempt is made to change the Sample Type property while data is already loaded, the following dialog will be displayed:

BT7PSD Delete Data dialog

Figure 3: You may wish to have datasets with different sample types!

If you select 'Yes', all loaded datasets will be deleted. If you select 'No' then the new Sample Type property may not match the existing dataset(s). As noted earlier, in cases where a loaded dataset's sample type does not match the Sample Type field, it will be ignored!

PSD Calib Parameter file
This is a read-only text field that enables the user to see the current setting for the PSD Calibration Parameter file. Choosing or specifying the file can be done by one of two ways. Either use the

Data Input->Load PSD Calibration Parameters file

menu or simply click on the field and then select the small arrow button that appears on the extreme right edge of the field as highlighted in Figure 4. In either case, a file dialog will launch for you to browse and select the calibration file.

BT7PSD Calibration file field

Figure 4: Click on the small arrow button to launch the calibration file selection dialog. You can also use the Data Input->Load PSD Calibration Parameters file menu.

BT7 utilizes a position sensitive detector (PSD) that is actually a composite detector consisting of 48 independent channels. The raw dataset contains the counts from these 48 channels but in order to interpret these in a meaningful way, the efficiencies, relative scattering angles and relative energy transfers for each detector channel must be known. This information is usually contained in a calibration parameter file provided by the instrument scientist. Note that the calibration parameters changes dependent on the exact instrument setup so always ensure you use the calibration file that is appropriate for your experiment. If in doubt, contact the BT7 instrument scientist.

Apply Channel Eff Corr?
This is a droplist field that has the following options available for the user to select from: As indicated above for the PSD Calib Parameter file property, the relative efficiencies of each detector channel is obtained from the calibration file. To properly normalize the detector counts, the counts in each channel must be divided by its efficiency. This would be the case if you set this property to Yes. However, on occasion, you may want to view the raw counts in each channel without any efficiency normalization. Simply set this property to No to achieve this. Note that this property will be desensitized (grayed out) if you have not loaded a calibration parameter file!

Scan Variable
This property only applies to powder samples

This is a droplist field that has the following options available for the user to select from:

The choices are respectively scattering angle (A4), d-space, magnitude of momentum transfer, energy transfer, sample temperature, magnetic field and index of data point index of scan.

These represent the available choices for the scan or independent variable that can be selected to display the data in the case of powder samples. The dependent variable is always Counts. Note that if a selection such as TEMP is made that turns out to be constant (i.e. not varying), the program will respond by automatically defaulting to the Data_Index as the Scan Variable!

Horizontal Axis Variable
This property only applies to single crystal samples

This is a droplist field that has the following options available for the user to select from:

The choices are respectively component of momentum transfer along x, component of momentum transfer along y, energy transfer, magnitude of momentum transfer, sample temperature, magnetic field and PSD Channel number. Please see the scattering diagram in Figure 5 showing how Q, QX and QY are defined.

BT7PSD Calibration file field

Figure 5: The scattering diagram showing how momentum transfer and its components are defined in the program.

These represent the available choices for the horizontal independent variable in the case of single crystal samples. For single crystals, the processed data is a multi-dimensional dataset with Counts as a function of two or more independent variables. Therefore, to view the data, it is necessary to select at least two independent variables so that an area plot can be produced. This property allows the user to specify the horizontal or x-axis variable. The dependent variable is set to Counts. Note that if a selection such as TEMP is made that turns out to be constant (i.e. not varying), the program will respond by automatically defaulting the horizontal axis to PSD Channel number!

Vertical Axis Variable
This property only applies to single crystal samples

This property is used to specify the vertical or y-axis variable. See Horizontal Axis Variable description for details.

Units of QX, QY
This property only applies to single crystal samples

This is a droplist field that has the following options available for the user to select from:

This property is used to specify the units of the QX and QY variables.

Min Bin Width (scan var)
This property only applies to powder samples

This is a text field that enables the user to specify the minimum bin width to be applied to the independent axis variable that has been selected using the Scan Variable property. The minimum bin width essentially defines the minimum resolution for the selected independent variable. Hence the value you specify should depend on what the Scan Variable is. Note that the data is not rebinned into a constant bin width! As a guide, the default minimum bin widths are shown in the following table

Default Minimum Bin Width    Scan Variable
0.152Theta
0.01d-space
0.01|Q|
0.50E
0.50TEMP
0.10MAGFIELD
1.00Data_Index

You are certainly free to explore other settings for the minimum bin width but be aware that you may start noticing strange effects if your values deviate too much from the actual resolution of that variable for your measurement! In general, the settings for 2Theta, d-space and |Q| are pretty much determined by the detector geometry and hence you may not need to deviate too much from the defaults. However, values for E, TEMP and MAGFIELD really depend on the details of each measurement!

Use Default Intensity Range?
This property only applies to single crystal samples

This is a droplist field that has the following options available for the user to select from:

If this property is set to No then the intensity range of the visualization will be determined from the data. If it is set to Yes then the user has the option of specifying a custom intensity range using the Min Intensity Value and Max Intensity Value properties.

Min Intensity Value
This property only applies to single crystal samples

This property will appear only if the Use Default Intensity Range? property is set to Yes. It is a text field that enables the user to specify the minimum intensity value of the current plot. Note that this property only affects the visualization and not the underlying data.

Max Intensity Value
This property only applies to single crystal samples

This property will appear only if the Use Default Intensity Range? property is set to Yes. It is a text field that enables the user to specify the maximum intensity value of the current plot. Note that this property only affects the visualization and not the underlying data.

Latt Param Source
This property only applies to single crystal samples

This is a droplist field that has the following options available for the user to select from:

The lattice parameters for the sample are stored in the experiment raw file. If this property is set to From Data then the lattice parameters used in the data processing are retrieved from the raw data file. However, if you wish to ignore or modify the values read from the file then set this property to User Specified and then use the Latt Param: a b c al be ga property to define custom values for the lattice parameters.

Latt Param: a b c al be ga
This property only applies to single crystal samples

This property will be editable only if the Latt Param Source property is set to User Specified. It is a text field that enables the user to specify the lattice parameters for the sample. All six values making up the lattice parameters must be specified in the order indicated in the label . Use space to separate entries. By default, if any dataset has been loaded the values read from the file will be automatically filled in for you in this field.

A3 Correction (Phi Offset)
This property only applies to single crystal samples

This property is a text field that enables the user to specify a correction to the angle A3 relative to what is recorded in the data file. Such a correction may be necessary if, for example, it is later realized that the sample was misalignment during the measurement.

Remove Masked Channels?
This is a droplist field that has the following options available for the user to select from: If this property is set to No then all the detector channels in the PSD will be used. If it is set to Yes then the user has the option of specifying which detector channels are to be masked using the Channels to be Masked property. Masked channels are essentially ignored in the data processing.

Channels to Mask
This is a text field that displays the detector channels that have been selected for masking. Masked detector channels are essentially ignored in the data processing. However, you cannot modify the mask list directly! To select or specify channel(s) to mask, simply click on the field and then select the small arrow button that appears on the extreme right edge of the field. The dialog shown in Figure 6 will be displayed.

BT7PSD Detector channel masking tool

Figure 6: The detector channel masking tool. The plot shows the integrated intensity in each detector channel. The grayed out channels are to be masked and the list includes channels 4, 5, 6, 16, 44, 45, 46!

The tool displays a plot of the integrated intensity in each detector channel giving the user a basic indication of whether there is anything unusual. The plotted data is the first selected dataset from the Data Browser - if no dataset is selected then the first one is used. If no datasets are loaded than the tool will not launch! In the figure, some channels are grayed while others are not. The grayed out channels are to be masked and are also listed in the text field at the top of the dialog. Use the left mouse click on the plot window to toggle the state of any channel from mask to unmask or vise versa. You can also select a range by clicking and dragging with the left mouse to select a range of channels. When satisfied with the mask list, you can exit the tool by clicking on the Accept Changes button to accept and use the list or the Discard Changes button to ignore all the changes. If you accept the changes, the mask list you just created will become the new value of the Channels to be Masked field and will be masked out if the Removed Masked Channels property is set to "Yes".

Normalize To
This is a droplist field that has the following options available for the user to select from: When making relative comparison between different datasets, it may be necessary to normalize the detector counts to the monitor flux or to the counting time. Using this property, the user can specify which option to use for normalization. If the "No Normalization" option is selected, then the raw detector counts are used.

Overall Scale Factor
This is a text field that can be used to specify a multiplicative overall scale factor that should be applied to the processed data. This is sometime useful to arbitrary rescale the data after, for example, a monitor normalization which results in really small numbers for the processed counts. If you attempt to set this property to 0.0 it will default to 1.0!

Fast Bkgd Corr.?
This is a droplist field that has the following options available for the user to select from: This property determines whether or not to apply a fast neutron background correction. If set to No then no correction is applied. If it is set to Yes then the fast background in addition to other corrections can be applied. These are:

Fast Bkgd (cts/min)
This property is active only when Fast Bkgd Corr.? is set to "Yes".

This is a text field that can be used to specify a value for the fast background correction in counts per minute. If you are not sure or if you are simply interested in applying another correction (eg monitor correction), then set the fast background value to zero!

Monitor Correction?
This property is active only when Fast Bkgd Corr.? is set to "Yes".

This is a droplist field that has the following options available for the user to select from:

Obviously, when set to "Yes", the monitor correction will be applied to the data.

Monitor correction is an energy dependent scale factor that accounts for higher-order harmonics in the beam. This correction is only applied in constant-Q scans when the incident energy (Ei) varies and the graphite (PG) monochromator is in use. The correction (MC) has been measured for BT7 and modeled so it is defined as follows:

corrected counts = (raw counts - fast background) * MC

where

MC = 6.123 - 0.5963 * Ei + 2.6244x10^(-2) * Ei^2 - 4.843x10^(-4) * Ei^3 + 2.881*10^(-6) * Ei^4

The above definition only works for Ei between 5 meV and 34 meV. For Ei above 34 meV, MC is 1 and for Ei less than 5 meV, the program will raise a warning flag and no correction will be applied!

Resolution Correction?
This property is active only when Fast Bkgd Corr.? is set to "Yes".

This is a droplist field that has the following options available for the user to select from:

Obviously, when set to "Yes", the resolution volume correction will be applied to the data.

This correction accounts for the change in phase space volume that results when the final neutron energy (Ef) is varying. It is implemented using the following formula

corrected counts = (raw counts - fast background) * RC

where

RC = norm / [cot(A6/2.0) * Ef^(3/2)]

and

norm = Ei^(3/2) * cot[arcsin[pi / 0.69472 * d * sqrt(Ei)]]

and

d = analyzer d spacing.

The correction is designed to be unity at the elastic position (Ei=Ef).

Det. Balance Correction?
This property is active only when Fast Bkgd Corr.? is set to "Yes".

This is a droplist field that has the following options available for the user to select from:

Obviously, when set to "Yes", the detailed balance correction will be applied to the data.

Detailed balance is defined as the factor exp(-B*E/2) where B = 1/(k*T) and k is the Boltzmann constant so that the result satisfies the principle of detailed balance: S(Q,-E) = S(Q,E)exp(-B*E).

Allow multiple Mslice?
This property only applies to single crystal samples

This is a droplist field that has the following options available for the user to select from:

The Mslice module in DAVE is used to perform more sophisticated analysis of a multi-dimensional dataset. At any time during the reduction process, you can export your data to Mslice. When you do this, you can decide to either instantiate a new Mslice module with each export or to update the data in the existing Mslice instance. So essentially, if this property is set to "No" then exporting your data will only instantiate a new Mslice window if none is running. If the property is set to "Yes" then a new Mslice instance will be created following each data export to Mslice.

Saving and Exporting Datasets

Processed data can be saved to disk or exported to other application modules within DAVE from the Data Output top level menu. The following actions can be performed:

Export Selection to Mslice (Single Crystal Samples)
This export action can only be performed if the processed data was treated as a single crystal.

This action is available underneath the Data Output menu. It is used to export the selected dataset(s) to the Mslice module for further analysis. Mslice is an invaluable tool for analyzing and visualizing multi-dimensional data and hence comes very handy since since single crystal data from BT7 are typically multi-dimensional.

If this menu is selected but there are only powder datasets present, nothing will happen! Also, if the menu is selected but there are no datasets selected from the tree browser section, then nothing will happen. If one or more datasets are selected, then a dialog will appear as shown in Figure 7 for the user to specify which independent variables to export in addition to the intensity and error.

BT7PSD export variables dialog

Figure 7: When exporting reduced data to Mslice you need to select the independent variables to be exported along with the dependent variables (intensity and uncertainty in intensity).

Note that because Mslice requires at least a 2-dimensional dataset, you have to select a minimum of 2 independent variables for export. If all goes successfully, the exported data will appear in a new or existing Mslice session as shown in Figure 8. Please see the Mslice use manual which is available from the Help menu in Mslice for help as to how to proceed.

BT7PSD Mslice window

Figure 8: Main Mslice window with data from BT7 PSD Reduction already loaded and ready to by analyzed and/or visualized.



Export Selection to Data Manager (Powder Samples)
This export action can only be performed if the processed data was treated as a powder.

This action is available underneath the Data Output menu. It is used to export the selected dataset(s) to the DAVE Data Manager for further analysis and visualization.

Save Selection to DAVE file (Powder Samples)
This export action can only be performed if the processed data was treated as a powder.

This action is available underneath the Data Output menu. It is used to save the selected dataset(s) to a file on disk using the DAVE (.dave) data format. Many program modules within DAVE are able to read .dave format files. The independent variable recorded is whatever was selected as the Scan Variable at the time of the save action.

Save Selection to ASCII file (Powder Samples)
This export action can only be performed if the processed data was treated as a powder.

This action is available underneath the Data Output menu. It is used to save the selected dataset(s) to a file on disk in 3 column ASCII format. The first column is the independent variable which would be whatever was selected as the Scan Variable at the time of the save action. The other two columns are the counts and the uncertainty in the counts.

Fit Selection in PAN (Powder Samples)
This export action can only be performed if the processed data was treated as a powder.

This action is available underneath the Data Output menu. It is used to export powder data to PAN for fitting. It only works if the selected data to be exported is for a powder sample. The independent variable that is exported to PAN is whatever was selected as the Scan Variable at the time of the export action. Figure 9 shows an example of a fitting session in PAN. For assistance, see the PAN user manual available from the Help menu in PAN.

BT7PSD PAN

Figure 9: Exported data fitted in PAN



Printing and Exporting Graphics

After generating and customizing a plot, you may decide to print it or export it to a variety of standard image formats. Almost all standard image formats such as GIF, PNG, JPEG, EPS, etc are supported. The following three menus
  1. File->Export Graphics...
  2. Print Preview...
  3. Print...
which are pretty much self explanatory, can be used to accomplish these tasks.

Session Management

One really nice feature of this program module is the ability to save and restore your sessions. A saved session preserves all the loaded data, calibration file and preference settings. When you open the saved session subsequently, you will essentially be restoring the session in its entirety, just as you left it before. Use the
File->Save Current Session
menu to save your session and the
File->Open Session
menu to open a previously saved session. This functionality gives you the ability to reduce and visualize related datasets together and then saving the result in a session or project. You can of course create as many projects as you wish based on whatever criteria you choose. Since project or sessions are completely self-contained, they can be shared with others without the need to send the raw data files, calibration file and the necessary user preferences to go with the dataset.
Note
Be aware that a session is completely self-contained and includes both data and application state (preferences) so when a new session is loaded, your existing session (data and preferences) will be replaced. However, you will be given the option to save the existing session if it has been modified!