<!-- README.md is generated from README.Rmd. Please edit that file -->

fellingdater: Tree-ring dating and estimating felling dates of historical timbers

<!-- badges: start -->

<!-- badges: end -->

The fellingdater package provides a suite of functions for dendrochronological and dendroarchaeological analysis, covering a workflow from tree-ring data processing and crossdating, up to the estimation and reporting of felling dates. Originally designed to assist dendrochronologists in inferring felling dates from dated tree-ring series with partially preserved sapwood, the package has been expanded to include a workflow for tree-ring dating, analysis, and visualization.

Installation

You can install the latest release of fellingdater from GitHub or R-universe:

# install.packages("pak")
pak::pak("ropensci/fellingdater")

or

# install.packages("remotes")
remotes::install_github("ropensci/fellingdater")

Core functionality

Tree-ring series analysis (trs_* functions):

• Data generation and preparation: Create synthetic datasets with trs_pseudo_rwl(), or read and prepare real data with read_fh(), trs_select(), trs_remove() and trs_trim().

• Crossdating analysis: Perform crossdating with trs_crossdate() and set end dates for the tree-ring series with trs_date_end().

  The statistical measures in the crossdating procedure include:

  • t-values according to Hollstein (1980) and Baillie & Pilcher (1973) transformation procedures (trs_tho()and trs_tbp())

  • percentage of parallel variation, including (Semi-)Synchronous Growth Changes (SGC and SSGC, Visser 2020), and Gleichläufigkeit (Buras & Wilmking 2015, Eckstein & Bauch 1969, Huber 1943) and associated significance level (Jansma 1995) (trs_pv())

  • correlation measures, r Pearson and t-values (trs_tSt())

• Visualization: Display crossdating results with trs_plot_dated(), or individual series with trs_plot_rwl()

**Felling date estimation ** (sw_* functions):

The package’s primary focus is estimating felling dates from accurately dated tree-ring series with preserved sapwood (sw). When the bark/cambial zone (waney edge) is absent, the preserved sapwood rings can be used to establish a date range for the felling event, allowing researchers to report an interval in which the actual felling date (fd) likely falls.

This procedure can be applied to individual series as well as to a collection of related timbers.

• Individual series: Estimate felling date ranges from tree-ring series with preserved sapwood.

• Group analysis: Combine multiple samples assumed to be felled simultaneously for enhanced precision.

• Probability densities: Work with sapwood probability distributions and create summed probability densities that reflect dynamics in felling date intensity.

Workflow

The package workflow progresses logically through:

1. Data preparation - Generate synthetic data or prepare existing tree-ring measurements
2. Crossdating and statistical analysis - Establish accurate calendar dates for tree-ring series
3. Quality control - Validate dating results using multiple statistical measures
4. Felling date estimation - Apply sapwood models to dated series with preserved sapwood
5. Grouping - Combine individual felling date estimates for related wooden finds
6. Visualization and reporting - Present results with publication-ready graphics

Examples

Felling date estimation

In the following example the combined felling date range for a set of five dated tree-ring series is computed:

library(fellingdater)

## a data set where all series have partially preserved sapwood:
sw_example1
#>   series last n_sapwood waneyedge
#> 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

sw_combine(sw_example1, plot = TRUE)

<img src="man/figures/README-example-1.png" width="100%" />

The light grey distributions shows felling date probability densities for each individual series, while the dark grey distribution represents the combined estimate for a common felling date.

The sapwood model used in the example above to estimate the felling date range, was published by Hollstein (1980):

sw_model("Hollstein_1980", plot = TRUE)

<img src="man/figures/README-model_sapwood_counts-1.png" width="100%" />

Tree-ring series analysis

The package provides comprehensive tools for the tree-ring analysis workflow:

• Generate synthetic tree-ring data for testing

set.seed(1234)
trs <- trs_pseudo_rwl(n_series = 5, series_length = c(100, 150),
                      end_date = c(2000, 2025), related = TRUE,
                      prefix = "series_")

trs_plot_rwl(trs,
             color = c("tomato3", "navyblue", "forestgreen", "purple", "orange")
             )

<img src="man/figures/README-trs-example-1.png" width="100%" />

• Crossdate a series against a reference series/chronology

series <- trs |> trs_select("series_1", trim = TRUE)
reference <- trs |> trs_select("series_2")
cd_results <- trs_crossdate(series, reference, min_overlap = 50,
                            sliding = TRUE, top_n = 5, rank_by = "t_Ho")
#>   |                                                                              |                                                                      |   0%  |                                                                              |                                                                      |   1%  |                                                                              |=                                                                     |   1%  |                                                                              |=                                                                     |   2%  |                                                                              |==                                                                    |   3%  |                                                                              |===                                                                   |   4%  |                                                                              |===                                                                   |   5%  |                                                                              |====                                                                  |   6%  |                                                                              |=====                                                                 |   7%  |                                                                              |=====                                                                 |   8%  |                                                                              |======                                                                |   8%  |                                                                              |======                                                                |   9%  |                                                                              |=======                                                               |  10%  |                                                                              |========                                                              |  11%  |                                                                              |========                                                              |  12%  |                                                                              |=========                                                             |  13%  |                                                                              |==========                                                            |  14%  |                                                                              |==========                                                            |  15%  |                                                                              |===========                                                           |  15%  |                                                                              |===========                                                           |  16%  |                                                                              |============                                                          |  17%  |