deltar (version 1.0.0)

dr_df: Compute Delta R values for a set of dates

Description

Computes Delta R values for a set of dates in a data frame either with dr_shell() or dr_pair() function. Multiple radiocarbon dates of marine samples with known collection dates or true ages identified in other ways can be downloaded as a data frame and Delta R for each column of the latter is computed

Usage

dr_df(df, N = 10000, CI = 0.95, method = "pair",
                       calCurves = "intcal13", make.plot = FALSE)

Arguments

df

A data frame. Its first column indicates a type of dates constituting each sample or pair. If Delta R is computed for dates amalgamated in pairs, each pair is stored in its own column. The order of rows is essential: first, terrestrial (or uranium-thorium) date of a pair, then its standard deviation, then marine radiocarbon date, and its standard deviation (see "adak" and "coral" datasets as examples). If Delta R is computed for marine samples with known collection date, each sample is stored in its own column. The order of rows is essential: first, the collection date (in calendar years AD/BC), then radiocarbon date of a sample and its standard deviation (see "BSea" dataset as an example). Column names are further used as identification codes.

N

Number of iterations. Must be a positive integer. Note that numbers too big can result in very long computation times. Default is 10000.

CI

Probability with which true Delta R value is contained within computed interval. Must be between 0 and 1. Default is 0.95.

method

A character vector. If Delta R is computed for dates amalgamated in pairs, "pair" should be supplied to this argument. If Delta R is computed for marine samples with known collection date, "shell" should be supplied to this argument.

calCurves

A character vector to determine whether to calibrate the first date of a pair or not. If the first date is terrestrial radiocarbon date, it should be calibrated with "intcal13" calibration curve (or "shcal13" for Southern Hemisphere, see Reimer et al, 2013 and Hogg et al, 2013 for calibration curves details) and the same curve has to be supplied to the calCurves argument. If it is uranium-thorium date, calibration is not needed and "normal" curve, which treats ages as normally distributed with given standard deviation, should be passed to calCurves. Default is "intcal13".

make.plot

A logical flag. Makes histograms of the Delta R values for each sample or pair if TRUE.

Value

If the make.plot argument is set to TRUE, the function produces histograms of Delta R values obtained during each iteration. Histogram of each sample or a pair is produced in its own window. Regardless of the make.plot argument settings, function returns a list containing:

• statistics <U+2014> a data frame. Basic statistics computed for pairs or samples supplied to the function are the following: mean (mean Delta R value), median (median Delta R value), sd (standard deviation of Delta R value), low.lim and up.lim (the lower and upper limits of an interval containing true Delta R value with a probability set by the CI argument), p.value (p value of the Kolmogorov <U+2013> Smirnov test of normality of computed Delta R values). These statistics are organized as columns, while pairs or samples supplied to the function are organized as rows.

• deltaR <U+2014> a data frame. For each pair or a sample supplied to the function a numeric vector of length N containing a series of assessments of Delta R values obtained during each iteration is created. All of them are combined in this data frame with an identification code of a pair or a sample as a column name.

Details

The function computes Delta R values for each column of the data frame according to the chosen method. See details of dr_pair() and dr_shell() functions. See examples of data frame format in "adak" and "coral" data sets for method "pair" and in "BSea" data set for method "shell". The output of this function can be supplied to the dr_plot() function for plotting Delta R values. If the make.plot argument is set to TRUE, the function produces histograms of Delta R values for each sample or a pair. The histograms have a total area of one and are supplemented with curves of probability densities of the corresponding normal distributions.

References

Hogg AG, Hua Q, Blackwell PG, Niu M, Buck CE, Guilderson TP, Heaton TJ, Palmer JG, Reimer PJ, Ron W, Turney CSM, Zimmerman SR. 2013. SHCal13 Southern Hemisphere calibration, 0<U+2013>50,000 cal yr BP. Radiocarbon. 55 (4): 1889-1903. <10.2458/azu_js_rc.55.16783> Reimer PJ, Bard E, Bayliss A, Beck JW, Blackwell PG, Bronk Ramsey C, Buck CE, Cheng H, Edwards RL, Friedrich M, Grootes PM, Guilderson TP, Haflidason H, Hajdas I, Hatt<U+00E9> C, Heaton TJ, Hoffmann DL, Hogg AG, Hughen KA, Kaiser KF, Kromer B, Manning SW, Niu M, Reimer RW, Richards DA, Scott EM, Southon JR, Staff RA, Turney CSM, van der Plicht J. 2013. IntCal13 and Marine13 radiocarbon age calibration curves 0<U+2013>50,000 years cal BP. Radiocarbon 55(4): 1869<U+2013>87. <10.2458/azu_js_rc.55.16947>

See Also

dr_shell dr_pair dr_plot

Examples

# NOT RUN {
#' # Acquire "BSea" data set
data(BSea)
# Compute Delta R values and store them in the new object
# Note, that samples with known collection date need "shell" method
bsea_res <- dr_df(BSea, method = "shell")
# See basic statistics of the computed Delta R values
bsea_res$statistics
# }
# NOT RUN {
# Acquire "adak" data set
data(adak)
# Compute Delta R values and store them in the new object
adak_res <- dr_df(adak)
# See basic statistics of the computed Delta R values
adak_res$statistics
# Save the results in the file "Adak.txt"
write.table(adak_res$statistics, "Adak.txt")
# Note, that it will be saved in the working directory
# See the path to the working directory
getwd()
# Acquire "coral" data set
data(coral)
# Compute Delta R values and store them in the new object
# Note, that 230Th dates do not need calibration
coral_res <- dr_df(coral, calCurves = "normal")
# See basic statistics of the computed Delta R values
coral_res$statistics
# }