diff --git a/docs/source/interfaces/HFIRPowderReduction.rst b/docs/source/interfaces/HFIRPowderReduction.rst
index 10ed6729b421d248b5d02222ef7fd63a02062516..a46d7f66158f76efc035b05298e001c07dbee97c 100644
--- a/docs/source/interfaces/HFIRPowderReduction.rst
+++ b/docs/source/interfaces/HFIRPowderReduction.rst
@@ -14,41 +14,41 @@ in SPICE format.
Use cases for tabs
------------------
- 1. **Raw Detectors**: Visualize the reading of detectors directly coming out of the raw data
+1. **Raw Detectors**: Visualize the reading of detectors directly coming out of the raw data
- - Plot N lines for N Pts.;
- - Highlight (make it thicker) the Pt that is interested;
- - New from Mantid: *ReadRawSpiceSignal(Pts)*;
+ - Plot N lines for N Pts.;
+ - Highlight (make it thicker) the Pt that is interested;
+ - New from Mantid: *ReadRawSpiceSignal(Pts)*;
- 2. **Individual Detector**: Visual the readings of one detector across an experiment
+2. **Individual Detector**: Visual the readings of one detector across an experiment
- - Plot the counts of any individual detector;
- - Able to change the X-axis from 2theta to arbitrary sample environment log;
- - New from Mantid: *ReadRawSpiceSignal(DetectorID, XLabel)*;
+ - Plot the counts of any individual detector;
+ - Able to change the X-axis from 2theta to arbitrary sample environment log;
+ - New from Mantid: *ReadRawSpiceSignal(DetectorID, XLabel)*;
- 3. **Normalized**: Reduce one scan each time
+3. **Normalized**: Reduce one scan each time
- - Plot the reduced data
- - Automatically locate detector efficiency file
- - New from Mantid: *ConvertCWPDMDToSpectra(ExcludedDetectors=[])*
- - New from Mantid: *ConvertSpiceDataToRealSpace(DetectorEfficiencyTable)*
+ - Plot the reduced data
+ - Automatically locate detector efficiency file
+ - New from Mantid: *ConvertCWPDMDToSpectra(ExcludedDetectors=[])*
+ - New from Mantid: *ConvertSpiceDataToRealSpace(DetectorEfficiencyTable)*
- 4. **Multiple Scans**: Reduce a set of scans
+4. **Multiple Scans**: Reduce a set of scans
- - Reduce a set of scans and plot in 2D/water-fall mode;
- - Able to merge all the scans;
- - New from Mantid: *ConvertCWPDMDToSpectra(ExcludedDetectors=[])*
+ - Reduce a set of scans and plot in 2D/water-fall mode;
+ - Able to merge all the scans;
+ - New from Mantid: *ConvertCWPDMDToSpectra(ExcludedDetectors=[])*
- 5. **Vanadium**: strip vanadium peaks
+5. **Vanadium**: strip vanadium peaks
- - Strip vanadium peak with unit 'Degrees' because of the binning (range and step size) must be respected;
- - Peaks' position should be calculated and indicated auotmatically;
- - *Mantid::StripPeaks()* will be called instread of *StripVadadiumPeaks()* because
- the later one only works in d-spacing;
+ - Strip vanadium peak with unit 'Degrees' because of the binning (range and step size) must be respected;
+ - Peaks' position should be calculated and indicated auotmatically;
+ - *Mantid::StripPeaks()* will be called instread of *StripVadadiumPeaks()* because
+ the later one only works in d-spacing;
- 6. **Advanced Setup**
+6. **Advanced Setup**
- - URL for raw data files;
+ - URL for raw data files;
Workflow for *Normalization*
@@ -56,31 +56,31 @@ Workflow for *Normalization*
Here is a typical use case for reduce data via tab *Noramlization*
- 1. User specifies *Exp No* and *Scan No* and push button *Load*;
+1. User specifies *Exp No* and *Scan No* and push button *Load*;
- - HFIR-PDR-GUI loads SPICE data according to experiment number and scan number;
- - HFIR-PDR-GUI checks whether vanadium correction file, i.e., detector efficiency file exists on server;
- - HFIR-PDR-GUI checks whether excluded detectors file exists on server;
- - HFIR-PDR-GUI checks log **m1** for wavelength and set to *Wavelength* ;
+ - HFIR-PDR-GUI loads SPICE data according to experiment number and scan number;
+ - HFIR-PDR-GUI checks whether vanadium correction file, i.e., detector efficiency file exists on server;
+ - HFIR-PDR-GUI checks whether excluded detectors file exists on server;
+ - HFIR-PDR-GUI checks log **m1** for wavelength and set to *Wavelength* ;
- 2. User may specify detector efficient file;
+2. User may specify detector efficient file;
- 3. User specifies *Bin Size*;
-
- 4. User pushes button *2Theta*, *dSpacng*, or *Q*;
+3. User specifies *Bin Size*;
+
+4. User pushes button *2Theta*, *dSpacng*, or *Q*;
- - HFIR-PDF-GUI reduce data in unit of *2theta* by taking accounting of
+ - HFIR-PDF-GUI reduce data in unit of *2theta* by taking accounting of
- - Detector efficiency;
- - Excluded detectors;
+ - Detector efficiency;
+ - Excluded detectors;
- 5. HFIR-PDR-GUI plots the reduced data;
+5. HFIR-PDR-GUI plots the reduced data;
- 6. User may rebin by different binning parameters or unit;
+6. User may rebin by different binning parameters or unit;
- 7. User may push button *Next Scan* or *Prev Scan* to load and reduce other scans with current setup;
+7. User may push button *Next Scan* or *Prev Scan* to load and reduce other scans with current setup;
- 8. User may save the result by pushing button *Save*;
+8. User may save the result by pushing button *Save*;
Workflow for *Raw Detectors*
@@ -88,18 +88,18 @@ Workflow for *Raw Detectors*
Here is a typical use case for reduce data via tab *Noramlization*
- 1. User specifies *Exp No* and *Scan No* and push button *Load*;
+1. User specifies *Exp No* and *Scan No* and push button *Load*;
- - HFIR-PDR-GUI loads SPICE data according to experiment number and scan number;
- - HFIR-PDR-GUI checks whether vanadium correction file, i.e., detector efficiency file exists on server;
- - HFIR-PDR-GUI checks whether excluded detectors file exists on server;
- - HFIR-PDR-GUI checks log **m1** for wavelength and set to *Wavelength* ;
+ - HFIR-PDR-GUI loads SPICE data according to experiment number and scan number;
+ - HFIR-PDR-GUI checks whether vanadium correction file, i.e., detector efficiency file exists on server;
+ - HFIR-PDR-GUI checks whether excluded detectors file exists on server;
+ - HFIR-PDR-GUI checks log **m1** for wavelength and set to *Wavelength* ;
- 2. User specifies a *Pt.* number and push button *Plot Raw Detector*;
+2. User specifies a *Pt.* number and push button *Plot Raw Detector*;
- - HFIR-PDF-GUI plots the raw detector counts normalized by monitor count;
+ - HFIR-PDF-GUI plots the raw detector counts normalized by monitor count;
- 3. User may push button *Previous Pt.* or *Next Pt.* for the other experiment points;
+3. User may push button *Previous Pt.* or *Next Pt.* for the other experiment points;
@@ -109,15 +109,14 @@ Workflow for *Multiple Scans*
It might be confusing to use the functionalities in tab *Multiple Scans*.
Here is the suggested workflow to reduce multiple scans and possibly merge them.
- 1. Set up *Exp No* and range of scan numbers;
- 2. Push button *Load All* to load and reduce all runs specified in previous step to single-spectrum diffraction pattern;
- 3. Plot all reduced scans in default;
- 4. Optinally plot all data in 2D fill plot;
- 5. User can delete some scans from the reduced scans via GUI or input text edit (not implemented yet);
- 6. Push button *Merge* to merge the scans;
- 7. Push button *Save All* to save all individual scans to files;
- 8. Push button *Save Merged* to save the merged scans to one file;
-
+1. Set up *Exp No* and range of scan numbers;
+2. Push button *Load All* to load and reduce all runs specified in previous step to single-spectrum diffraction pattern;
+3. Plot all reduced scans in default;
+4. Optinally plot all data in 2D fill plot;
+5. User can delete some scans from the reduced scans via GUI or input text edit (not implemented yet);
+6. Push button *Merge* to merge the scans;
+7. Push button *Save All* to save all individual scans to files;
+8. Push button *Save Merged* to save the merged scans to one file;
HB2A Data Reduction
-------------------
@@ -129,50 +128,50 @@ There information can be retrieved from HB2A's data repository accessible from i
Experiment setup and sample log
===============================
- 1. **Wavelength**: There are three settings for neutron wavelength, referenced by sample log *m1*.
+1. **Wavelength**: There are three settings for neutron wavelength, referenced by sample log *m1*.
- - Ge 113: :math:`\lambda = 2.41 \AA`, m1 = 9.45 (The **error** can be 0.05, such that in Exp 231 scan0001, m1=9.5)
- - Ge 115: :math:`\lambda = 1.54 \AA`, m1 = 0
- - Ge 117 :math:`\lambda = 1.12 \AA`, No used
+ - Ge 113: :math:`\lambda = 2.41 \AA`, m1 = 9.45 (The **error** can be 0.05, such that in Exp 231 scan0001, m1=9.5)
+ - Ge 115: :math:`\lambda = 1.54 \AA`, m1 = 0
+ - Ge 117 :math:`\lambda = 1.12 \AA`, No used
- 2. **Collimator translation**: There are two status for collimator, which is specified by sample log *colltrans*
+2. **Collimator translation**: There are two status for collimator, which is specified by sample log *colltrans*
- - *IN*: colltrans = 0
- - *OUT*: colltrans = +/-80
+ - *IN*: colltrans = 0
+ - *OUT*: colltrans = +/-80
Raw data correction files
=========================
- 1. **Detector efficiency**:
+1. **Detector efficiency**:
- - File name: *HB2A_exp0IJK__GE_abc_XY_vcorr.txt* where
+ - File name: *HB2A_exp0IJK__GE_abc_XY_vcorr.txt* where
- - IJK is the experiment number
- - abc is the GE set up. It can be 113, 115 or 117
- - XY is either IN or OUT.
- - Exmaple: *HB2A_exp0400__Ge_113_IN_vcorr.txt*
+ - IJK is the experiment number
+ - abc is the GE set up. It can be 113, 115 or 117
+ - XY is either IN or OUT.
+ - Example: *HB2A_exp0400__Ge_113_IN_vcorr.txt*
- - Web address: *http://neutron.ornl.gov/user_data/hb2a/exp400/Datafiles/HB2A_exp0IJK__Ge_abc_IN_vcorr.txt*
+ - Web address: *http://neutron.ornl.gov/user_data/hb2a/exp400/Datafiles/HB2A_exp0IJK__Ge_abc_IN_vcorr.txt*
- - IJK is the experiment number
- - abc is the GE set up. It can be 113, 115 or 117
- - XY is either IN or OUT.
- - Exmaple: *http://neutron.ornl.gov/user_data/hb2a/exp400/Datafiles/HB2A_exp0400__Ge_113_IN_vcorr.txt*
+ - IJK is the experiment number
+ - abc is the GE set up. It can be 113, 115 or 117
+ - XY is either IN or OUT.
+ - Example: *http://neutron.ornl.gov/user_data/hb2a/exp400/Datafiles/HB2A_exp0400__Ge_113_IN_vcorr.txt*
- 2. **Excluded detectors**: Some detectors might be exluded from the experiment for some reason. It is recorded in some excluded detectors' file.
+2. **Excluded detectors**: Some detectors might be exluded from the experiment for some reason. It is recorded in some excluded detectors' file.
- - File name: *HB2A_exp0IJK__exclude_detectors.txt*
+ - File name: *HB2A_exp0IJK__exclude_detectors.txt*
- - IJK is the epxeriment number
- - Exmaple: *HB2A_exp0400__exclude_detectors.txt*
+ - IJK is the epxeriment number
+ - Example: *HB2A_exp0400__exclude_detectors.txt*
- - Web address: *http://neutron.ornl.gov/user_data/hb2a/expIJK/Datafiles/HB2A_exp0IJK__exclude_detectors.txt*
+ - Web address: *http://neutron.ornl.gov/user_data/hb2a/expIJK/Datafiles/HB2A_exp0IJK__exclude_detectors.txt*
- - IJK is the experiment number
- - Example: *http://neutron.ornl.gov/user_data/hb2a/exp400/Datafiles/HB2A_exp0400__exclude_detectors.txt*
+ - IJK is the experiment number
+ - Example: *http://neutron.ornl.gov/user_data/hb2a/exp400/Datafiles/HB2A_exp0400__exclude_detectors.txt*
- 3. Detector gaps: The 2-theta gap (in unit degrees) can be changed among cycles.
+3. Detector gaps: The 2-theta gap (in unit degrees) can be changed among cycles.
- Location example: *http://neutron.ornl.gov/user_data/hb2a/exp400/Datafiles/HB2A_exp0400__gaps.txt*
@@ -182,3 +181,4 @@ Limitation
- HFIR powder reduction GUI supports for instrument HB2A only in release 3.4.0;
+.. categories:: Interfaces
diff --git a/docs/source/interfaces/HFIR_4Circle_Reduction.rst b/docs/source/interfaces/HFIR_4Circle_Reduction.rst
index 348935d56466844c9d62b20dcdb1b8eab75f2c15..d152332983e771d7969dcb323672754074820128 100644
--- a/docs/source/interfaces/HFIR_4Circle_Reduction.rst
+++ b/docs/source/interfaces/HFIR_4Circle_Reduction.rst
@@ -14,7 +14,7 @@ HFIR's four-circle single crystal diffractometer in SPICE format.
Introduction of Tabs
--------------------
- 1. **Setup and Data Access**: Configure the instrument name, data server URL and directories.
+1. **Setup and Data Access**: Configure the instrument name, data server URL and directories.
- Configure the instrument name;
- Set up and test HB3A data server's URL;
@@ -22,11 +22,13 @@ Introduction of Tabs
- Configure the directory to save working result;
- Download data from server;
- 2. **View Raw Data**: View 2D image of counts on detector of one measurement.
+
+2. **View Raw Data**: View 2D image of counts on detector of one measurement.
- Plot the counts of the 256 by 256 2D detector;
- 3. **Calculate UB**: Calculate UB matrix.
+
+3. **Calculate UB**: Calculate UB matrix.
- Find peak in one measurement;
- Option to load Miller index directly from SPICE file;
@@ -34,232 +36,329 @@ Introduction of Tabs
- Re-index the peaks;
- Refine UB matrix with more than two peaks.
- 4. **Merge Scan**: Merge all the measurements in a scan.
+
+4. **Merge Scan**: Merge all the measurements in a scan.
- Merge all measuring points in a scan to an MDEventWorkspace in HKL-frame or Q-sample-frame;
- Allow various ways to set up UB matrix
- 5. **Peak Integration**: Integrate peaks
+
+5. **Peak Integration**: Integrate peaks
- Still in developmenet
- 6. **Survey**: Get experiments runs' information by scanning through all SPICE files in an experiment
+
+6. **Survey**: Get experiments runs' information by scanning through all SPICE files in an experiment
- For selected scans in an experiment, list the run (i.e., Pt.) with maximum detector counts in a specific scan;
- For each listed run, the information show includes detector counts and HKL
-Converting SPICE UB matrix to Mantid UB matrix
-----------------------------------------------
+Use Cases
+---------
-Assuming that SPICE UB matrix (3 x 3) is composed as
- * R11, R12, R13
- * R21, R22, R23
- * R31, R32, R33
+Here are some use cases that can be used as examples.
-Then, converted to UB matrix in Mantid, it is like
- * R11, R12, R13
- * R31, R32, R33
- * -R21, -R22, -R23
+Set up reduction
+++++++++++++++++
+The first step to reduce data with 4-Circle GUI is to set up the reduction environment.
+Reduction cannot work correctly if this step is **SKIPPED**.
-Peak Integration: Normalization
-+++++++++++++++++++++++++++++++
+1. Go to tab *Setup & Data Access*;
+2. Set up *Data Directory* and *Working Directory*;
+3. An alternative way to step 2 is to push button *Load Default*;
+4. Push button *Apply*. Mantid thus checks whether the setup, including source data file's URL, data directory and working directory are valid. Be noticed that the check of URL may return **timeout** error. It might be a false alarm. You might push the *Apply* button few more times.
-Counts of neutron on any detector shall be normalized by its corresponding monitor
-count and then be multiplied by a constant specified by user.
-Peak Integration with automatic background subtraction by IntegrateEllipsoids
------------------------------------------------------------------------------
+Experiment overview
++++++++++++++++++++
-There is no existing algorithm in Mantid to integrate ellipsoid because1
-algorithm *IntegrateEllipsoids* works only for event in unit as time-of-flight.
+Usually if it is the first time to reduce data for an experiment, it is
+recommended to go through the whole experiment to gather some information.
+
+1. Go to tab *Survey*;
+2. Set up experiment number on the top of application window;
+3. Input the range of the scan numbers for survey. Leaving them blank will result in going through all scans of the experiment;
+4. Click button *Survey*;
+5. It might take a while to load and scan all the SPICE files belonged to an individual experiment. After it is finished, the result will be shown in the table.
+6. Save the survey result for future by clicking button *Save*;
+7. Select a row, and click button *View Peak*, application will switch to tab *View Raw Data* automatically and set the scan and Pt number from the selected row.
-So far, there is only one algorithm is implemented to integrate peaks for HB3A.
-Simple cuboid integration
-+++++++++++++++++++++++++
+Workflow to calculate and refine UB matrix
+++++++++++++++++++++++++++++++++++++++++++
+Here is a typical use case to calculate UB matrix after initial setup.
-This is a simple algorithm for approximate the integrated peak intensity.
+1. User specifies *Experiment* and pushes button *Set*
+2. Users may do a new survey or load a survey result file in tab *Survey*;
+3. User enters tab *View Raw Data* and inputs scan number and list all the measuring points (Pt.)
+4. User views all the measurements
+
+ * User finds out the measurement with the strongest reflection and push button use
+ * Alternatively, user can use the survey result to find out the Pt. with the maximum counts of the scan
+
+5. GUI shifts to tab *Calculate UB* automatically
+6. User pushes button *Find Peak* with checking *Load HKL from file*
+7. GUI finds the peak center and load HKL
+8. User pushes button *Add peak* to add the peak to table
+9. User repeats step 2 to 9 to add other peaks
+10. User select the peaks that are linearly independent and pushes *Calcualte UB*
+11. GUI calculates UB matrix and show the result
+12. User may push *Index peak* to use the calculated UB matrix to index peaks in the table to check UB matrix;
+13. User may refine the UB matrix and thus lattice parameters
+
+ a. user adds more peaks to the UB peak table;
+ b. user selects at least 3 non-degenerate peaks;
+ c. user clicks button *Refine*;
+ d. application refines UB matrix and outputs the refined UB matrix, refined lattice parameters and their error.
-Measuring one peak usually contains around 20 Pt. in a same scan.
-In most of the cases, the first and last several measurements (called as *Pt* in SPICE) are
-background.
-Therefore, the background for per measurement can be estimated by averaging the
-summed number of counts normalized by either monitor counts or measuring time.
-Estimating background
----------------------
+Workflow to merge measurements in scan
+++++++++++++++++++++++++++++++++++++++
-For each measurment, the background :math:`B_i` is calculated as
+Here is a typical use case to merge all the measuring points (Pt.) in a scan
-..math.. B_i = \frac{\sum^{(pt)}_{\{d_i\}}n_{d_i}}{F^{(a)}_{d_i}}
+1. User specifies *Experiment* and pushes button *Set*
-where :math:`F^{(a)}` is the normlization of either time or beam monitor counts,
-and :math:`n_{d_i}` is the neutron counts of measumrent :math:`d_i`.
+2. User enters tab *Merge Scan*
-Then the estimation of the normalized background for each measurement is
+3. User specifies the UB matrix either by *From tab Calculate UB* or by entering the values to text editor
-..math.. B^{(e)} = \sum_{\{P_i\}}\frac{B_i}{N}
+4. User pushes button *Set*
-where :math:`N` is the number of measurements used to calculated background.
+5. User specifies the frame in which the merged data will be in. If the target frame is Q-Sample-Sapce, then there is no need to specify UB matrix
-Integrating a peak in cuboid
-----------------------------
+6. User specifies the scan numbers and push button *Add*
-In the Q-space, by masking each measurement, it is assumed that the peak's intensity
-is very close to the number of counts in the unmasked cuboid normalized either by
-measuring time or beam monitor counts with background removed.
+7. User specifies the base name for the output MDEventWorkspaces
-..math.. I = \sum_{i} \frac{n_i}{F_i} - B^{(e)}
+8. User pushes button *Process*
-where :math:`n_i` is the counts of Pt i in the region of interest,
-:math:`F_i` is the normalization factor of Pt i,
-and `B^{(e)}` is the estimated background per Pt with the same
-normalization type of :math:`F_i`.
+9. User goes to MantidPlot to view the merged scan by SliceView or Vates.
Peak Integration with automatic background subtraction by approximation
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
-TODO/NOW - Polish this section!
-
This is an easy approximation to integrate a peak with background subtraction
by specified region of interest.
The pre-requisit is that all events are normalized by monitor counts
and scaled up by same factor (e.g, 1500).
-1. Set up region of interest
- Define region of interest on the detector.
+1. Set up region of interest
-2. Mask detectors
- Mask all the detectors out of the region of interest, which is defined by the pixel ID of its upper-left corner and lower-right corner.
+ - define region of interest on the detector
+ - check whether the ROI does not exclude any peak
-3. Integrate counts inside region of interest
- Bla bla bla
+2. Specify background Pts.
-4. Estimate background
+ - specify the Pts. in the scan that are used to estimate background
-5. Background subtraction
- Subtract the background from detector's count. If the result is negative, keep it as negative.
+3. Integrate peaks
+ - select peaks to integrate
+ - integrate peaks
-Use Cases
----------
+4. Review the integration result
+5. Export to Fullprof peak integration (.int) file.
-Here are some use cases that can be used as examples.
-Set up reduction
-++++++++++++++++
-The first step to reduce data with 4-Circle GUI is to set up the reduction environment.
-Reduction cannot work correctly if this step is **SKIPPED**.
+UB Matrix Calcualtion and Refinement
+------------------------------------
+
+
+Converting SPICE UB matrix to Mantid UB matrix
+++++++++++++++++++++++++++++++++++++++++++++++
- 1. Go to tab *Setup & Data Access*;
+Assuming that SPICE UB matrix (3 x 3) is composed as
+ * R11, R12, R13
+ * R21, R22, R23
+ * R31, R32, R33
- 2. Set up *Data Directory* and *Working Directory*;
+Then, converted to UB matrix in Mantid, it is like
+ * R11, R12, R13
+ * R31, R32, R33
+ * -R21, -R22, -R23
- 3. An alternative way to step 2 is to push button *Load Default*;
- 4. Push button *Apply*. Mantid thus checks whether the setup, including source data file's URL, data directory and working directory are valid. Be noticed that the check of URL may return **timeout** error. It might be a false alarm. You might push the *Apply* button few more times.
+Peak Integration
+----------------
+Unlike TOF single crystal diffractometer, HB3A uses a different method to integrate diffraction peaks.
-Survey experiment
-+++++++++++++++++
+Presently, HB3A reduction interface supports 3 types of integrations.
-Usually if it is the first time to reduce data for an experiment, it is
-recommended to go through the whole experiment to gather some information.
+Normalization
++++++++++++++
- 1. Go to tab *Survey*;
+Counts of neutron on any detector shall be normalized by its corresponding monitor
+count and then be multiplied by a constant specified by user.
- 2. Set up experiment number on the top of application window;
+But for HB3A, the normalization to counting *time* is more reliable because the
+beam monitor may be unstable.
- 3. Input the range of the scan numbers for survey. Leaving them blank will result in going through all scans of the experiment;
- 4. Click button *Survey*;
+Region of interest
+++++++++++++++++++
- 5. It might take a while to load and scan all the SPICE files belonged to an individual experiment. After it is finished, the result will be shown in the table.
+A region of interest (ROI) on the detector can be defined for each scan.
+The signals in the ROI of each Pt. in a scan construct a 3-dimensional diffraction peak.
- 6. Save the survey result for future by clicking button *Save*;
+The purpose to define the region of interest on detector is to reduce the affect of background noise.
- 7. Select a row, and click button *View Peak*, application will switch to tab *View Raw Data* automatically and set the scan and Pt number from the selected row.
+Integration algorithm 1: simple counts summation
+++++++++++++++++++++++++++++++++++++++++++++++++
-Workflow to calculate and refine UB matrix
-++++++++++++++++++++++++++++++++++++++++++
+This algorithm is also called *simple cuboid integration*,
+which is to approximate the integrated peak intensity.
-Here is a typical use case to calculate UB matrix after initial setup.
+Measuring one peak usually contains around 20 Pt. in a same scan.
+In most of the cases, the first and last several measurements (called as *Pt* in SPICE) are
+background.
+Therefore, the background for per measurement can be estimated by averaging the
+summed number of counts normalized by either monitor counts or measuring time.
+
+The integrated peak intensity is
+
+.. math:: I = \sum_i (C_i - B_i) \times \Delta X
+
+where
+ * :math:`C_i` is the normalized detector counts in ROI of measurement *i*
+ * :math:`\Delta X` is the motor step
+ * :math:`B_i` is the estimated background
- 1. User specifies *Experiment* and pushes button *Set*
+The error can be calculated as
- 2. Users may do a new survey or load a survey result file in tab *Survey*;
+.. math:: \sigma = \sum_i \sqrt{C_i} \cdot \Delta X
- 3. User enters tab *View Raw Data* and inputs scan number and list all the measuring points (Pt.)
- 4. User views all the measurements
+Estimating background
+^^^^^^^^^^^^^^^^^^^^^
- * User finds out the measurement with the strongest reflection and push button use
- * Alternatively, user can use the survey result to find out the Pt. with the maximum counts of the scan
+For each measurment, the background :math:`B_i` is calculated as
- 5. GUI shifts to tab *Calculate UB* automatically
+.. math:: B^{(e)} = \frac{\sum_i^{<pt>}C_i}{|<pt>|}
- 6. User pushes button *Find Peak* with checking *Load HKL from file*
+where :math:`<pt>` is a set of measurment points that are specified by users.
+Usually they are the first and last several measurements in a scan.
- 7. GUI finds the peak center and load HKL
+Then this estimated **normalized** background value can be applied to each measuremnt, whose counts are normalized.
- 8. User pushes button *Add peak* to add the peak to table
- 9. User repeats step 2 to 9 to add other peaks
+Integration algorithm 2: simple counts summation with fitted background
++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
- 10. User select the peaks that are linearly independent and pushes *Calcualte UB*
+This algorithm is based on previous algorithm.
+It is assumed that if the statistic of the diffraction peak is good enough, then
+the curve, i.e., moving motor position against normalized counts, can be
+fitted with a Gaussian plus flat background.
- 11. GUI calculates UB matrix and show the result
+.. Gaussian formula comes from http://mathworld.wolfram.com/GaussianFunction.html
- 12. User may push *Index peak* to use the calculated UB matrix to index peaks in the table to check UB matrix;
+.. math:: C = A\times e^{-(x - x_0)^2/(2s^2)} - B
- 13. User may refine the UB matrix and thus lattice parameters
+where
+ * *x* is the (moving) motor position
+ * *C* is the normalized counts in ROI when the moving motor is at *x*
- 1. user adds more peaks to the UB peak table;
+The integrated peak intensity and its error will be calculated as
- 2. user selects at least 3 non-degenerate peaks;
+.. math:: I = \sum_i^{<pt>} (C_i - B) \times \Delta X
- 3. user clicks button *Refine*;
+where
+ * :math:`C_i` is the normalized detector counts in ROI of measurement *i*
+ * :math:`\Delta X` is the motor step
+ * :math:`B_i` is the estimated background
+ * the set of measurements *<pt>* is defined by the motor positions in the range of :math:`x_0 \pm \frac{N}{2}FWHM`.
- 4. application refines UB matrix and outputs the refined UB matrix, refined lattice parameters and their error.
+ - usually the default value of *N* is set to 2.
+ - :math:`FWHM = 2\sqrt{2\ln2}s \approx 2.3548s`
+The error can be calculated as
-Workflow to merge measurements in scan
-++++++++++++++++++++++++++++++++++++++
+.. math:: \sigma = \sum_i \sqrt{C_i} \cdot \Delta X
-Here is a typical use case to merge all the measuring points (Pt.) in a scan
- 1. User specifies *Experiment* and pushes button *Set*
+Integration algorithm 3: calculate intensity from fitted model
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
+
+It is assumed that for a well measured diffraction peak, in 3D,
+the counts in ROI of each measurement from the edge of the peak to the other edge of peak
+against the moving motor's positions should be represented by a Gaussian function with
+flat background
+
+.. math:: C = A\times e^{-(x - x_0)^2/(2s^2)} - B
- 2. User enters tab *Merge Scan*
+Then the peak intensity should be the integral of the Gaussian from :math:`-\inf` to :math:`+\inf`,
+i.e.,
- 3. User specifies the UB matrix either by *From tab Calculate UB* or by entering the values to text editor
+.. math:: I = A\times s\times\sqrt{2\pi}
- 4. User pushes button *Set*
+The error of the intensity should be calculated by the propagation of fitted error of *A* and *s*.
- 5. User specifies the frame in which the merged data will be in. If the target frame is Q-Sample-Sapce, then there is no need to specify UB matrix
+.. math:: \sigma_I^2 = 2\pi (A^2\cdot \sigma_s^2 + \sigma_A^2\cdot s^2 + 2\cdot A\cdot s\cdot \sigma_{As})
- 6. User specifies the scan numbers and push button *Add*
+Issue
+^^^^^
- 7. User specifies the base name for the output MDEventWorkspaces
+It is found that the standard deviation of *A* from covariance matrix calculated from **scipy.curve_fit** library
+is very large, which causes an unreasonably large estimated error on integrated intensity *I*.
- 8. User pushes button *Process*
- 9. User goes to MantidPlot to view the merged scan by SliceView or Vates.
+Other peak integration algorithms in consideration
+++++++++++++++++++++++++++++++++++++++++++++++++++
+There are some other peak integration algorithms that we discussed.
+None of them has been implemented.
+But it is still worth to document them here.
+Peak Integration with automatic background subtraction by IntegrateEllipsoids
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+There is no existing algorithm in Mantid to integrate ellipsoid because1
+algorithm *IntegrateEllipsoids* works only for event in unit as time-of-flight.
+
+So far, there is only one algorithm is implemented to integrate peaks for HB3A.
+
+
+Integrating a peak in cuboid in Q-space
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+In the Q-space, by masking each measurement, it is assumed that the peak's intensity
+is very close to the number of counts in the unmasked cuboid normalized either by
+measuring time or beam monitor counts with background removed.
+
+.. math:: I = \sum_{i} \frac{n_i}{F_i} - B^{(e)}
+
+where :math:`n_i` is the counts of Pt i in the region of interest,
+:math:`F_i` is the normalization factor of Pt i,
+and `B^{(e)}` is the estimated background per Pt with the same
+normalization type of :math:`F_i`.
+
+
+Estimating background
+^^^^^^^^^^^^^^^^^^^^^
+
+For each measurment, the background :math:`B_i` is calculated as
+
+.. math:: B_i = \frac{\sum^{(pt)}_{\{d_i\}}n_{d_i}}{F^{(a)}_{d_i}}
+
+where :math:`F^{(a)}` is the normlization of either time or beam monitor counts,
+and :math:`n_{d_i}` is the neutron counts of measumrent :math:`d_i`.
+
+Then the estimation of the normalized background for each measurement is
+
+.. math:: B^{(e)} = \sum_{\{P_i\}}\frac{B_i}{N}
+
+where :math:`N` is the number of measurements used to calculated background.
-Limitation
-----------
-- HFIR single crystal reduction GUI supports for instrument HB3A only from release 3.5.0 and nightly.
.. categories:: Interfaces