update documentation

DOCS/_Paleopizometry.md

@@ -14,16 +14,18 @@ For the first requirement, the GrainSizeTools script includes common mineral pha
 
 For the second requirement, the function will automatically convert the equivalent circular diameter to linear intercepts where applicable using de Hoff and Rhines (1968) correction. This is, **you don't have to worry about whether the piezometer was originally calibrated using linear intercepts**, always use the equivalent circular diameters in microns.
 
-The third requirement is key for a correct estimation of the differential stress since each paleopiezometer was calibrated for a specific average grain size (e.g. the arithmetic mean, median, or RMS mean) and, hence, **only provides valid results if the same type of average is used**. Also, **you should not use any type of stereological correction for the estimation of the average grain size**, if the author(s) of the piezometer used any type of stereological correction, the average grain size will be automatically corrected by the function. 
+The third requirement is key for a correct estimation of the differential stress since each paleopiezometer was calibrated for a specific average grain size (e.g. the arithmetic mean, median or RMS mean) and, hence, **only provides valid results if the same type of average is used**. Also, **you should not use any type of stereological correction for the estimation of the average grain size**, if the author(s) of the piezometer used any type of stereological correction, the average grain size will be automatically corrected by the function. 
 
 The fourth requirement means that the user has to decide whether to correct or not the estimate of the differential stress for plane stress using the correction factor proposed by Paterson and Olgaard (2000). The rationale for this is that the experiments designed to calibrate piezometers are mainly performed in uniaxial compression while natural shear zones approximately behave as plane stress volumes.
 
-Below are examples of how to obtain information about the different piezometers and define these parameters.
+In the next subsection, we will show examples of how to obtain information about the different piezometers and define these parameters.
 
 
 ## Get information on piezometric relations
 
-Table 1 provides a list of the all piezometric relations currently available in the GrainSizeTools script with features (the type of average to use and the DRX mechanism) and references. The experimentally-derived parameters are provided in Tables 2 to 5. Besides, you can get information from the console on the different available piezometric relations  just by typing ``piezometers.*()``, where * is the mineral phase, either ``quartz``, ``calcite``, ``olivine``, or ``feldspar``. For example:
+Table 1 provides a list of the all piezometric relations currently available in the GrainSizeTools script with features (the type of average to use and the DRX mechanism) and references. The experimentally-derived parameters are provided in Tables 2 to 5.
+
+Besides, you can get information interactively on the different available piezometric relations from the console just by typing ``piezometers.*()``, where * is the mineral phase, either ``quartz``, ``calcite``, ``olivine``, or ``feldspar``. For example:
 
 ```python
 piezometers.quartz()
@@ -41,7 +43,7 @@ Available piezometers:
 'Twiss'
 ```
 
-Also, if you want to obtain the complete information of a specific piezometer you can do it in the following way:
+If you want to get the details of a particular piezometric relationship you can do so as follows. Remember that the relationship between recrystallized grain size and differential stress is ***σ~d~ = Bg^-m^***  where σ~d~ and g are the differential stress and the average grain size respectively.
 
 ```python
 piezometers.quartz('Twiss')
@@ -50,12 +52,19 @@ piezometers.quartz('Twiss')
 ```
 (550,
  0.68,
- 'Ensure that you entered the apparent grain size as the arithmeic mean grain size',
+ 'Ensure that you entered the apparent grain size as the arithmetic mean grain size',
  True,
  1.5)
 ```
 
-where...TODO
+Note the five different outputs separated by commas which correspond with:
+- the constant *B* of the piezometric relation
+- the exponent *m* of the piezometric relation
+- A warning indicating the average to use with this piezometric relation
+- An indication of whether the piezometric relation was calibrated using linear intercepts (if ``False`` the piezometric relation was calibrated using equivalent circular diameters.
+- The stereological correction factor used (if applicable). If ``False``, no stereological correction applies.
+
+
 
 **Table 1.** Relation of piezometers (in alphabetical order) and the apparent grain size required to obtain meaningful differential stress estimates
 
@@ -134,51 +143,154 @@ where...TODO
 
 
 
-## Using the ``calc_diffstress()`` function
+## Estimate differential stress using the ``calc_diffstress()`` function
+
+Let us first look at the documentation of the:
+
+```python
+?calc_diffstress
+
+Signature: calc_diffstress(grain_size, phase, piezometer, correction=False)
+Docstring:
+Apply different piezometric relations to estimate the differential
+stress from average apparent grain sizes. The piezometric relation has
+the following general form:
+
+df = B * grain_size**-m
+
+where df is the differential stress in [MPa], B is an experimentally
+derived parameter in [MPa micron**m], grain_size is the aparent grain
+size in [microns], and m is an experimentally derived exponent.
+
+Parameters
+----------
+grain_size : positive scalar or array-like
+    the apparent grain size in microns
+
+phase : string {'quartz', 'olivine', 'calcite', or 'feldspar'}
+    the mineral phase
+
+piezometer : string
+    the piezometric relation
+
+correction : bool, default False
+    correct the stress values for plane stress (Paterson and Olgaard, 2000)
+
+ References
+-----------
+Paterson and Olgaard (2000) https://doi.org/10.1016/S0191-8141(00)00042-0
+de Hoff and Rhines (1968) Quantitative Microscopy. Mcgraw-Hill. New York.
+
+Call functions
+--------------
+piezometers.quartz
+piezometers.olivine
+piezometers.calcite
+piezometers.albite
+
+Assumptions
+-----------
+- Independence of temperature (excepting Shimizu piezometer), total strain,
+flow stress, and water content.
+- Recrystallized grains are equidimensional or close to equidimensional when
+using a single section.
+- The piezometer relations requires entering the grain size as "average"
+apparent grain size values calculated using equivalent circular diameters
+(ECD) with no stereological correction. See documentation for more details.
+- When required, the grain size value will be converted from ECD to linear
+intercept (LI) using a correction factor based on de Hoff and Rhines (1968):
+LI = (correction factor / sqrt(4/pi)) * ECD
+- Stress estimates can be corrected from uniaxial compression (experiments)
+to plane strain (nature) multiplying the paleopiezometer by 2/sqrt(3)
+(Paterson and Olgaard, 2000)
+
+Returns
+-------
+The differential stress in MPa (a float)
+File:      c:\users\marco\documents\github\grainsizetools\grain_size_tools\grainsizetools_script.py
+Type:      function
+
+```
 
-The ``calc_diffstress`` requires three (obligatory) inputs: (1) the average grain size **in microns**, (2) the mineral phase, and (3) the piezometric relation to use. We provide few examples below:
+As indicated in the documentation, the ``calc_diffstress()`` requires three (obligatory) inputs: (1) the average grain size in microns, (2) the mineral phase, and (3) the piezometric relation to use. We provide a few examples below:
 
 ```python
-calc_diffstress(12.0, phase='quartz', piezometer='Twiss')
+calc_diffstress(12, phase='quartz', piezometer='Twiss')
 ```
 
 ```
 ============================================================================
 differential stress = 83.65 MPa
 
 INFO:
-Ensure that you entered the apparent grain size as the arithmeic mean grain size
+Ensure that you entered the apparent grain size as the arithmetic mean grain size
 ECD was converted to linear intercepts using de Hoff and Rhines (1968) correction
-============================================================================
+===========================================================================
 ```
 
-TODO
-
-
+The function returns the differential stress (in MPa) plus some relevant information about the corrections made and the type of average expected. Most piezometric calibrations were calibrated using uniaxial compression deformation experiments while in nature most shear zones approximately behaves as plane stress. Due to this, it may be necessary to correct the differential stress value. The ``calc_diffstress()`` allows you to apply the correction proposed by Paterson and Olgaard (2000) for this as follows (note the slightly different value of differential stress):
 
 ```python
 # Apply the same piezometric relation but correct the estimate for plane stress
-calc_diffstress(12.0, phase='quartz', piezometer='Twiss', correction=True)
+calc_diffstress(12, phase='quartz', piezometer='Twiss', correction=True)
 ```
 
 ```
 ============================================================================
 differential stress = 96.59 MPa
 
 INFO:
-Ensure that you entered the apparent grain size as the arithmeic mean grain size
+Ensure that you entered the apparent grain size as the arithmetic mean grain size
 ECD was converted to linear intercepts using de Hoff and Rhines (1968) correction
 ============================================================================
 ```
 
 Note that the stress estimate is a bit different compare to the value without the correction.
 
+Some paleopiezometers require uncommon averages such as the root mean square or RMS, for example:
+
+```python
+piezometers.quartz('Stipp_Tullis')
+
+(669.0,
+ 0.79,
+ 'Ensure that you entered the apparent grain size as the root mean square (RMS)',
+ False,
+ False)
+```
+
+In this case you should estimate the RMS as  
+$RMS = \sqrt{\dfrac{1}{n} (x_{1}^2 + x_{2}^2 + ... + x_{n}^2)}$
+
+```python
+# Import the example dataset
+filepath = 'C:/Users/marco/Documents/GitHub/GrainSizeTools/grain_size_tools/DATA/data_set.txt'
+dataset = pd.read_csv(filepath, sep='\t')
+dataset['diameters'] = 2 * np.sqrt(dataset['Area'] / np.pi)  # estimate ECD
+
+# estimate the root mean squared
+rms = np.sqrt(np.mean(dataset['diameters']**2))  # note that in Python the exponent operator is ** (as in Fortran) not ^ (as in Matlab)
+
+calc_diffstress(rms, phase='quartz', piezometer='Stipp_Tullis')
+```
+
+```
+============================================================================
+differential stress = 36.79 MPa
 
+INFO:
+Ensure that you entered the apparent grain size as the root mean square (RMS)
+============================================================================
+```
 
-You can pass as input an array of grain size values instead of a scalar value, in this case the function will returns an array of values 
+
+
+## Estimation of the differential stress using arrays of values
+
+Alternatively, you can use (NumPy) arrays as input to estimate several differential stresses at once. In this case, the ``calc_diffstress()`` function will return a NumPy array, so it is generally more useful to store it in a variable as in the example below.
 
 ```python
-ameans = np.array([12.23, 13.71, 12.76, 11.73, 12.69, 10.67])
+ameans = np.array([12.23, 13.71, 12.76, 11.73, 12.69, 10.67])  # a set of average grain size values
 estimates = calc_diffstress(ameans, phase='olivine', piezometer='VanderWal_wet')
 estimates
 ```
@@ -193,12 +305,50 @@ Differential stresses in MPa
 array([167.41, 153.66, 162.16, 172.73, 162.83, 185.45])
 ```
 
-For example, the piezometer relation of Stipp and Tullis (2003) requires entering the grain size as *the root mean square (RMS) using equivalent circular diameters with no stereological correction*, and so on. Table 1 show all the implemented piezometers in GrainSizeTools v3.0+ and the apparent grain size required for each one. Despite some piezometers were originally calibrated using linear intercepts (LI), the script will always require entering a specific grain size average measured as equivalent circular diameters (ECD). The script will automatically approximate the ECD value to linear intercepts using the De Hoff and Rhines (1968) empirical relation. Also, the script takes into account if the authors originally used a specific correction factor for the grain size. For more details on the piezometers and the assumption made using the command ```help()```  in the console as follows:
+If the set of estimated values belongs to the same structural element (e.g. different areas of the same mylonite or different rocks within the same shear zone), you may want to estimate the average differential stress from all the data. The GrainSizeTools script provides a method named ``conf_interval()`` for this.
 
 ```python
-help(calc_diffstress)
+?conf_interval
+
+Signature: conf_interval(data, confidence=0.95)
+Docstring:
+Estimate the confidence interval using the t-distribution with n-1
+degrees of freedom t(n-1). This is the way to go when sample size is
+small (n < 30) and the standard deviation cannot be estimated accurately.
+For large datasets, the t-distribution approaches the normal distribution.
+
+Parameters
+----------
+data : array-like
+    the dataset
+
+confidence : float between 0 and 1, optional
+    the confidence interval, default = 0.95
+
+Assumptions
+-----------
+the data follows a normal or symmetric distrubution (when sample size
+is large)
+
+call_function(s)
+----------------
+Scipy's t.interval
+
+Returns
+-------
+the arithmetic mean, the error, and the limits of the confidence interval
+File:      c:\users\marco\documents\github\grainsizetools\grain_size_tools\grainsizetools_script.py
+Type:      function
+```
 
-# alternatively in Jupyterlab:
-?calc_diffstress
+```python
+conf_interval(estimates)
+```
+
+```
+Mean = 167.37 ± 11.41
+Confidence set at 95.0 %
+Max / min = 178.79 / 155.96
+Coefficient of variation = ±6.8 %
 ```