fellingdater

fellingdater: a toolkit to estimate, report and combine felling dates derived from historical tree-ring series - Published in JOSS (2024)

https://github.com/ropensci/fellingdater

Keywords

Scientific Fields

Repository

A suite of functions designed to assist dendrochronologists in inferring estimates for felling dates, derived from dated tree-ring series.

README.Rmd

---
output: github_document
editor_options: 
  markdown: 
    wrap: 72
---



```{r, include = FALSE}
knitr::opts_chunk$set(
     collapse = TRUE,
     comment = "#>",
     fig.path = "man/figures/README-",
     out.width = "100%"
)
```

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



[![R-CMD-check](https://github.com/ropensci/fellingdater/actions/workflows/R-CMD-check.yaml/badge.svg)](https://github.com/ropensci/fellingdater/actions/workflows/R-CMD-check.yaml)
[![rOpenSci](https://badges.ropensci.org/618_status.svg)](https://github.com/ropensci/software-review/issues/618)
[![fellingdateer status
badge](https://ropensci.r-universe.dev/badges/fellingdater)](https://ropensci.r-universe.dev)
[![DOI](https://zenodo.org/badge/276190636.svg)](https://zenodo.org/doi/10.5281/zenodo.11186274)
[![JOSS](https://joss.theoj.org/papers/3db8c54ec854b575bf5450336ccb000b/status.svg)](https://joss.theoj.org/papers/3db8c54ec854b575bf5450336ccb000b)



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.

![](man/figures/cross-section.png)

## Installation

You can install the latest release of `fellingdater` from
[GitHub](https://github.com/ropensci/fellingdater/) or
[R-universe](https://ropensci.r-universe.dev/fellingdater):

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

or

``` r
# 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)](https://search.worldcat.org/de/title/899062584) and
        [Baillie & Pilcher (1973)](http://hdl.handle.net/10150/260029)
        transformation procedures (`trs_tho()`and `trs_tbp()`)

    -   percentage of parallel variation, including (Semi-)Synchronous
        Growth Changes (SGC and SSGC, [Visser
        2020](https://doi.org/10.1111/arcm.12600)), and
        *Gleichläufigkeit* ([Buras & Wilmking
        2015](https://doi.org/10.1016/j.dendro.2015.03.003), [Eckstein &
        Bauch 1969](https://doi.org/10.1007/BF02741777), [Huber
        1943](https://doi.org/10.1007/BF02603303)) and associated
        significance level ([Jansma
        1995](https://dspace.library.uu.nl/handle/1874/45149))
        (`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.

![](man/figures/workflow.png)


### 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:

```{r basic-example}
library(fellingdater)

## a data set where all series have partially preserved sapwood:
sw_example1
```

```{r example}
sw_combine(sw_example1, plot = TRUE)
```

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)](https://search.worldcat.org/nl/title/6391864):

```{r model_sapwood_counts, dpi=200}
sw_model("Hollstein_1980", plot = TRUE)
```

### Tree-ring series analysis

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

- Generate synthetic tree-ring data for testing

```{r trs-example}
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")
             )
```

- Crossdate a series against a reference series/chronology

```{r}
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")

cd_results
```

 - Visualize crossdating results
 
```{r}
series_dated <- trs_end_date(series, 2014)
trs_plot_dated(series_dated, reference, 
               zscore = TRUE, pv_highlight = TRUE)

```

## Getting started

Explore the package capabilities through our documentation:

-   **Function reference**: Complete overview of all functions and
    datasets at
    [docs.ropensci.org/fellingdater/reference/](https://docs.ropensci.org/fellingdater/reference/)
-   **Practical examples**: Step-by-step workflows in the [`Get started`
    vignette](https://docs.ropensci.org/fellingdater/articles/getting_started.html)
-   **Sapwood models**: Available regional sapwood datasets and their
    applications

## Motivation & citation

This package was developed during the analysis of a large data set of
tree-ring series originating from medieval timber constructions in
[Bruges](https://en.wikipedia.org/wiki/Bruges) (Belgium). The results of
this study were published in
[*Dendrochronologia*](https://www.journals.elsevier.com/dendrochronologia).

Please cite these papers when using the `fellingdater` package:

> Kristof HANECA
> [![](https://orcid.org/sites/default/files/images/orcid_16x16.png)](https://orcid.org/0000-0002-7719-8305)
> 2024. *fellingdater*: a toolkit to estimate, report and combine
> felling dates derived from historical tree-ring series. *Journal of
> Open Source Software*, 9(97), 6716. 
> 

> Kristof HANECA
> [![](https://orcid.org/sites/default/files/images/orcid_16x16.png)](https://orcid.org/0000-0002-7719-8305),
> Vincent DEBONNE
> [![](https://orcid.org/sites/default/files/images/orcid_16x16.png)](https://orcid.org/0000-0003-4536-146X),
> Patrick HOFFSUMMER 2020. The ups and downs of the building trade in a
> medieval city: tree-ring data as proxies for economic, social and
> demographic dynamics in Bruges (*c.* 1200 -- 1500).
> *Dendrochronologia* 64, 125773.\
> 

## Acknowledgements

The `fellingdater` package builds on established crossdating algorithms
from dendrochronology literature. It also draws inspiration from
established R-apackages like [`dplR`](https://opendendro.org/r/).

## Academic papers citing `fellingdater`

> Altman J., Altmanova N., Fibich P., Korznikov K. & Fonti P. 2025:
> Advancing dendrochronology with R: an overview of packages and future
> perspectives, *Frontiers in Ecology and Evolution* 13, 1593675.
> 

> Haneca K., Debonne V., Davies D., McCarroll D. & Loader N.J. 2025:
> Oxygen isotope dendrochronology allows dating of historical timbers
> across a wide geographical region, *Dendrochronologia* 89, 126283.
> 

> Haneca K. 2024: *fellingdater*: a toolkit to estimate, report and
> combine felling dates derived from historical tree-ring series,
> *Journal of Open Source Software* 9.97, 6716.
> 

> Haneca K. & De Groote K. 2024: Ieper - De Meersen. Deel 5. Houten
> grafkisten, tonnen en gebruiksvoorwerpen: dendrochronologie, typologie
> en houtonderzoek, *Onderzoeksrapporten agentschap Onroerend Erfgoed*
> 330, Brussel. 

> Domínguez-Delmás M., Schroeder H., Kuitems M., Haneca K., Archangel
> S., van Duin P. & Piena H. 2023: A stepwise multidisciplinary approach
> to determine the date and provenance of historical wooden objects,
> *Journal of Cultural Heritage* 62, 430–440.
> 

> Haneca K., Debonne V. & Hoffsummer P. 2020: The ups and downs of the
> building trade in a medieval city: Tree-ring data as proxies for
> economic, social and demographic dynamics in Bruges (c. 1200–1500),
> *Dendrochronologia* 64, 125773.
> 

## Comments and contributions

-   Please report any issues or bugs here:
    .

-   Get citation information for `fellingdater` in R typing
    `citation(package = 'fellingdater')`.

-   Please note that the `fellingdater` package is released with a
    [Contributor Code of
    Conduct](https://github.com/ropensci/fellingdater/blob/main/.github/CONTRIBUTING.md).
    By contributing to this project, you agree to abide by its terms.

Owner

JOSS Publication

fellingdater: a toolkit to estimate, report and combine felling dates derived from historical tree-ring series

Published

May 22, 2024

DOI

10.21105/joss.06716

Volume 9, Issue 97, Page 6716

Authors

Kristof Haneca
Flanders Heritage Agency, Belgium

Editor

Arfon Smith

Tags

tree-ring analysis dendrochronology sapwood dendroarchaeology

View PDF Review Thread Software Archive

CodeMeta (codemeta.json)

{
  "@context": "https://doi.org/10.5063/schema/codemeta-2.0",
  "@type": "SoftwareSourceCode",
  "identifier": "fellingdater",
  "description": "fellingdater provides a comprehensive 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.",
  "name": "fellingdater: Tree-ring dating and estimating felling dates of historical timbers",
  "relatedLink": [
    "https://docs.ropensci.org/fellingdater",
    "https://ropensci.github.io/fellingdater"
  ],
  "codeRepository": "https://github.com/ropensci/fellingdater",
  "issueTracker": "https://github.com/ropensci/fellingdater/issues",
  "license": "https://spdx.org/licenses/MIT",
  "version": "1.2.0",
  "programmingLanguage": {
    "@type": "ComputerLanguage",
    "name": "R",
    "url": "https://r-project.org"
  },
  "runtimePlatform": "R version 4.5.0 (2025-04-11 ucrt)",
  "author": [
    {
      "@type": "Person",
      "givenName": "Kristof",
      "familyName": "Haneca",
      "email": "Kristof.Haneca@vlaanderen.be",
      "@id": "https://orcid.org/0000-0002-7719-8305"
    }
  ],
  "contributor": [
    {
      "@type": "Person",
      "givenName": "Koen",
      "familyName": "Van Daele",
      "@id": "https://orcid.org/0000-0002-8153-2978"
    },
    {
      "@type": "Person",
      "givenName": "Ronald",
      "familyName": "Visser",
      "@id": "https://orcid.org/0000-0001-6966-1729"
    }
  ],
  "copyrightHolder": [
    {
      "@type": "Person",
      "givenName": "Kristof",
      "familyName": "Haneca",
      "email": "Kristof.Haneca@vlaanderen.be",
      "@id": "https://orcid.org/0000-0002-7719-8305"
    }
  ],
  "maintainer": [
    {
      "@type": "Person",
      "givenName": "Kristof",
      "familyName": "Haneca",
      "email": "Kristof.Haneca@vlaanderen.be",
      "@id": "https://orcid.org/0000-0002-7719-8305"
    }
  ],
  "softwareSuggestions": [
    {
      "@type": "SoftwareApplication",
      "identifier": "covr",
      "name": "covr"
    },
    {
      "@type": "SoftwareApplication",
      "identifier": "knitr",
      "name": "knitr"
    },
    {
      "@type": "SoftwareApplication",
      "identifier": "rmarkdown",
      "name": "rmarkdown"
    },
    {
      "@type": "SoftwareApplication",
      "identifier": "testthat",
      "name": "testthat",
      "version": ">= 3.0.0"
    }
  ],
  "softwareRequirements": {
    "1": {
      "@type": "SoftwareApplication",
      "identifier": "R",
      "name": "R",
      "version": ">= 4.1.0"
    },
    "2": {
      "@type": "SoftwareApplication",
      "identifier": "dplyr",
      "name": "dplyr"
    },
    "3": {
      "@type": "SoftwareApplication",
      "identifier": "plyr",
      "name": "plyr"
    },
    "4": {
      "@type": "SoftwareApplication",
      "identifier": "ggplot2",
      "name": "ggplot2",
      "version": ">= 3.5.0"
    },
    "5": {
      "@type": "SoftwareApplication",
      "identifier": "ggtext",
      "name": "ggtext"
    },
    "6": {
      "@type": "SoftwareApplication",
      "identifier": "MASS",
      "name": "MASS"
    },
    "7": {
      "@type": "SoftwareApplication",
      "identifier": "tidyr",
      "name": "tidyr"
    },
    "8": {
      "@type": "SoftwareApplication",
      "identifier": "utils",
      "name": "utils"
    },
    "9": {
      "@type": "SoftwareApplication",
      "identifier": "dplR",
      "name": "dplR"
    },
    "10": {
      "@type": "SoftwareApplication",
      "identifier": "stats",
      "name": "stats"
    },
    "11": {
      "@type": "SoftwareApplication",
      "identifier": "rlang",
      "name": "rlang"
    },
    "SystemRequirements": null
  },
  "fileSize": "5772.22KB",
  "citation": [
    {
      "@type": "ScholarlyArticle",
      "datePublished": "2024",
      "author": [
        {
          "@type": "Person",
          "givenName": "Kristof",
          "familyName": "Haneca"
        }
      ],
      "name": "fellingdater: a toolkit to estimate, report and combine felling dates derived from historical tree-ring series",
      "identifier": "10.21105/joss.06716",
      "pagination": "6716",
      "@id": "https://doi.org/10.21105/joss.06716",
      "sameAs": "https://doi.org/10.21105/joss.06716",
      "isPartOf": {
        "@type": "PublicationIssue",
        "issueNumber": "97",
        "datePublished": "2024",
        "isPartOf": {
          "@type": [
            "PublicationVolume",
            "Periodical"
          ],
          "volumeNumber": "9",
          "name": "Journal of Open Source Software"
        }
      }
    },
    {
      "@type": "ScholarlyArticle",
      "datePublished": "2020",
      "author": [
        {
          "@type": "Person",
          "givenName": "Kristof",
          "familyName": "Haneca"
        },
        {
          "@type": "Person",
          "givenName": "Vincent",
          "familyName": "Debonne"
        },
        {
          "@type": "Person",
          "givenName": "Patrick",
          "familyName": "Hoffsummer"
        }
      ],
      "name": "The ups and downs of the building trade in a medieval city: Tree-ring data as proxies for economic, social and demographic dynamics in Bruges (c. 1200–1500)",
      "identifier": "10.1016/j.dendro.2020.125773",
      "pagination": "125773",
      "@id": "https://doi.org/10.1016/j.dendro.2020.125773",
      "sameAs": "https://doi.org/10.1016/j.dendro.2020.125773",
      "isPartOf": {
        "@type": "PublicationIssue",
        "datePublished": "2020",
        "isPartOf": {
          "@type": [
            "PublicationVolume",
            "Periodical"
          ],
          "volumeNumber": "64",
          "name": "Dendrochronologia"
        }
      }
    }
  ],
  "releaseNotes": "https://github.com/ropensci/fellingdater/blob/main/NEWS.md",
  "readme": "https://github.com/ropensci/fellingdater/blob/main/README.md",
  "contIntegration": "https://github.com/ropensci/fellingdater/actions/workflows/R-CMD-check.yaml",
  "keywords": [
    "tree-rings",
    "dendrochronology",
    "sapwood",
    "r",
    "r-package",
    "rstats"
  ]
}

GitHub Events

Committers

Last synced: 5 months ago

Issues and Pull Requests

Last synced: 4 months ago