update CITATION

- paper.md accepted for publication in Journal of Open Source Software

inst/CITATION

@@ -1,21 +1,25 @@
 citHeader("To cite fellingdater in publications use:")
 
 bibentry(
-  bibtype    = "Manual",
-  title    = "fellingdater: an R package to facilitate the organisation, analysis and interpretation of tree-ring data from wooden heritage objects and structures" ,
+  bibtype  = "Article",
+  title    = "fellingdater: a toolkit to estimate, report and combine felling dates derived from historical tree-ring series",
   author   = "Kristof Haneca",
+  journal  = "Journal of Open Source Software",
   year     = "2024",
-  note     = "R package, version 1.0.1",
-  url      = "https://github.com/ropensci/fellingdater",
+  volume   = "9",
+  number   = "97",
+  pages    = "6716",
+  doi      = "10.21105/joss.06716"
+)
+
+bibentry(
+  bibtype  = "Article",
+  title    = "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)",
+  author   = "Kristof Haneca, Vincent Debonne, Patrick Hoffsummer",
+  journal  = "Dendrochronologia",
+  year     = "2020",
+  volume   = "64",
+  pages    = "125773",
+  doi      = "10.1016/j.dendro.2020.125773"
 )
 
-bibentry(bibtype = "Article",
-         title = "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)",
-         journal = "Dendrochronologia",
-         volume = "64",
-         pages = "125773",
-         year = "2020",
-         doi = "10.1016/j.dendro.2020.125773",
-         author = "Kristof Haneca, Vincent Debonne, Patrick Hoffsummer",
-         keywords = "dendrochronology, sapwood, rood constrcutions, tree-ring dating",
-         key = "Haneca_etal2020")

vignettes/articles/the_workflow.Rmd

@@ -14,13 +14,15 @@ knitr::opts_chunk$set(
 library(fellingdater)
 ```
 
-> **This vignette is a lengthy version of a paper submitted to '*The Journal of Open Source Software*' (JOSS).**
+> 
+> **This vignette is a lengthy version of a paper published in [*The Journal of Open Source Software*](https://joss.theoj.org/papers/10.21105/joss.06716).**
+> 
 
 \
 
 # Summary
 
-Tree-ring dating, or dendrochronology, allows to assign calendar-year dates to growth rings that can be observed on a cross-section of a stem or a piece of timber. It involves measuring the width of each growth ring and comparing the measured ring-width pattern to absolutely dated reference chronologies. Once a tree-ring series is securely anchored to a calendar year time-scale, the end date of the outermost ring can be used to determine or estimate the year of death of the parent tree (i.e., the felling of the tree).
+Tree-ring dating, or dendrochronology, allows the assignment of calendar-year dates to growth rings that can be observed on a cross-section of a stem or a piece of timber. It involves measuring the width of each growth ring and comparing the measured ring-width pattern to absolutely dated reference chronologies. Once a tree-ring series is securely anchored to a calendar year time scale, the end date of the outermost ring can be used to determine or estimate the year of death of the parent tree (i.e., the felling of the tree).
 
 The `fellingdater` package offers a suite of functions that can assist dendrochronologists to infer, combine and report felling date estimates from dated tree-ring series of (pre-)historical timbers, based on the presence of partially preserved sapwood or waney edge ([Fig. 1](#fig-cross-section)).
 
@@ -44,7 +46,7 @@ The `fellingdater` package aims to facilitate this process by providing function
 
 Many descriptive statistics and statistical models have been published to establish accurate estimates of the expected number of sapwood ring [@edvardsson2022; @bleicher2020; @rybnicek2006; @pilcher1987; @hollstein1965; @hollstein1980; @wazny1990; @miles1997; @sohar2012; @bräthen1982; @haneca2009; @hughes1981; @jevsenak2019; @hillam1987; @gjerdrum2013; @shindo2024]. These models are based on counts of sapwood rings from living and historical timber and often rely on log-transformation of the original data, or use regression models including additional variables such as mean ring width, the cambial age of the tree or a combination of both. These statistical procedures report the expected minimal and maximal number of sapwood rings, usually within 95% a confidence interval, but have also been presented in a wide variety of ways and differ among laboratories and dendrochronologists. A standardized methodology for reporting felling dates is therefore hampered by this variety in statistical approaches. This variety in methodology and reporting comes even more to the surface when tree-ring dates of multiple elements from a single object, construction or building phase are combined into a single felling date for the whole ensemble. The goal of such a mutual interpretation of the individual felling dates is to refine the range of the felling date, but also to check or test whether these dated tree-ring series/wooden elements could indeed represent one single event (i.e. the felling of trees).
 
-A Bayesian method to improve the procedures to model sapwood data, compute lower and upper limits for the felling date based upon the selected sapwood model and a given credible interval have been introduced by @millard2002a. This procedure was further refined by @miles2006, and critically reviewed with real-life examples by @tyers2008. This workflow has been incorporated in [OxCal](https://c14.arch.ox.ac.uk/oxcal/OxCal.html), the routine software for calibration and analysis of radiocarbon dates and related archaeological and chronological information [@bronkramsey2009: <https://c14.arch.ox.ac.uk/oxcalhelp/Sapwood.html>]. Tree-ring analyses, on the other hand, relies on a growing set of R-packages, with the '*Dendrochronology Program Library in R*' [@bunn2008; @bunn2010; @bunn2022], the `dplR`-package, at it's core [see <https://opendendro.org/>, @bunn2022a]. Yet, the Bayesian methodology to establish sapwood estimates and felling dates was so far not available as a suite of functions in R [@rcoreteam2022].
+A Bayesian method to improve the procedures to model sapwood data, compute lower and upper limits for the felling date based upon the selected sapwood model and a given credible interval have been introduced by @millard2002a. This procedure was further refined by @miles2006, and critically reviewed with real-life examples by @tyers2008. This workflow has been incorporated in [OxCal](https://c14.arch.ox.ac.uk/oxcal/OxCal.html), the routine software for calibration and analysis of radiocarbon dates and related archaeological and chronological information [@bronkramsey2009: <https://c14.arch.ox.ac.uk/oxcalhelp/Sapwood.html>]. Tree-ring analyses, on the other hand, relies on a growing set of R-packages, with the '*Dendrochronology Program Library in R*' [@bunn2008; @bunn2010; @bunn2022], the `dplR`-package, at its core [see <https://opendendro.org/>, @bunn2022a]. Yet, the Bayesian methodology to establish sapwood estimates and felling dates was so far not available as a suite of functions in R [@rcoreteam2022].
 
 In order to facilitate and standardize the reporting, interpretation and combination of felling dates from historical timbers and objects, the `fellingdater` R-package was devised. The 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 and assists in building standardized workflows when applied to large datasets of historical tree-ring series originating from geographically distinct regions [e.g. @haneca2020]. The package is designed to offer several functions that are related to each step in the (generalized) workflow when analysing tree-ring series from (pre-)historical objects or constructions ([Fig. 2](#fig-workflow)).
 
@@ -209,9 +211,9 @@ cor_table(x = Doel1_trs,
 
 ## Felling date interval
 
-After selecting the appropriate sapwood model (e.g., one of [Fig. 2](#fig-sw-model)) one can use the model to estimate the upper and lower limits of the number of missing sapwood rings. The function `sw_interval()` calcualtes the probability density function (PDF) and highest probability density interval (HDI) of the felling date range based on the observed number of sapwood rings (`n_sapwood = ...`), their chronological dating (`last = ...`) and the selected sapwood data (`sw_data = ...`) and model (`densfun = ...`).
+After selecting the appropriate sapwood model (e.g., one of [Fig. 3](#fig-sw-model)) one can use the model to estimate the upper and lower limits of the number of missing sapwood rings. The function `sw_interval()` calcualtes the probability density function (PDF) and highest probability density interval (HDI) of the felling date range based on the observed number of sapwood rings (`n_sapwood = ...`), their chronological dating (`last = ...`) and the selected sapwood data (`sw_data = ...`) and model (`densfun = ...`).
 
-In the example below, 10 sapwood rings were observed on a historical timber, with the last ring dated to 1234 CE, that is supposed to have a provenance in the Southern Baltic region (covered by the sapwood model published by Wazny [-@wazny1990]). The HDI delineates an interval in which the actual felling date is most likely situated. It is the shortest interval within a probability distribution for a given probability mass or credible interval (`cred_mass = ...`). The HDI summarizes the distribution by specifying an interval that spans most of the distribution (in the example below the credible interval is set to 95%), as such that every point inside the interval has higher credibility than any point outside the interval ([Fig. 4](#fig-sw_interval)).
+In the example below, 10 sapwood rings were observed on a historical timber, with the last ring dated to 1234 CE, that is supposed to have a provenance in the Southern Baltic region (covered by the sapwood model published by Wazny [-@wazny1990]). The HDI delineates an interval in which the actual felling date is most likely situated. It is the shortest interval within a probability distribution for a given probability mass or credible interval (`cred_mass = ...`). The HDI summarizes the distribution by specifying an interval that spans most of the distribution (in the example below the credible interval is set to 95%), as such that every point inside the interval has higher credibility than any point outside the interval ([Fig. 4](#fig-sw-interval)).
 
 Note that the more sapwood rings that have been measured, the more probability mass is assigned to the tails of the sapwood model.
 
@@ -309,7 +311,7 @@ p2 <- sw_combine(trs_example4, plot = TRUE)
 
 ## Sum felling dates
 
-For large datasets of dated tree-ring series, it is not always straightforward to assess temporal trends in the frequency of felling dates. Exact felling dates can be stacked by calender year, but for series with partially preserved sapwood, their felling date is situated in an interval. The individual series each have their own probability density function based on a chosen sapwood model and the number of observed sapwood rings. To make another reference to radiocarbon dating, it is common practice in the analysis of large volumes of radiocarbon dates to compute the *summed probability densities* (SPD) of the calibrated radiocarbon dates. Summed probabilities are used to determine the temporal density of ages (events) in situations where there is no clear prior information on their distribution [@bronkramseymethods2017]. This procedure is implemented in OxCal and the R-package `rcarbon` [@crema2020]. The function `sw_sum()` makes his procedure available for tree-ring analyses. The summed probability distribution (SPD) of the individual probability densities of felling dates of single tree-ring series with incomplete sapwood allows to visualize fluctuations in the incidence of potential felling dates over time. The resulting *p*-values should however not be interpreted in a probabilistic way but must be regarded as relative measures that unveil temporal trends in the dataset. Exact felling dates derived from tree-ring series with waney edge are not included in the computational process of the SPD as they would result in anomalous spikes in the SPD, as their associated probability (*p* = 1) would be assigned to a single calendar year, whereas for series with incomplete sapwood the total probability (*p* = 1) is dispersed over a wider time range. Therefore exact felling dates are plotted separately on top of the SPD ([Fig. 6](#fig-sw_sum)).
+For large datasets of dated tree-ring series, it is not always straightforward to assess temporal trends in the frequency of felling dates. Exact felling dates can be stacked by calender year, but for series with partially preserved sapwood, their felling date is situated in an interval. The individual series each have their own probability density function based on a chosen sapwood model and the number of observed sapwood rings. To make another reference to radiocarbon dating, it is common practice in the analysis of large volumes of radiocarbon dates to compute the *summed probability densities* (SPD) of the calibrated radiocarbon dates. Summed probabilities are used to determine the temporal density of ages (events) in situations where there is no clear prior information on their distribution [@bronkramseymethods2017]. This procedure is implemented in OxCal and the R-package `rcarbon` [@crema2020]. The function `sw_sum()` makes his procedure available for tree-ring analyses. The summed probability distribution (SPD) of the individual probability densities of felling dates of single tree-ring series with incomplete sapwood allows to visualize fluctuations in the incidence of potential felling dates over time. The resulting *p*-values should however not be interpreted in a probabilistic way but must be regarded as relative measures that unveil temporal trends in the dataset. Exact felling dates derived from tree-ring series with waney edge are not included in the computational process of the SPD as they would result in anomalous spikes in the SPD, as their associated probability (*p* = 1) would be assigned to a single calendar year, whereas for series with incomplete sapwood the total probability (*p* = 1) is dispersed over a wider time range. Therefore exact felling dates are plotted separately on top of the SPD ([Fig. 6](#fig-sw-sum)).
 
 ``` r
 sum <- sw_sum(trs_example7)