Usage

Usage#

Tcplotter can be used either as a function in a Python script or interpreter, or from the command line. The four main Tcplotter functions/command-line tools are:

  • time_vs_temp

  • eu_vs_radius

  • rate_vs_radius_eu

  • rate_vs_age_tc

Brief examples of possible usage for both cases can be found below.

Usage in a Python script or interpreter#

Assuming the base tcplotter directory is your working directory, functions available in Tcplotter can be imported as follows:

from tcplotter import time_vs_temp, eu_vs_radius, rate_vs_radius_eu, rate_vs_age_tc

Once imported, you can use functions as shown below:

eu_versus_radius(save_plot=True)

You can find more information about the function parameters using the help() function:

help(eu_vs_radius)

Command-line usage#

Command-line usage is similar to that for use in a Python script, except that the underscores in the function names have been replaced by hyphens. For example, assuming you are in a terminal in the tcplotter/tcplotter directory, you can type the following to use the eu_vs_radius() function:

./eu-vs-radius --save-plot

To find more information about options available for command-line use you can include the --help or -h flags.

./eu-vs-radius -h

Plotting your own data#

Tcplotter version 0.3.0 and later supports plotting of age data from a file on plots using the eu_vs_radius() function. Details about plotting your own data can be found below.

Age data file format#

Tcplotter expects the age data file you will use to have the following format:

  1. It should be a plain text file with commas separating the values in the file

  2. It should contain 5 columns:

    • The age types (AHe or ZHe)

      • AFT ages can also be listed but are currently ignored

    • The ages in Ma

    • The age uncertainties (standard deviation) in Myrs

    • The eU concentration in parts per million

    • The effective spherical grain radius in micrometers

  3. The text file should include a header in the first row

An example of the file format can be found in the file sample_data.csv in the Tcplotter GitHub repository. The contents of that file are also shown below, for convenience.

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, 147.0, 1.5, 3200.0, 55.0

Notes about the age file#

  • In this example file, the values for the AFT sample on line 3 will not be plotted.

  • Any age without both an eU and radius value will not be plotted.

  • Ages with eU and/or radius values outside the range on the plot will also not be plotted.

How to use your own data file#

To use your own text file you should ensure a copy of it is in the directory where you are running Tcplotter. You can enable reading of your age data file using the age_data_file parameter if using the eu_vs_radius() function, or using the --age-data-file command-line flag if using the eu-vs-radius executable from the command line. Examples of both can be found below.

Reading age data using the eu_vs_radius() function#

eu_vs_radius(age_data_file="sample_data.csv")

Reading age data from the command line#

eu-vs-radius --age-data-file sample_data.csv

Calculating a misfit between measured and predicted ages#

It is also possible to calculate the misfit between measured ages in the age file and those predicted using Tcplotter. The equation used to calculate the misfit is the reduced chi-squared equation given below.

\[ \large \chi^{2} = \frac{1}{N} \sum \frac{(O_{i} - E_{i})^{2}}{\sigma_{i}^{2}} \]

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.

Examples of how to enable the misfit calculation can be found below.

Calculating a misfit using the eu_vs_radius() function#

eu_vs_radius(age_data_file="sample_data.csv", calc_misfit=True)

Calculating a misfit from the command line#

eu-vs-radius --age-data-file sample_data.csv --calc-misfit

Functions reference#

You can also find details about the parameters available to the functions in Tcplotter in the functions reference guide.

Contents