Update documentation within the user guide for the spectrum viewer (#…

…2050)

docs/release_notes/next/feature-2048-spectrum_documentation

@@ -0,0 +1 @@
+#2048: Update spectrum documentation to reflect changes made to the Spectrum Viewer.

docs/user_guide/gui/spectrum_viewer.rst

@@ -1,29 +1,98 @@
 Spectrum Viewer
 =================
 
-Mantid Imaging offers a spectrum viewer where users can select many regions of interest (ROI) for time of flight (TOF) data and view the spectrum of each ROI. 
-The spectrum viewer can be used to export the spectrum of each ROI and its respective coordinates to a separate csv file.
+
+The Spectrum Viewer is a tool for viewing the spectrum of each region of interest (ROI) in time of flight (TOF) data.
 
 The spectrum viewer can be accessed from the main menu under "Workflow" > "Spectrum Viewer".
 
-To try out the spectrum viewer, you find a basic example workflow to follow within `quick start <https://mantidproject.github.io/mantidimaging/user_guide/quick_start.html>`_
+To try out the spectrum viewer, you can find a basic example workflow to follow within `quick start <https://mantidproject.github.io/mantidimaging/user_guide/quick_start.html>`_
 
 .. image:: ../../_static/spectrum_viewer.png
-    :alt: Spectrum Viewer
+    :alt: Spectrum Viewer ROI Mode
     :width: 90%
+    :align: center
 
 Above you can see that the spectrum viewer consists of a left hand side panel and a right hand side panel.
 The left hand side panel contains the ROI selection tools and the right hand side panel contains the spectrum plot.
 
-Similar to the image view `image_view <https://mantidproject.github.io/mantidimaging/user_guide/gui/image_view.html>`_, the spectrum viewer has a histogram view to the right of the sample image to control the brightness and contrast of the displayed image.
+Similar to the `image_view <https://mantidproject.github.io/mantidimaging/user_guide/gui/image_view.html>`_, the spectrum viewer has a histogram view to the right of the sample image to control the brightness and contrast of the displayed image.
 To read more about the histogram view see `image_view <https://mantidproject.github.io/mantidimaging/user_guide/gui/image_view.html>`_ .
 
 Below the sample image is the spectrum line plot, which shows the intensity of each ROI as a function of the TOF value. 
 You can select the TOF range to be displayed by clicking and dragging the mouse over the vertical bars on the left and right of the plot.
 
+The Spectrum Viewer has two main modes of operation: "ROI" mode and "Image" mode.
+
+
+ROI Mode
+----------
+ROI mode is the default mode of the Spectrum Viewer. In this mode, you can add, rename and remove many ROIs to and from the spectrum viewer and view the spectrum of each ROI.
+The spectrum viewer can be used to export the spectrum of each ROI and its respective coordinates to a separate csv file.
+
+To add an ROI, click the "Add" button and then click and drag the mouse over the newly created ROI within the sample image to resize and position the ROI.
+To rename an ROI, click on the ROI name you would like to rename within the table of ROI's and type the new name.
+To remove an ROI, click on the ROI would like to remove within the table of ROI's and the click the "Remove" button to remove.
+
+ROI mode allows users to export the spectrum of each ROI and its respective coordinates to a separate csv file using the "Export spectrum" button.
+The export spectrum button will open a file dialog where you can select the directory and file name to save the csv file and is only enabled if you have selected a valid tomography data stack and open beam data stack.
+Both stacks must be the same shape and size. If the open beam is a different shape or size, the export spectrum button will be disabled and a warning message will be displayed.
+
+
+Image Mode
+----------
+Image mode, accessible by selecting the "Image" tab, is a mode of the Spectrum Viewer where you can view the spectrum within a singular region of interest (ROI) and export the spectrum in a format compatible with `RITS <https://mlfinfo.jp/bl22/en/GUI-RITS.html>`_ .
+In this mode, you can select whether you would like to export your data in single spectrum or binned spectrum format. 
+You can also select the step size and bin size. If the step size is the same as the bin size, a tiled average will be performed. If the step size is less than the bin size, a rolling average will be performed. The unit of measurement is pixels
+
+.. image:: ../../_static/Spectrum_viewer_ImageMode.png
+    :alt: Spectrum Viewer Image Mode
+    :width: 90%
+    :align: center
+
+Error Mode
+-------------------
+
+Additionally, you can choose between two different modes of error calculation: standard deviation and propagated error.
+
+Choosing between Standard Deviation and Error Propagation will depend on the nature of your measurements and the sources of error.
+
+**Standard Deviation Mode:**
+If you have multiple measurements of the same quantity (for example, repeated measurements of the same spectrum), and the errors are random and uncorrelated, then standard deviation would good a good choice of error mode to select.
+
+Standard deviation will provide a spread of your measurements and can help you to identify outliers.
+
+**Propagated Error Mode:**
+If your final result will be derived from multiple measurements through some formula (for example, calculating the lattice spacing using Bragg’s law), and you believe the errors are systematic and correlated, then error propagation may be the better choice.
+Error propagation will allow you to estimate how errors in individual measurements contribute to the error in the final result.
+
+Both Standard Deviation and Error Propagation can be used in conjunction, You could use standard deviation to analyse the error in individual measurements, and then use propagated error to analyse how the errors affect your final result.
+The choice between the two methods depends on the specific details of your experiment and the nature of your data. 
+
+
+Similarly to the image view, the spectrum viewer requires a valid tomography data stack, open beam data stack and spectrum log file to be selected.
+
+
 ROIs
 ----------
 Using the ROI selection tools, you can add, rename and remove many ROIs to the spectrum viewer and view the spectrum of each ROI.
 When you are happy with the ROIs you have created and positioned over the sample image, you can export the spectrum of each ROI and its respective coordinates to a separate csv file using the "Export spectrum" button.
 
 
+Common Questions
+-------------------
+
+**Why would I want to export the spectrum for multiple ROI's?**
+
+The spectrum viewer allows you to export the spectrum of each ROI and its respective coordinates to a separate csv file.
+This can be useful if you want to analyse the spectrum of each ROI in a different program or if you want to compare the spectrum of each ROI to each other for various areas across your sample.
+
+
+**Why do I need to normalise against the open beam to to export my data?**
+
+Normalising against the open beam is required to convert from counts to transmission. The Spectrum Viewer needs to convert measured counts to transmission, which is more physically meaningful as a quantity.
+It can be defined as the ratio of the intensity with the sample in the beam to the intensity without the sample (open beam). The ability to export data relies on an open beam to convert to transmission and is thus greyed out unless a valid open beam stack has been selected.
+
+**Why do I need to load a sample spectrum log file with my data to export to RITS?**
+The conversion from counts to transmission in neutron imaging involves the use of both the sample data (counts) and the open beam data. The spectra file, which contains the energy or wavelength and corresponding intensity or counts, is also required in this process.
+The spectra file provides the energy or wavelength information for each count. This is needed for interpreting the transmission data, as different materials interact differently with neutrons of different energies or wavelengths. 

docs/user_guide/quick_start.rst

@@ -125,11 +125,34 @@ you can apply some post-processing operations (such as circular mask), or just s
 Spectrum Viewer
 ###############
 
-The spectrum viewer is a tool that allows you to view spectrum data within an image stack. To open the spectrum viewer go to Workflow > Spectrum Viewer.
-
-1. Resize the orange ROI to just cover the size of the sample. This will allow you to see the spectrum of the sample which you will be able to see in the spectrum line plot at the bottom of the window.
-2. Click the "Add" button on the left to add another ROI which you can position over a particular detail of your choosing on the sample.
-3. Within the ROI Table, double click "roi_1" to rename to something more descriptive of what the ROI is covering.
-4. To remove an ROI, you can select the ROI you would like to remove within the ROI Table and click the "Remove" button on the left.
-5. To export spectrum data, you can click the "Export spectrum" button and select a location and filename. Two files will be saved to this location <filename>.csv and <filename>_roi_coords.csv. <filename>.csv contains the spectrum data for each ROI. <filename>_roi_coords.csv contains the coordinates of the ROIs in the image stack.
-6. If you have a TOF dataset loaded where you would like to normalise to the open beam, you can do so by toggling the "Normalise to open beam" checkbox. This will normalise the spectrum to the open beam spectrum. The greyed out drop down menu will become available and you can select which dataset you would like to use as the open beam.
+.. image:: ../_static/spectrum_viewer.png
+    :alt: Spectrum Viewer Window
+    :align: center
+
+The spectrum viewer is a tool that allows you to view spectrum data within a Time of flight (TOF) image stack. To open the spectrum viewer go to Workflow > Spectrum Viewer.
+
+**Export Spectrum Data**:
+
+#. Resize the ROI to just cover the size of the sample within your data or a particular area of interest within your sample. This will allow you to see the spectrum within the ROI which you will be able to see in the spectrum line plot at the bottom of the window.
+
+#. Click the "Add" button on the left to add another ROI which you can position over a particular detail of your choosing on the sample.
+
+#. Within the ROI Table, double click "roi_1" to rename to something more descriptive of what the ROI is covering.
+
+#. To remove an ROI, you can select the ROI you would like to remove within the ROI Table and click the "Remove" button on the left.
+
+#. To export spectrum data, you can click the "Export spectrum" button and select a location and filename. Two files will be saved to this location <filename>.csv and <filename>_roi_coords.csv. <filename>.csv contains the spectrum data for each ROI. <filename>_roi_coords.csv contains the coordinates of the ROIs in the image stack.
+
+#. If you have a TOF dataset loaded where you would like to normalise to the open beam, you can do so by toggling the "Normalise to open beam" checkbox. This will normalise the spectrum to the open beam spectrum. The greyed out drop down menu will become available and you can select which dataset you would like to use as the open beam.
+
+**Export Single or Binned Spectrum Data in RITS Format**
+
+#. To enter IMAGE mode to export single or binned spectrum data in RITS format, you can click the "IMAGE" tab at the top of the table of ROIs.
+
+#. Resize the ROI in the same way as before for exporting regular spectrum data to cover an area of the sample you would like to acquire the spectrum for.
+
+#. Select the output mode from the top drop down menu on the left which replaces the table of ROIs, either "Single Spectrum" or 2D Binned" depending on what you would like to export. 2D binned will bin within the ROI and export the binned data as multi-spectrum data.
+
+    #. If you choose to export as a "2D Binned", you can choose the size of your bin in pixels squared from the drop down menu on the left. You can also select the step size of the bin from the drop down menu. If the step size if the same as the bin size, the binned data will be non-overlapping tiled binning. If the step size is smaller than the bin size, the binned data will be overlapping which will achieve a rolling average.
+
+#. Choose between "Propagated" and "Standard Deviation" from the "Error Mode" drop down box. Propagated will calculate the error from the propagated error of the counts in the spectrum. Standard Deviation will calculate the error from the standard deviation of the counts in the spectrum. The mode you choose will depend on the data you are working with. Optionally, you could export to both modes separately to compare the results.