-
Notifications
You must be signed in to change notification settings - Fork 4
/
README.Rmd
109 lines (66 loc) · 5.93 KB
/
README.Rmd
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
---
output: github_document
---
<!-- README.md is generated from README.Rmd. Please edit that file -->
```{r, include = FALSE}
knitr::opts_chunk$set(
collapse = TRUE,
comment = "#>",
fig.path = "man/figures/README-",
out.width = "100%"
)
```
# `fellingdater`: Estimate, report and combine felling dates of historical tree-ring series
<!-- badges: start -->
[](https://github.com/ropensci/fellingdater/actions/workflows/R-CMD-check.yaml) [](https://github.com/ropensci/software-review/issues/618) [](https://ropensci.r-universe.dev)
[](https://zenodo.org/doi/10.5281/zenodo.11186274)
[](https://joss.theoj.org/papers/3db8c54ec854b575bf5450336ccb000b)
<!-- badges: end -->
This R-package offers a suite of functions designed to assist dendrochronologists in inferring estimates for felling dates, derived from dated tree-ring series. The presence of partially preserved sapwood (*sw*) allows to estimate the missing number of sapwood rings, and 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 timbers.
In cases where it can be assumed that a group of historical timbers were all felled simultaneously (i.e., in the same year), but due to the absence of the bark/cambial zone (waney edge) and the final formed tree ring, this cannot be determined, the preserved sapwood rings can be used to establish a date range for the felling event.
Taking into account the observed number of sapwood rings across all analysed samples and combining them into a single estimate, a more accurate and precise estimation of the felling date year for the group of timbers under study is likely to be obtained.
An additional function offers a tool for summing sapwood probability distributions, comparable to 'summed probability densities (SPD)' commonly applied to sets of radiocarbon (^14^C) dates.
## 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")
```
``` r
install.packages("fellingdater", repos = "https://ropensci.r-universe.dev")
```
## Basic example
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:
trs_example1
```
```{r example}
sw_combine(trs_example1, plot = TRUE)
```
The light grey distributions represent the probability density function of the felling date range for each individual series. The dark grey distribution is 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)
```
## Getting started
You can find an overview of the **main functions** and **sapwood datasets** distributed with the package in the [documentation](https://docs.ropensci.org/fellingdater/reference/).
Some practical examples are provided in the [`Get started`](https://docs.ropensci.org/fellingdater/articles/getting_started.html) vignette.
## The workflow
The `fellingdater`-package allows to fully document the methodology to establish a felling date -- for a single timber or a group of timbers -- making the whole procedure reproducible. It assists in building standardized workflows when applied to large datasets of historical tree-ring series originating from geographically distinct regions. The package is designed to offer several functions related to each step in the (generalized) workflow when working with tree-ring series from (pre-)historical objects or constructions.
## 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/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.\
> <https://doi.org/10.21105/joss.06716>
> Kristof HANECA [](https://orcid.org/0000-0002-7719-8305), Vincent DEBONNE [](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.\
> <https://doi.org/10.1016/j.dendro.2020.125773>
## Comments and contributions
- Please report any issues or bugs here: <https://github.com/ropensci/fellingdater/issues>.
- 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.