updated docs

docs/_sources/age_calcs.rst.txt

@@ -22,7 +22,7 @@ In cases where present-day [|234U|/|238U|] or [|230Th|/|238U|] values are entere
 
    .. figure:: assets/disequilibrium_tab.png
       :alt: Disequilibrium tab
-      :width: 500
+      :width: 400
 
       Disequilibrium tab of the main window on Mac
 

docs/_sources/age_uncertainties.rst.txt

@@ -1,12 +1,24 @@
 Age uncertainties
 =================
 
+Analytical uncertainties
+-------------------------
+
+Age uncertainties may be calculated using a first-order analytical error propagation approach for all equilibrium U-Pb age calculations. For disequilibrium ages, they are are currently only available for single analysis |206Pb*|, |207Pb*| and |207Pb|-corrected ages. To use this approach, select the ``analytical`` check box on the first tab of the main window.
+
+
 Monte Carlo uncertainties
 --------------------------
 
+Monte Carlo uncertainty calculations can be more accurate than analytical approaches when uncertainties on the input variables (e.g., analytical uncertainties, activity ratios, etc.) are relatively large, and the output age distribution is significantly non-Gaussian. However, Monte Carlo approaches can deliver unreliable results when a large number of trials fail, or when a large number of simulated variables take non-physicial values (e.g., negative simulated activity ratios). To avoid these problems going unnoticed, DQPB performs checks on Monte Carlo data inputs and outputs, and alerts the user of any potential issues (see the section  :ref:`below <mc-checks-label>`).
+
+Monte Carlo age uncertainties are available for all age types. To use this approach, select the ``Monte Carlo`` check box on the first tab of the main window.
+
 Disequilibrium ages calculated with near equilibrium [|234U|/|238U|]\ :sub:`m`\  values
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-When a disequilibrium age is computed using a measured [|234U|/|238U|] activity ratio with an assigned uncertainty that significantly overlaps the radioactive equilibrium value (i.e., ~1.00005), it’s likely that a large number of Monte Carlo trials will fail to return convergent age solutions. This makes the calculated uncertainties unreliable (or at least, difficult to interpret). This may be demonstrated using a synthetic Tera-Wasserburg data set. If we begin by assuming a true age of 1.80 Ma, an initial :math:`[^{234}\mathrm{U}/^{238}\mathrm{U}]` value of 1.5, and an common :math:`[^{207}\mathrm{Pb}/^{206}\mathrm{Pb}]` value of 0.83, the true slope of the discordia line will be -0.0002275. We can generate 5 simulated data points along this line, and perturb them according to assigned measurement uncertainties (ignoring uncertainty correlations here for simplicity). Performing linear regression using the York algorithm, results in a fit with MSWD = 0.89 (see Fig. :numref:`regression-fit`) Note, the exact MSWD obtained here is not important here.
+One case in which Monte Carlo uncertainties can be unreliable is when a disequilibrium age is computed using a measured [|234U|/|238U|] activity ratio with an assigned uncertainty that significantly overlaps radioactive equilibrium. In this case, it’s likely that a large number of Monte Carlo trials will fail to return convergent age solutions and this makes the results unreliable (or at least, difficult to interpret).
+
+This issue may be demonstrated using a synthetic Tera-Wasserburg data set. If we begin by assuming a true age of 1.80 Ma, an initial :math:`[^{234}\mathrm{U}/^{238}\mathrm{U}]` value of 1.5, and an common :math:`[^{207}\mathrm{Pb}/^{206}\mathrm{Pb}]` value of 0.83, the true slope of the discordia line will be -0.0002275. We can generate 5 simulated data points along this line, and perturb them according to assigned measurement uncertainties (ignoring uncertainty correlations here for simplicity). We then perform a linear regression using the York algorithm, i.e., model 1 (see Fig. :numref:`regression-fit`).
 
 .. figure:: assets/mc_reg_1400ka.png
     :name: regression-fit
@@ -16,7 +28,7 @@ When a disequilibrium age is computed using a measured [|234U|/|238U|] activity
 
     Linear regression of simulated data set with a true age = 1.80 Ma and :math:`[^{234}\mathrm{U}/^{238}\mathrm{U}]_{\mathrm{i}}` = 1.5.
 
-The present [|234U|/|238U|] value can be calculated from the known age and initial [|234U|/|238U|] as :math:`[^{234}\mathrm{U}/^{238}\mathrm{U}]_{\mathrm{m}} = 1.0031`. To this value, we may assign an arbitrary (but realistic) measurement uncertainty of 0.0014 (:math:`2\sigma`), and perturb this value according to this assigned uncertainty to simulate a measured value. Performing a Monte Carlo simulation with 10 000 trials using these inputs, gives an age of 1.810 (95% CI) (1.754, 1.878) ka and a :math:`[^{234}\mathrm{U}/^{238}\mathrm{U}]_{\mathrm{i}}` solution of 1.514 (95% CI) (1.343, 1.658). The results of the Monte Carlo simulation are shown in Fig. :numref:`mc-histograms`. Only 1 of the 10,000 trials failed. Such a small number will not affect results, and so we may consider the uncertainties calculated from this simulation to be reliable. 
+The present [|234U|/|238U|] value can be calculated from the known age and initial [|234U|/|238U|], giving :math:`[^{234}\mathrm{U}/^{238}\mathrm{U}]_{\mathrm{m}} = 1.0031`. To this value, we may assign an arbitrary (but realistic) measurement uncertainty of 0.0014 (:math:`2\sigma`). Performing a Monte Carlo simulation with 10 000 trials using these inputs, gives an age of 1.810 (95% CI) (1.754, 1.878) ka and a :math:`[^{234}\mathrm{U}/^{238}\mathrm{U}]_{\mathrm{i}}` solution of 1.514 (95% CI) (1.343, 1.658). The results of the Monte Carlo simulation are shown in Fig. :numref:`mc-histograms`. Only 1 of the 10,000 trials failed. Such a small number will not affect results, and so we may consider the uncertainties calculated from this simulation to be reliable.
 
 .. figure:: assets/mc_hist_1400ka.png
     :name: mc-histograms
@@ -26,7 +38,7 @@ The present [|234U|/|238U|] value can be calculated from the known age and initi
 
     Monte Carlo simulation results for simulated data set with true age = 1.800 Ma and measured :math:`[^{234}\mathrm{U}/^{238}\mathrm{U}] = 1.0031 \pm 0.0014 (2\sigma)`. Red bars indicate values for all trials, and blue bars indicate values for successful trials only. Note that the blue bars overlay the red bars, which are not visible in this plot because virtually all Monte Carlo trials were successful.
 
-We can repeat this simulation using a true age of 2.4 Ma, but keeping the initial [|234U|/|238U|] and common [|207Pb|/|206Pb|] values the same. This yields a measured [|234U|/|238U|] value of :math:`1.00057 \pm 0.0014 (2\sigma)`, which now overlaps the radioactive equilibrium value significantly. If we repeat the data point simulation and re-fit the linear regression (for the slope corresponding to 2.40 Ma), we obtain a model 1 fit with MSWD = 0.99 (see Fig. :numref:`regression-fit-two`). Again the exact MSWD value obtained here is not important.
+We can repeat this simulation using a true age of 2.4 Ma, but keeping the initial [|234U|/|238U|] and common [|207Pb|/|206Pb|] values the same. This yields a measured [|234U|/|238U|] value of :math:`1.00057 \pm 0.0014 (2\sigma)`, which overlaps the radioactive equilibrium value significantly. We now repeat the data point simulation and re-fit the linear regression for the slope corresponding to 2.40 Ma (see Fig. :numref:`regression-fit-two`).
 
 .. figure:: assets/mc_reg_2400ka.png
     :name: regression-fit-two
@@ -47,10 +59,10 @@ Performing 10,000 Monte Carlo trials with these new inputs, gives an age of 2.39
     Monte Carlo simulation results for simulated data set with true age = 2.0 Ma and measured :math:`[^{234}\mathrm{U}/^{238}\mathrm{U}] = 1.00057 \pm 0.0014 (2\sigma)`. Again, red bars indicate values for all trials, and blue bars indicate values for successful trials only. Note that the blue bars overlay the red bars.
 
 
-This time 1198 of the 10 000 trials failed. This is a significant number, which may bias uncertainties calculated from this simulation. Note that these “failed” trials were not rejected by the algorithm because they returned a negative initial [|234U|/|238U|] value, but rather because there was no convergent age solution available (i.e., the simulated discordia line did not intercept the simulated concordia curve). This can be demonstrated by plotting the concordia curves for the failed trials as Fig. :numref:`concordia-intercept`.
+This time 1198 of the 10 000 trials failed. This is a significant number, which may bias uncertainties calculated from this simulation. Note that these “failed” trials were not rejected by the algorithm because they returned a negative initial [|234U|/|238U|] value, but rather because there was no convergent age solution available (i.e., the simulated discordia line did not intercept the simulated concordia curve). This can be demonstrated by plotting the concordia curves for the failed trials as :numref:`concordia-intercept-2`.
 
 .. figure:: assets/mc_conc_2400ka.png
-    :name: concordia-intercept
+    :name: concordia-intercept-2
     :width: 360
     :align: center
     :alt: Concordia intercept for failed trials of 2.40 Ma simulation.
@@ -67,15 +79,36 @@ To confirm that simulated regression lines do not intercept the corresponding co
 
     The same plot as above, but zoomed in. Simulated concordia curves and regression lines for the first 10 failed trials that enter this zoomed in part of the plot are shown. The concordia curves are truncated where age and :math:`[^{234}\mathrm{U}/^{238}\mathrm{U}]_{\mathrm{m}}` returns a physically impossible negative :math:`[^{234}\mathrm{U}/^{238}\mathrm{U}]_{\mathrm{i}}` value. Note that regression lines do not intercept the corresponding concordia curve for these trials (indicated by the concordia curve of the same colour).
 
-To address this problem, DQPB implements two checks when calculating Monte Carlo uncertainties. 
+.. _mc-checks-label:
+
+Monte Carlo quality control checks
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+To alert users of potential problems with Monte Carlo simulations, DQPB implements two checks when calculating Monte Carlo uncertainties.
 
-1. Measured activity ratio values are checked before age calculation to ensure that they are analytically resolvable from radioactive equilibrium with 95% confidence. Where this criterion is not met, a warning is displayed, and the Monte Carlo simulation does not proceed. The age is still reported, but the uncertainties are listed as 'undef.' (i.e., undefined). 
+1. Measured activity ratio values are checked before age calculation to ensure that they are analytically resolvable from radioactive equilibrium with 95% confidence. Where this criterion is not met, a warning is displayed (:numref:`mc-diseq-error`), and the Monte Carlo simulation does not proceed. The age is still reported, but the uncertainties are listed as 'undef.' (i.e., undefined).
+
+.. figure:: assets/diseq_not_resolvable.png
+    :name: mc-diseq-error
+    :width: 500
+    :align: center
+    :alt: Monte Carlo disequilibrium not resolvable error dialog
+
+    Measured activity ratio not resolvable warning
+
+2. After a Monte Carlo simulation is completed, as second check is performed to verify that a minimum proprtion of trials were successful (the default value is set to 97.5%). Where this second criterion is not met, the software displays a warning that Monte Carlo simulation results may be biased by excessive failed trials and should not be used (:numref:`mc-trials-warning`). This second warning may also be triggered if the PDF of an initial activity ratio value significantly overlaps negative values (e.g., if the value of an initial activity ratio significantly overlaps zero within its uncertainty).
+
+.. figure:: assets/mc_trials_warning.png
+    :name: mc-trials-warning
+    :width: 500
+    :align: center
+    :alt: Monte Carlo disequilibrium not resolvable error dialog
 
-2. After a Monte Carlo simulation is completed, as second check is performed to verify that a minimum proprtion of trials were successful (the default value is set to 97.5%). Where this second criterion is not met, the software displays a warning that Monte Carlo simulation results may be biased by excessive failed trials and should not be used. This second warning may also be triggered if the PDF of an initial activity ratio value significantly overlaps negative values (e.g., if the value of an initial activity ratio significantly overlaps zero within its uncertainty).
+    Monte Carlo failed trials error dialog
 
 
 Isochron ages calculated with near equilibrium [|234U|/|238U|]\ :sub:`m`\  values
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-The same issue may be encountered when computing |206Pb|/|238U| isochron ages using measured [|234U|/|238U|] activity ratios that are not clearly analytically resolvable from radioactive equilibrium, although this is not as easy to demonstrate graphically. Therefore, the same checks as described above are performed here too.
+The same issue may be encountered when computing |206Pb|/|238U| isochron ages using measured [|234U|/|238U|] activity ratios that are not clearly analytically resolvable from radioactive equilibrium, although this is not as easy to demonstrate graphically. Therefore, measured activity ratio values are checked before age calculation to ensure that they are analytically resolvable from radioactive equilibrium with 95% confidence here too.
 

docs/_sources/references.rst.txt

@@ -47,10 +47,6 @@ References
     Worked Examples and a Computer Program, Journal of Metamorphic Geology, 6,
     173–204, https://doi.org/10.1111/j.1525-1314.1988.tb00415.x, 1988.
 
-.. [SAKATA2018] A practical method for calculating the U-Pb age of Quaternary
-    zircon: Correction for common Pb and initial disequilibria. Geochemical
-    Journal 52, 281–286. https://doi.org/10.2343/geochemj.2.0508
-
 .. [TAYLOR1997] Taylor, J., 1997. Introduction to Error Analysis, the Study of
     Uncertainties in Physical Measurements, 2nd Edition, Published by
     University Science Books. University Science Books, New York.

docs/_sources/usage.rst.txt

@@ -21,7 +21,7 @@ All tasks are invoked via the main window, which is displayed when the applicati
 
 
    .. figure:: assets/data_selection.png
-      :width: 550
+      :width: 700
       :align: center
       :alt: Data selection example screenshot
 
@@ -49,7 +49,7 @@ All tasks are invoked via the main window, which is displayed when the applicati
 #. When the task is complete, results and figures (in .jpg format) will be printed back to the Excel worksheet.
 
    .. figure:: assets/progress_bar.png
-      :width: 550
+      :width: 700
       :align: center
       :alt: Progress bar screenshot