Add support for reading age data file, plotting measured ages, calculating misfits

README.md

@@ -1,7 +1,8 @@
 # T<sub>c</sub>plotter code description and instructions for use
 
 [![Binder](https://mybinder.org/badge_logo.svg)](https://mybinder.org/v2/gh/HUGG/tcplotter/HEAD?urlpath=lab/tree/tcplotter.ipynb)
-[![Documentation Status](https://readthedocs.org/projects/tcplotter/badge/?version=latest)](https://tcplotter.readthedocs.io/en/latest/?badge=latest) 
+[![Documentation Status](https://readthedocs.org/projects/tcplotter/badge/?version=latest)](https://tcplotter.readthedocs.io/en/latest/?badge=latest)
+[![Anaconda-Server Badge](https://anaconda.org/conda-forge/tcplotter/badges/version.svg)](https://anaconda.org/conda-forge/tcplotter)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 [![DOI](https://zenodo.org/badge/444915688.svg)](https://zenodo.org/badge/latestdoi/444915688)
 
@@ -78,9 +79,7 @@ When including plots generated using T<sub>c</sub>plotter in publications or pre
 
 You're also welcome to cite the manuscript related to T<sub>c</sub>plotter when referencing ideas from the article:
 
-- Whipp, D., Kellett, D., and Coutand, I.: Short communication: Modelling competing effects of cooling rate, grain size and radiation damage in low temperature thermochronometers, Geochronology Discuss. [preprint], <https://doi.org/10.5194/gchron-2021-29>, in review, 2021. 
-
-*Please note that this is the pre-print reference and it is preferable to cite the final article once available*.
+- Whipp, D. M., Kellett, D. A., Coutand, I., and Ketcham, R. A.: Short communication: Modeling competing effects of cooling rate, grain size, and radiation damage in low-temperature thermochronometers, *Geochronology*, *4*, 143–152, <https://doi.org/10.5194/gchron-4-143-2022>, 2022. 
 
 ### How to cite related articles
 
@@ -92,4 +91,4 @@ The age prediction software used for calculating apatite and zircon (U-Th)/He an
 
 ## License
 
-The T<sub>c</sub>plotter software is licensed under an MIT License: [T<sub>c</sub>plotter software license](LICENSE)
+The T<sub>c</sub>plotter software is licensed under an MIT License: [T<sub>c</sub>plotter software license](LICENSE)

sample_data.csv

@@ -0,0 +1,9 @@
+Age type, Age (Ma), Standard deviation (Ma), eU concentration (ppm), Grain radius (um)
+AHe, 45.0, 0.5, 40.0, 60.0
+AFT, 10.0, 1.5, ,
+ZHe, 158.0, 1.5, 900.0, 60.0
+ahe, 73.0, 1.0, 120.0, 90.0
+ZHe, 173.0, 1.5, 2000.0, 80.0
+ZHe, 175.0, 1.5, 3000.0, 120.0
+aHe, 58.0, 0.9, 200.0, 70.0
+ZHe, 147.0, 1.5, 3200.0, 55.0

tcplotter.ipynb

@@ -7,7 +7,7 @@
    "source": [
     "# T<sub>c</sub>plotter: Thermochronology age and closure temperature plotters\n",
     "\n",
-    "This is a Jupyter notebook, an interactive web application, that can be used to reproduce and modify the plots from the Geochronology article \"[Modelling competing effects of cooling rate, grain size and radiation damage in low temperature thermochronometers](https://gchron.copernicus.org/preprints/gchron-2021-29/)\" by Whipp/Kellett and Coutand. Below you will find some general information about the software, instructions about how to produce and save copies of the plots, lists of options each of the plot types, and a list of common questions.\n",
+    "This is a Jupyter notebook, an interactive web application, that can be used to reproduce and modify the plots from the Geochronology article \"[Modelling competing effects of cooling rate, grain size and radiation damage in low temperature thermochronometers](https://doi.org/10.5194/gchron-4-143-2022)\" by Whipp/Kellett, Coutand, and Ketcham. Below you will find some general information about the software, instructions about how to produce and save copies of the plots, lists of options each of the plot types, and a list of common questions.\n",
     "\n",
     "## Links for the impatient\n",
     "\n",
@@ -16,6 +16,7 @@
     "    - [Preparing to plot (**must run this first before making any plots**)](#Preparing-to-plot)\n",
     "    - [Time-temperature history (manuscript Figure 1)](#Figure-1---A-time-temperature-cooling-history)\n",
     "    - [Ages and closure temperatures for different eU and grain radii (Figures 2 and 3)](#Figures-2-and-3---Ages-and-closure-temperatures-for-different-eU-and-grain-radii)\n",
+    "        - [Plotting your own data](#Plotting-age-data-on-the-figures)\n",
     "    - [Closure temperatures for different cooling rates, grain radii, and eU (manuscript Figure 4)](#Figure-4---Closure-temperatures-as-a-function-of-cooling-rate,-grain-radius,-and-eU)\n",
     "    - [Ages and closure temperatures for different cooling rates and eU (manuscript Figure 5)](#Figure-5---Ages-and-closure-temperatures-for-different-cooling-rates-and-eU)\n",
     "- [Frequently asked questions](#Frequently-asked-questions)\n",
@@ -24,7 +25,7 @@
     "\n",
     "If you use plots produced by this software, please cite the following article:\n",
     "\n",
-    "- Whipp, D. M., Kellett, D. A., Coutand, I, & Ketcham, R. A. (in revision). Modelling competing effects of cooling rate, grain size and radiation damage in low temperature thermochronometers. *Geochronology*, doi: [10.5194/gchron-2021-29](https://doi.org/10.5194/gchron-2021-29).\n",
+    "- Whipp, D. M., Kellett, D. A., Coutand, I, & Ketcham, R. A. Modelling competing effects of cooling rate, grain size and radiation damage in low temperature thermochronometers. *Geochronology*, doi: [10.5194/gchron-4-143-2022](https://doi.org/10.5194/gchron-4-143-2022).\n",
     "\n",
     "The age prediction software used for calculating apatite and zircon (U-Th)/He and apatite fission-track ages was written by Richard Ketcham at the University of Texas, USA. Results published using this software should cite the articles below:\n",
     "\n",
@@ -56,7 +57,9 @@
    "cell_type": "code",
    "execution_count": null,
    "id": "10e5fb7e-9a58-4d4e-ab5e-8be32f0835d3",
-   "metadata": {},
+   "metadata": {
+    "tags": []
+   },
    "outputs": [],
    "source": [
     "print(f\"The sum of 11111 plus 1234 is {11111 + 1234}.\")"
@@ -106,7 +109,9 @@
    "cell_type": "code",
    "execution_count": null,
    "id": "7d59d96c-f123-4f69-a622-87c40e89bbe1",
-   "metadata": {},
+   "metadata": {
+    "tags": []
+   },
    "outputs": [],
    "source": [
     "# Load plotting functions\n",
@@ -155,7 +160,9 @@
    "cell_type": "code",
    "execution_count": null,
    "id": "38ead04f-9cae-4a4b-aa62-c72e6dd00464",
-   "metadata": {},
+   "metadata": {
+    "tags": []
+   },
    "outputs": [],
    "source": [
     "# Create customized version of Figure 1 (feel free to edit this cell)\n",
@@ -188,7 +195,9 @@
    "cell_type": "code",
    "execution_count": null,
    "id": "e565f916-c5e7-4064-9c8d-6ebe12dfeda1",
-   "metadata": {},
+   "metadata": {
+    "tags": []
+   },
    "outputs": [],
    "source": [
     "# Display documentation for time_vs_temp function\n",
@@ -232,6 +241,7 @@
     "- You can also find details about the plotting options in the [plotting options for Figures 2 and 3](https://tcplotter.readthedocs.io/en/latest/reference.html#eu-vs-radius)\n",
     "- These examples include a graphical progress bar enabled with the `use_widget` option\n",
     "- Figure 3 is the same as Figure 2 with a slower cooling rate, so the `rate` option must be specified and equal to `1.0` to produce Figure 3 (as it is in the example plot)\n",
+    "- **New in tcplotter 0.3.0**: Measured ages can be read from a file for plotting and calculation of a misfit between the model predictions and measured ages\n",
     "\n",
     "### Figure 2"
    ]
@@ -310,6 +320,91 @@
     "eu_vs_radius(use_widget=True, cooling_rate=1.0, tt_plot=True)"
    ]
   },
+  {
+   "cell_type": "markdown",
+   "id": "4fb50a4c",
+   "metadata": {},
+   "source": [
+    "### Plotting age data on the figures\n",
+    "\n",
+    "T<sub>c</sub>plotter version 0.3.0 and later supports plotting of age data from a file on plots like Figures 2 and 3. In order to plot the data you will need to do a few additional steps prior to creating the plots. These steps are given below.\n",
+    "\n",
+    "#### Age data file format\n",
+    "\n",
+    "T<sub>c</sub>plotter expects the age data file you will use to have the following format:\n",
+    "\n",
+    "1. It should be a plain text file with commas separating the values in the file\n",
+    "2. It should contain 5 columns:\n",
+    "    - The age types (AHe or ZHe)\n",
+    "        - AFT ages can also be listed but are currently ignored\n",
+    "    - The ages in Ma\n",
+    "    - The age uncertainties (standard deviation) in Myrs\n",
+    "    - The eU concentration in parts per million\n",
+    "    - The effective spherical grain radius in micrometers\n",
+    "3. The text file should include a header in the first row\n",
+    "\n",
+    "An example of the file format can be found in the file [`sample_data.csv`](sample_data.csv). The contents of that file are also shown below, for convenience.\n",
+    "\n",
+    "```\n",
+    "Age type, Age (Ma), Standard deviation (Ma), eU concentration (ppm), Grain radius (um)\n",
+    "AHe, 45.0, 0.5, 40.0, 60.0\n",
+    "AFT, 10.0, 1.5, ,\n",
+    "ZHe, 158.0, 1.5, 900.0, 60.0\n",
+    "ahe, 73.0, 1.0, 120.0, 90.0\n",
+    "ZHe, 173.0, 1.5, 2000.0, 80.0\n",
+    "ZHe, 175.0, 1.5, 3000.0, 120.0\n",
+    "aHe, 58.0, 0.9, 200.0, 70.0\n",
+    "ZHe, 147.0, 1.5, 3200.0, 550.0\n",
+    "```\n",
+    "\n",
+    "**Notes about the age file**:\n",
+    "\n",
+    "- In this example file, the values for the AFT sample on line 3 will not be plotted.\n",
+    "- Any age without both an eU and radius value will not be plotted.\n",
+    "- Ages with eU and/or radius values outside the range on the plot will also not be plotted.\n",
+    "\n",
+    "#### How to use your own data file\n",
+    "\n",
+    "You have a few options for how to provide your own data for plotting.\n",
+    "\n",
+    "##### Option 1: Modifying the existing sample_data.csv file\n",
+    "\n",
+    "This is probably the easiest option. You can simply right click on the `sample_data.csv` file, select **Open With**, and the select **Editor**. This will open the file in the text file editor in Jupyter Lab and you can edit the file as you like. Save your changes and you should be all set.\n",
+    "\n",
+    "##### Option 2: Uploading a file with sample data\n",
+    "\n",
+    "To use your own text file, you can click on the **Upload Files** icon (upward pointing arrow with a line beneath the arrow) at the top of the Jupyter Lab file browser on the left side of the window. You can then select the file you would like to upload.\n",
+    "\n",
+    "#### An example plot\n",
+    "\n",
+    "Below you can find an example of how to use the parameters `age_data_file` and `calc_misfit` to read/plot age data and calculate a misfit. Note that if you have uploaded your own age data file, then you should change the name of the file listed in quotes for the `age_data_file` parameter.\n",
+    "\n",
+    "The equation used to calculate the misfit is the reduced chi-squared equation given below.\n",
+    "\n",
+    "$$\n",
+    "\\large\n",
+    "\\chi^{2} = \\frac{1}{N} \\sum \\frac{(O_{i} - E_{i})^{2}}{\\sigma_{i}^{2}}\n",
+    "$$\n",
+    "\n",
+    "where $N$ is the number of ages, $O_{i}$ is the $i$th observed/measured age, $E_{i}$ is the $i$th estimated/predicted age, and $\\sigma_{i}$ is the standard deviation (uncertainty) for the $i$th observed/measured age."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "660f5684",
+   "metadata": {
+    "collapsed": false,
+    "jupyter": {
+     "outputs_hidden": false
+    }
+   },
+   "outputs": [],
+   "source": [
+    "# Create customized version of Figure 3 (feel free to edit this cell)\n",
+    "eu_vs_radius(use_widget=True, cooling_rate=1.0, plot_type=3, age_data_file=\"sample_data.csv\", calc_misfit=True)"
+   ]
+  },
   {
    "cell_type": "markdown",
    "id": "1a5844e4-e1ac-41f0-af33-1e516821bcc2",
@@ -451,7 +546,7 @@
    "name": "python",
    "nbconvert_exporter": "python",
    "pygments_lexer": "ipython3",
-   "version": "3.8.12"
+   "version": "3.10.9"
   }
  },
  "nbformat": 4,

tcplotter/eu_vs_radius.py

@@ -199,6 +199,20 @@ def main():
         default=256,
         type=int,
     )
+    parser.add_argument(
+        "--age-data-file",
+        dest="age_data_file",
+        help="Filename for file containing measured thermochronometer ages",
+        default="",
+        type=str,
+    )
+    parser.add_argument(
+        "--calc-misfit",
+        dest="calc_misfit",
+        help="Flag for whether a misfit should be calculated for measured and predicted ages",
+        action="store_true",
+        default=False,
+    )
     parser.add_argument(
         "--no-display-plot",
         dest="no_display_plot",
@@ -253,6 +267,8 @@ def main():
         plot_alpha=args.plot_alpha,
         plot_contour_lines=args.plot_contour_lines,
         plot_contour_fills=args.plot_contour_fills,
+        age_data_file=args.age_data_file,
+        calc_misfit=args.calc_misfit,
         display_plot=display_plot,
         tt_plot=args.tt_plot,
         verbose=args.verbose,