Main functions
sw_interval
This function calculates the probability density function (PDF) and the highest probability density interval (HDI) for the range of potential felling dates, based on the observed number of sapwood rings, their chronological dating and the selected sapwood data and model.
In the example below, we observe 10 sapwood rings on a sample (with the last ring dated to 1234 AD) that originates from the Southern Baltic region. The sapwood model published by Wazny, 1990 covers this provenance region. The hdi delineates an interval in which the actual felling date is most likely situated. It represents the shortest interval within a probability distribution for a given probability mass or credible interval. The HDI summarizes the distribution by specifying an interval that spans most of the distribution, typically 95%, such that every point inside the interval has higher credibility than any point outside the interval.
sw_interval(n_sapwood = 10,
last = 1234,
hdi = TRUE,
cred_mass = .95,
sw_data = "Wazny_1990",
densfun = "lognormal")
#> lower upper p
#> 1 1234 1250 0.9611793When hdi = FALSE, a matrix is returned with scaled
p-values for each number of observed sapwood rings.
The results of this procedure can be visualized by setting
plot = TRUE.
# 10 sapwood rings observed and the Wazny 1990 sapwood model:
sw_interval(n_sapwood = 10,
last = 1234,
hdi = TRUE,
cred_mass = .95,
sw_data = "Wazny_1990",
densfun = "lognormal",
plot = TRUE)
fd_report
The fd_report()function reports estimates of the felling
date (fd) range for individual series.
tmp <- data.frame(id = c("aaa", "bbb", "ccc"),
swr = c(10, 11, 12),
waneyedge = c(FALSE, FALSE,TRUE),
end = c(123, 456, 1789))
fd_report(tmp,
series = "id",
n_sapwood = "swr",
last = "end",
sw_data = "Wazny_1990")
#> series last n_sapwood waneyedge lower upper felling_date sapwood_model
#> 1 aaa 123 10 FALSE 123 139 between 123 and 139 Wazny_1990
#> 2 bbb 456 11 FALSE 456 471 between 456 and 471 Wazny_1990
#> 3 ccc 1789 12 TRUE NA 1789 in 1789 Wazny_1990sw_combine
The the sw_combine() function combines felling dates of
a group of related series with (partially) preserved sapwood, in order
to narrow down the range of a common felling date. The function returns
a list with:
the PDF for the felling date of the individual series and the PDF of the model that combines these individual series (
$dataRaw),the HDI for the combined estimate of the common felling date (
$hdi_model),the Agreement index (
$A_comb) of the model, expressing how well the individual series fit into the model (ideally around 100%, and not lower than the critical threshold A_c = 60%) ,an overview of the felling date range for the individual series (
$individual_series), and their Agreement index (A_i) to the combined model.
trs_example0
A data set with dated tree-ring series, all with partially preserved
sapwood. The names of the variables in the data set are mapped to the
parameters of the sw_combine() function. In the example
below, the numeric output is returned:
trs_example0
#> trs end swr bark
#> 1 trs_01 1000 5 FALSE
#> 2 trs_02 1009 10 FALSE
#> 3 trs_03 1007 15 FALSE
#> 4 trs_04 1005 16 FALSE
#> 5 trs_05 1010 8 FALSE
# In trs_example0, the column names are not equivalent to the default names in `sw_combine()`.
output_comb <- sw_combine(trs_example0,
series = "trs",
last = "end",
n_sapwood = "swr",
waneyedge = "bark",
cred_mass = .954,
plot = FALSE
)
head(output_comb$rawData, 20)
#> NULL
output_comb[-1]
#> $sapwood_data
#> [1] "Hollstein_1980"
#>
#> $sapwood_model
#> [1] "lognormal"
#>
#> $cred_mass
#> [1] 0.954
#>
#> $hdi_model
#> lower upper p
#> 1 6 34 0.9561277
#>
#> $hdi_combine
#> lower upper p
#> 1 1010 1018 0.9741642
#>
#> $individual_series
#> series last n_sapwood waneyedge lower upper agr_index
#> 1 trs_01 1000 5 FALSE 1001 1029 122.0
#> 2 trs_02 1009 10 FALSE 1009 1033 132.3
#> 3 trs_03 1007 15 FALSE 1007 1029 103.9
#> 4 trs_04 1005 16 FALSE 1005 1026 78.9
#> 5 trs_05 1010 8 FALSE 1010 1036 108.5
#>
#> $A_model
#> Overall agreement index (%)
#> 117.6
#>
#> $A_c
#> Critical threshold (%)
#> 60
#>
#> $model_summary
#> [1] "felling date range: 1010 - 1018"trs_example2
A data set with 5 tree-ring series, one of which has an exact felling date (waney edge present):
trs_example2
#> series last n_sapwood waneyedge
#> 1 trs_06 1000 5 FALSE
#> 2 trs_07 1005 10 FALSE
#> 3 trs_08 1008 NA FALSE
#> 4 trs_09 1000 1 FALSE
#> 5 trs_10 1010 15 TRUE
sw_combine(trs_example2, plot = TRUE)
trs_example3
A data set where all tree-ring series have been measured up to the waney edge:
trs_example4
An attempt to compute a common felling date for a group of tree-ring series, all including partially preserved sapwood:
No common felling date can be computed for this particular data set. The model fails (agreement index of the model is below the critical threshold value (A_c) of 60%). Three series have an individual agreement index below 60%.
sw_sum
The sw_sum() function calculates the the summed
probability density (SPD) for a set of felling date ranges. In the
example, the SPD for a set of 9 series with partially preserved sapwood
or waney edge is computed and plotted. A smoother for the SPD is plotted
as well. The dots represent exact felling dates (i.e., series with waney
edge).
spd7 <- sw_sum(trs_example7, plot = FALSE)
#> Warning in sw_sum(trs_example7, plot = FALSE): --> 1 series without sapwood rings or waney edge detected
#> and removed from the data set
sw_sum_plot(spd7, window_smooth = 5, bar_col = "#95d5b2", trend_col = "#dda15e", dot_col = "forestgreen", dot_shape = 23, dot_size = 4)
