2.A. Input format for sample/measurement data.
Like the 2008 online calculators up to version 2.3, version 3 accepts plain-text input with a specific defined format. Because version 3 can do computations for a variety of nuclide-mineral pairs besides just 10Be and 26Al in quartz, the input format has to be different from the version 2 input format. The version 3 input format is described at this page:
http://hess.ess.washington.edu/math/docs/v3/v3_input_explained.html
The main difference between the version 2 and version 3 input format is that the version 3 input format has some characteristics of a relational database in that it defines different types of text lines for sample information, independent age information, and nuclide concentration measurements, so that information about multiple measurements on the same sample can be entered without redundantly entering information about the sample.
An additional difference between version 2 and version 3 input is that version 3 input requires entering a date of sample collection. Technically, the reason for this is that magnetic field reconstructions used in time-dependent production rate scaling methods are indexed to specific calendar years, so it is necessary to correctly line these up with the period during which exposure took place. In nearly all cases, the exposure age is not significantly affected by whether the date of sample collection is known accurately or not. Thus, the input format includes the option to use a default value. See the input format explanation at the link above.
At present, the version 3 exposure age calculation input page will also accept version 2 input. However, the production rate calibration page requires version 3 input and will not accept input formatted for the version 2 production rate calibration page. You should not probably not expect version 2 input to continue to be valid indefinitely into the future.
Examples of version 3 input (for both exposure-age calculations and production rate calibration) are available at http://www.ice-d.org.
The version 3 input format also supports 36Cl calculations in which production rates are compositionally dependent. This requires adding additional input lines for major and trace element composition of whole rock and target fractions. This should be mostly documented in the format spec linked above.
Another difference from the version 2 input page is that there now exists a checkbox on the exposure age input page to identify all the samples in the input data set as being from the same landform. What 'being from the same landform' means in this sense is that the geological context of the samples indicates that all the samples were emplaced at the same time, and the purpose of measuring the exposure ages is to determine when the landform was emplaced. The typical example where this is true would be a set of boulder exposure ages from a single moraine. Checking this box triggers calculation of summary statistics on the resulting set of exposure ages, including outlier screening, tests for belonging to a single population, and averaging. Of course, if you enter data with multiple age populations, or data sets that are badly behaved in certain other ways, this calculation will not be meaningful and will most likely generate nonsense results.
2.B. Web interface output.
2.B.1. Exposure-age results.
This should be reasonably self-explanatory. The server returns a web page that includes, for each nuclide/mineral pair in each sample, the exposure age, internal uncertainty, and external uncertainty for each available production rate scaling method. As in version 2, the internal uncertainties consider measurement uncertainties on the nuclide concentration only, and the external uncertainties include both measurement uncertainty and production rate uncertainty.
The output page reports version information for various components of the code, which is helpful in determining whether any difference between exposure ages computed at different times from the same data is the result of updates and/or bug fixes.
It also reports the production rate calibration data set used for the exposure-age calculations. Normally this will be the default data set, unless you have entered non-default data. In the latter case the calibration data set name will be whatever you originally entered in the calibration data input page.
Finally, there may be some diagnostic information reported if something unusual happens in the calculations. The most common such situation occurs when a measured nuclide concentration is greater than production-erosion-decay saturation for the location and erosion rate entered for the sample. If above-saturation warnings occur unexpectedly (i.e., for a nuclide concentration that you know is nowhere near saturation), the most common explanation is an error in entering the surface erosion rate. Check that first.
36Cl calculation results include some additional diagnostic information. The small minority of people who care about this can probably figure it out for themselves.
It is possible to make some errors in the input formatting that are not caught by the data ingestion code and will cause the rest of the code to crash and return nothing. The most common one of these at present is trying to use the production rate calibration page with either (i) no independent age data lines, or (ii) maximum and minimum ages that are somehow undefined or incompatible (like, entering only minimum ages).
2.B.1.a. Exposure age vs. calendar year age.
The output of the exposure-age calculation is an exposure age, not a calendar year age. The exposure age of a sample is the number of years that the sample was exposed prior to sampling. This is different from a specific calendar year date such as one would typically calculate from a radiocarbon measurement. To reiterate, an exposure age generated by this code is not a calendar age in years AD/BC, years before 1950, or years before 2000. It is a duration of exposure.
This differs from some other online exposure age calculators, which report a calendar year date on which exposure of the sample began.
An implication of this discussion is that if it is an exposure age and not a calendar date that is being computed, one may wonder why it's necessary to enter the date of sample collection. As discussed above, the reason is that paleomagnetic field reconstructions are indexed to specific calendar years, so when using a time-dependent scaling method it's necessary to correctly line up the exposure period of the sample with the magnetic field reconstruction. Although this does create the technical requirement that one know the date of sample collection, as a practical matter it is usually not necessary to know this any more precisely than the nearest decade or even century, except in the rare case of extremely short exposure durations less than ca. 100 years.
A potential source of confusion in this area is that independent age input for calibration data (again, see the input format definition page) is defined to be in calendar years before 1950. The reason for this is that the independent ages for most production rate calibration sites derive from calibrated radiocarbon ages. Thus, suppose that you enter the following data into the production rate calibration page:
06-NE-001-HOL 42.30387 -72.53188 304 std 1.0 2.65 1.0000 0.00e+00 2006;
06-NE-001-HOL true_t HOLYR 16795 320;
06-NE-001-HOL Be-10 quartz 9.557e+04 4.382e+03 07KNSTD;
Here the sample was collected in 2006 and the independent age of the site has been specified as 16795 years before 1950. If you then paste in the same data and compute the exposure age of this sample with this production rate calibration, the calculated exposure age will be 16852 years. Why isn't this the same as the independent age used for the calibration? Because the independent age used for calibration is in calendar years before 1950, and the resulting exposure age is a duration of exposure ending in 2006. So the exposure age of the sample is 16795 + (2006 - 1950) = 16851. OK, there is 1 year of numerical imprecision there (remember, target precision is a couple of per mil), but you get the idea.
2.B.2. Production rate calibration results.
Submitting the production rate calibration input page returns a page that looks very much like the exposure-age calculation input page, but differs in that (i) it contains a lot of information about the results of the production rate calibration generated from the data that you entered, and (ii) if you enter unknown-age data and submit it, the exposure ages will be calculated using your production rate calibration data and not the default data set.
First there is a block of data that: (i) returns the name you gave the calibration data set; (ii) reminds you which nuclide you entered calibration data for; (iii) reminds you that you can only calibrate the production rate for one nuclide at a time, and if you enter unknown-age data for other nuclides, the default calibration data sets will be used; and (iv) reports some statistics about how well the various scaling methods fit the calibration data you entered.
How the averages and fits are calculated are described in detail in the 'ancillary calculations' section. In brief, these numbers are:
1. The best-estimate value of the one parameter that is being estimated. For St and Lm scaling, this has units of atoms/g/yr and can be interpreted as a best-fitting reference production rate at sea level and high latitude. For LSDn scaling, this is a nondimensional factor that is applied to production rates calculated directly by the LSDn method. The reason it is done this way here, as described in more detail elsewhere, is that because of the nature of the LSDn method, defining a reference-state production rate in the usual units is redundant and time-consuming, so I don't do it. Note, as always, that the best-fitting reference production rates for St and Lm scaling are also not comparable to similar values generated by other code. If you publish the results of calculations that use this production rate calibration, you should not report these numbers, but instead should report what production rate calibration data set you used.
2. 'Uncertainty by total scatter' and corresponding chi-squared. Absolute and relative (e.g., units of percent) uncertainties derived from the standard deviation of the reference production rates (or nondimensional correction factors) computed from all the individual measurements, and their chi-squared with respect to the best-estimate value above. If you only enter data from one site, the production rate uncertainty used in downstream exposure-age calculations is derived from this scatter metric.
3. 'Uncertainty by site-to-site scatter' and corresponding chi-squared. Absolute and relative uncertainties derived from the standard deviation of the best estimates from each calibration site, and corresponding chi-squared with respect to the overall best-estimate value. Theoretically, this should be a good estimate of the scaling (as opposed to measurement) uncertainty. If you enter data from multiple sites, in most cases the production rate uncertainty used in the downstream exposure-age calculations will be derived from this scatter metric. There is more information about this on the 'ancillary calculations' page.
Then there is a plot showing the scatter of production rates (or, for LSDn scaling, the equivalent nondimensional factor) computed from individual measurements around the best estimate. Note that this could be improved by also distinguishing among data from different sites, but, obviously, that is not the case at present. The y-axis is elevation simply because elevation accounts for most of the variation in production rates, so poor scaling performance is most likely to be evidenced by a systematic trend in this space. In addition, plotting against elevation generally spreads out the data nicely. As always, there are links to GMT code to make the plot as well as a Postscript version of the plot.
2.C. Web service API.
The above sections describe interacting with the exposure age server using a web browser to manually enter input data and view a web page that shows the results of calculations. It is also possible to compute exposure ages programmatically using a web service API that responds to an HTTP "POST" request with an XML object containing the results of the calculations.
This is not well described here. It is described somewhere in the ICE-D wiki.
URL for web service
The http request can have the following fields:
mlmfile = "age_input_v3"
reportType = "HTML" or "XML"
resultType = "long" or "short"
plotFlag = "yes" or "no"
summary = ??
text_block
Example of an http request
Example of an XML result
XML output fields details
Example use in MATLAB
Example use in Python
2.D. Use in ICE-D databases.
The version 3 code is the back end for the ICE-D databases. Uses the web service API.
See the ICE-D wiki.