Update docs

docs/user_docs/constants.rst

@@ -20,8 +20,7 @@ Tissue water density [0]_::
 
     TISSUE_WATER_DENSITY = {'GM':0.78,'WM':0.65,'CSF':0.97} 
 
-
-Mollecular mass of water::
+Molecular mass of water::
 
     H2O_MOLECULAR_MASS = 18.01528   # g/mol
 
@@ -33,6 +32,15 @@ Number of protons in water::
 
     H2O_PROTONS = 2
 
+The integrated water signal is referenced to a single reference basis.
+There are three defaults defined in FSL-MRS, and each are tried in the order listed here.
+Each possible reference is equivalent to a predetermined number of protons and has associated integration limits.
+There are::
+
+    WATER_SCALING_METAB = ['Cr', 'PCr', 'NAA']
+    WATER_SCALING_METAB_PROTONS = [5, 5, 3]
+    WATER_SCALING_DEFAULT_LIMITS = [(2, 5), (2, 5), (1.8, 2.2)]
+
 Relaxation parameters
 *********************
 Values are derived from a survey of the literature. References listed below. Values for metabolites are derived from an average of NAA, Cr and Cho peaks.

docs/user_docs/quantitation.rst

@@ -11,4 +11,18 @@ For this FSL-MRS provides the :code:`svs_segment` and :code:`mrsi_segment` comma
     mrsi_segment -t T1.nii.gz -f tissue_frac mrsi_data.nii.gz
 
 :code:`svs_segment` creates a small JSON file which can be passed to the fitting routines. :code:`mrsi_segment` creates NIfTI files of the fractional tissue volumes registered to the MRSI volume.
-:code:`svs_segment` and :code:`mrsi_segment` both rely on fsl_anat to run FSL FAST tissue segmentation. If fsl_anat has already been run then the :code:`-t T1.nii.gz` can be substituted with :code:`-a T1.anat`. 
\ No newline at end of file
+:code:`svs_segment` and :code:`mrsi_segment` both rely on fsl_anat to run FSL FAST tissue segmentation. If fsl_anat has already been run then the :code:`-t T1.nii.gz` can be substituted with :code:`-a T1.anat`. 
+
+
+Water Reference Scaling Model
+-----------------------------
+If provided with an unsuppressed water reference FSL-MRS can generate metabolite concentrations in units of molarity (moles of substance per unit-volume, mol/L), or molality (moles of substance per unit-weight, mol/kg). Scaling is performed alongside relaxation correction as described by equations 4 & 6 of [NEAR20]_. 
+
+Referencing to water is carried out by comparing the integrated water resonance in the unsuppressed water (between 1.65 and 7.65 ppm) to the integrated area of a reference metabolite. The raw unsuppressed signal is first fitted using to a simple model (a single peak with Voigt lineshape), and integration is carried out on the fitted data after residual phase has been removed. This is to ensure the corruption of the first few FID points doesn't result in integration of broad, negative-valued wings of the water peak. Similarly the integration of the reference metabolite is carried out on the scaled, broadened basis with the influence of phase and baseline removed.
+
+The integrated areas are shown in the final plot of the html report if a reference dataset is provided.
+
+References
+----------
+
+.. [NEAR20] `Near J et al. Preprocessing, analysis and quantification in single‐voxel magnetic resonance spectroscopy: experts' consensus recommendations. NMR in Biomed 2020.  <https://pubmed.ncbi.nlm.nih.gov/32084297>`_
\ No newline at end of file