Package 'fellingdater'

Title: Estimate, report and combine felling dates of historical tree-ring series
Description: fellingdater is an R package that aims to facilitate the analysis and interpretation of tree-ring data from wooden cultural heritage objects and structures. The package standardizes the process of computing and combining felling date estimates, both for individual and groups of related tree-ring series.
Authors: Kristof Haneca [aut, cre, cph] , Koen Van Daele [ctb] , Ronald Visser [ctb] , Antonio Jesus Pérez-Luque [rev] , Nicholas John Tierney [rev]
Maintainer: Kristof Haneca <[email protected]>
License: MIT + file LICENSE
Version: 1.0.2
Built: 2024-10-31 19:47:07 UTC
Source: https://github.com/ropensci/fellingdater

Help Index

Brathen 1982 sapwood data set.

Description

Sapwood data set for Western Sweden published by Bräthen in 1982.

Usage

Brathen_1982

Format

A tibble of 2 variables:

n_sapwood

number of sapwood rings

count

number of times n_sapwood was observed

Details

sample size = 69 observations

Source

Bräthen A. 1982. A tree-ring chronology from the western part of Sweden. Sapwood and a dating problem, in: Hackens T., Mejdahl V. (Eds.), Second Nordic Conference on the Application of Scientific Methods in Archaeology, PACT 7(1). pp. 27–35.

Examples

sw_data_info("Brathen_1982")

sw_model("Brathen_1982", plot = TRUE)

Calculate correlation values between tree-ring series

Description

This function calculates common correlation values between dated tree-ring series (x) and a set of reference chronologies (y). When no master chronologies are provided, each series in x is compared to all other series in x.

Only values are reported for pairs of series with a common overlap >= min_overlap.

The correlation values computed include:

  • glk: 'Gleichläufigkeit' or 'percentage of parallel variation' (Buras & Wilmking 2015; Eckstein & Bauch 1969; Huber 1942; Visser 2020)

  • glk_p: significance level associated with the glk-value (Jansma 1995)

  • r_pearson: the Pearson's correlation coefficient

  • t_St: Student's t-value

  • t_BP: t-values according to the Baillie & Pilcher (1973) algorithm

  • t_Ho: t-values according to the Hollstein (1980) algorithm

Usage

cor_table(
  x,
  y = NULL,
  min_overlap = 50,
  remove_duplicates = TRUE,
  output = "table",
  sort_by = "t_Ho"
)

Arguments

x

A data.frame of class ´rwl' with tree-ring data. Each column represents a measurement series, and row names correspond to (calendar) years.
y

A data.frame of class 'rwl' with tree-ring data. Each column represents a measurement series or chronology, and row names correspond to (calendar) years. If NULL (default), x is compared to itself (y = x).
min_overlap

A numeric value specifying the minimum overlap required between series for correlation calculation.
remove_duplicates

A logical value. If TRUE, identical pairs of series and references are removed from the output.
output

The desired output format, either "matrix" or "table" (default).
sort_by

The correlation value by which the output is sorted for each series in x. One of "r_pearson", "t_St", "glk", "glk_p", "t_BP", "t_Ho". Default to "t_Ho"

Details

This function computes various correlation values between tree-ring series in a data.frame x and a set of reference chronologies in a data.frame y. If y is not provided, it compares each series in x to all other series in 'x.

Value

The function returns a list of correlation matrices if output is set to "matrix." If output is set to "table," it returns a data.frame reporting all correlation values.

References

  • Baillie, M.G.L., Pilcher, J.R. (1973) A simple crossdating program for tree-ring research. Tree-Ring Bulletin 33, 7–14. http://hdl.handle.net/10150/260029

  • Buras, A. and Wilmking, M. (2015) Correcting the calculation of Gleichläufigkeit, Dendrochronologia 34, 29-30. https://doi.org/10.1016/j.dendro.2015.03.003

  • Eckstein, D. and Bauch, J. (1969) Beitrag zur Rationalisierung eines dendrochronologischen Verfahrens und zur Analyse seiner Aussagesicherheit. Forstwissenschaftliches Centralblatt, 88(1), 230-250.

  • Huber, B. (1943) Über die Sicherheit jahrringchronologischer Datierung. Holz als Roh- und Werkstoff 6, 263-268. https://doi.org/10.1007/BF02603303

  • Hollstein E. (1980) Mitteleuropäische Eichenchronologie. Trierer dendrochronologische Forschungen zur Archäologie und Kunstgeschichte, Trierer Grabungen und Forschungen 11, Mainz am Rhein.

  • Jansma, E. (1995) RemembeRINGs; The development and application of local and regional tree-ring chronologies of oak for the purposes of archaeological and historical research in the Netherlands, Nederlandse Archeologische Rapporten 19, Rijksdienst voor het Oudheidkundig Bodemonderzoek, Amersfoort. https://dspace.library.uu.nl/handle/1874/45149

  • Schweingruber, F. H. (1988) Tree rings: basics and applications of dendrochronology, Kluwer Academic Publishers, Dordrecht, Netherlands, 276 p.

  • Visser, R.M. (2020) On the similarity of tree-ring patterns: Assessing the influence of semi-synchronous growth changes on the Gleichläufigkeit for big tree-ring data sets, Archaeometry 63, 204-215. https://doi.org/10.1111/arcm.12600

Examples

# example code

Doel1 <- system.file("extdata", "DOEL1.fh", package = "fellingdater")
Doel1_trs <- read_fh(Doel1, verbose = FALSE)
# crossdating ring-width series from Doel 1 against each other:

cor_results <- cor_table(Doel1_trs, output = "table", min_overlap = 80,
sort_by = "t_Ho", remove_duplicates = TRUE)
head(cor_results,20)

Report felling dates of individual tree-ring series

Description

This function reports the felling date estimate of individual tree-ring series, based on the presence/absence of sapwood and/or waney edge. There are three possible modes of reporting:

  • a terminus post quem or earliest possible felling date: when only heartwood rings have been observed and measured

  • a felling date range or interval: when sapwood rings have been recorded, but no bark or waney edge is present.

  • an exact felling date: when bark or waney edge is present on the measured sample.

Reports the lower and upper boundaries of a felling date range for individual tree-ring series.

Usage

fd_report(
  x,
  series = "series",
  last = "last",
  n_sapwood = "n_sapwood",
  waneyedge = "waneyedge",
  sw_data = "Hollstein_1980",
  cred_mass = 0.954,
  densfun = "lognormal"
)

Arguments

x

Name of a data.frame with at least four columms, providing information on

  • the id's of the tree-ring series

  • the number of sapwood rings observed

  • the presence of waney edge

  • the date assigned to the last measured ring.

A column describing the sapwood data set to be used for modelling and the computation of the hdi can be provided as well.
series

Name of the column in x where id's of the tree-ring series are listed as character values.
last

Name of the column in x which lists the calendar year assigned to the last measured ring (should be a numeric vector).
n_sapwood

Name of the column in x where the number of observed sapwood rings are listed (should be numeric vector).
waneyedge

Name of the column in x indicating the presence (TRUE)/absence (FALSE) of waney edge (should be a logical vector).
sw_data

There are two options:

  • A character string providing the name of the sapwood data set to use for modelling. It should be one of the data sets listed in sw_data_overview(), or the name of a data.frame with sapwood data in columns n_sapwood and count, or

  • the name of the column in xthat lists for each series one of the sapwood data sets given by sw_data_overview().

cred_mass

A scalar [0, 1] specifying the mass within the credible interval (default = .954).
densfun

Name of the density function fitted to the sapwood data set. Should be one of:

  • lognormal (the default value),

  • normal,

  • weibull,

  • gammma.

Value

A data.frame reporting the estimate of the felling date for each tree-ring series?

See Also

sw_interval(), sw_data_overview(), sw_interval_plot()

Examples

tmp <- data.frame(id = c("aaa", "bbb", "ccc"),
                  swr = c(10, 11, 12),
                  waneyedge = c(FALSE, FALSE,TRUE),
                  end = c(10, 0, -10))
fd_report(tmp,
          series = "id",
          n_sapwood = "swr",
          last = "end",
          sw_data = "Wazny_1990")

# Example with different sw_model for individual series

sw_models_for_indiv_series <- c("Sohar_2012_ELL_c",
                                "Wazny_1990",
                                "Hollstein_1980",
                                "vanDaalen_Norway",
                                "vanDaalen_Norway")

trs_example2_edit <- cbind(trs_example2, "sw_models" = sw_models_for_indiv_series)

fd_report(trs_example2_edit,
          sw_data = "sw_models"
          )

fellingdater

Description

fellingdater is an R package that facilitate the analysis and interpretation of tree-ring data from wooden cultural heritage objects and structures. The package standardizes the process of computing and combining felling date estimates (fd), derived from the observed number of sapwood rings (sw), both for individual and groups of related tree-ring series.

Learn more about fellingdater at

https://hanecakr.github.io/fellingdater/index.html/

Author(s)

Maintainer: Kristof Haneca [email protected] (ORCID) [copyright holder]

Other contributors:

  • Koen Van Daele (ORCID) [contributor]

  • Ronald Visser (ORCID) [contributor]

  • Antonio Jesus Pérez-Luque (ORCID) [reviewer]

  • Nicholas John Tierney (ORCID) [reviewer]

See Also

It's main functions are:

Retrieve the HEADER fields of a Heidelberg format (.fh) file

Description

This function reports the HEADER fields from a Heidelberg format (.fh) ring-width file. The header fields are harvested from the .fh-file by the read_fh() function, which stores the HEADER fields from the .fh file as attributes of the data.frame with the measurement data it returns.

Usage

fh_header(x)

Arguments

x

The output of read_fh(x, header = TRUE), a data.frame of class rwl.

Value

A data.frame with 29 header fields.

Examples

Doel1 <- system.file("extdata", "DOEL1.fh", package = "fellingdater")
Doel1_trs <- read_fh(Doel1, verbose = FALSE)
fh_header(Doel1_trs)

Compute the highest posterior density interval (hdi)

Description

This function returns a matrix with 'upper' and 'lower' limits of the hdi (highest density interval), and the associated probability 'p'. The function first sorts the input data.frame - with columns 'n_sapwood´ and 'p' (the associated probability) - by column 'p' in decreasing order and then it calculates the HDI by finding the first value of the sorted probabilities higher than the specified cred_mass. It then finds the indices of the values that are greater than or equal to this threshold, and uses these indices to find the 'upper' and 'lower' limits of the hdi. The function also calculates the probability of the interval. The final result is returned as a matrix with 'lower', 'upper', and 'p' values.

This function is applied in functions sw_model and sw_interval.

Usage

hdi(x, a = "n_sapwood", b = "p", cred_mass = 0.954)

Arguments

x

A data.frame with columns n_sapwood and p (the associated probability). x is computed in functions sw_model, sw_interval, and sw_combine.
a

The name of the column in x that lists the number of sapwood rings.
b

The name of the column in x that lists the the associated probability of having n sapwood rings.
cred_mass

A scalar [0, 1] specifying the mass within the credible interval (default = .954).

Value

A matrix with ´upper´ and ´lower´ limits of the hdi, and the associated probability ´p´.

Examples

tmp <- data.frame(n_sapwood = seq(1,30, 1),
                  p = dnorm(seq(1,30, 1), 15, 5))
hdi(tmp, cred_mass = 0.954)

Hollstein 1980 sapwood data set.

Description

Sapwood data set for South and Central Germany published by Hollstein in 1980.

Usage

Hollstein_1980

Format

A tibble of 2 variables:

n_sapwood

number of sapwood rings

count

number of times n_sapwood was observed

Details

sample size = 490 observations

Source

Hollstein E. 1980. Mitteleuropäische Eichenchronologie: Trierer dendrochronologische Forschungen zur Archäologie und Kunstgeschichte, Trierer Grabungen und Forschungen. Verlag Phillipp von Zabern, Mainz am Rhein.

Examples

sw_data_info("Hollstein_1980")

sw_model("Hollstein_1980", plot = TRUE)

Miles 1997 sapwood data set.

Description

Sapwood data set for the Northern Midland counties (U.K.) - Cheshire, Staffordshire, West Midlands, Northamptonshire, Cambridgeshire, and everything to the north - published by Miles in 1997.

Usage

Miles_1997_NM

Format

A tibble of 2 variables:

n_sapwood

number of sapwood rings

count

number of times n_sapwood was observed

Details

sample size = 295 observations

Source

Miles D. 1997. The interpretation, presentation and use of tree-ring dates. Vernacular architecture 28, 40–56. https://doi.org/10.1179/030554797786050563

Examples

sw_data_info("Miles_1997_NM")

sw_model("Miles_1997_NM", plot = TRUE)

Miles 1997 sapwood data set.

Description

Sapwood data set for the Southern counties (U.K.), up to and including Gloucestershire, Warwickshire, Bedfordshire, Suffolk and Norfolk, published by Miles in 1997.

Usage

Miles_1997_SC

Format

A tibble of 2 variables:

n_sapwood

number of sapwood rings

count

number of times n_sapwood was observed

Details

sample size = 406 observations

Source

Miles D. 1997. The interpretation, presentation and use of tree-ring dates. Vernacular architecture 28, 40–56. https://doi.org/10.1179/030554797786050563

Examples

sw_data_info("Miles_1997_SC")

sw_model("Miles_1997_SC", plot = TRUE)

Miles 1997 sapwood data set.

Description

Sapwood data set for Wales and border counties (U.K.), Shropshire, Hereford and Worcesterthe, published by Miles in 1997.

Usage

Miles_1997_WBC

Format

A tibble of 2 variables:

n_sapwood

number of sapwood rings

count

number of times n_sapwood was observed

Details

sample size = 219 observations

Source

Miles D. 1997. The interpretation, presentation and use of tree-ring dates. Vernacular architecture 28, 40–56. https://doi.org/10.1179/030554797786050563

Examples

sw_data_info("Miles_1997_WBC")

sw_model("Miles_1997_WBC", plot = TRUE)

Compute a running mean on a time series

Description

This vectorized function computes a running mean/moving average over a continuous (time) series with a specified window width.

Usage

mov_av(x, w = 11, align = "center", edges = "fill")

Arguments

x

A numeric vector of length(x), with the time series data.
w

The width of the moving average window. When wis even, one more value from the future is included.
align

The alignment of the window relative to the current data point. It can be one of:

  • align = "center": The average is assigned to the center of the window (default).

  • align = "left": The average includes the current value and the next (w-1) values.

  • align = "right": The average includes the current value and the previous (w-1) values.

edges

Defines how values are computed at the start and end of the series. Options are:

  • edges = "fill": The average is calculated with a decreasing number of values near the edges of the vector (default).

  • edges = "nofill": The result includes NA values when the window does not cover w values.

Value

A numeric vector of the same length of x with the computed running mean values.

Examples

num_vec <- sample(seq(50, 100, 1), 100, replace = TRUE)
filtered <- mov_av(num_vec, w = 5, align = "center", edges = "nofill")
plot(num_vec, type = "l")
lines(filtered, col = "darkblue")

Pilcher 1987 sapwood data set.

Description

Sapwood data set for northern France , published by Pilcher in 1987.

Usage

Pilcher_1987

Format

A tibble of 2 variables:

n_sapwood

number of sapwood rings

count

number of times n_sapwood was observed

Details

sample size = 219 observations

Source

Pilcher J.R. 1987. A 700 year dating chronology for northern France. Applications of tree-ring studies. Current research in dendrochronology and related subjects. BAR International Series 333, 127–139.

Examples

sw_data_info("Pilcher_1987")

sw_model("Pilcher_1987", plot = TRUE)

Read a Heidelberg format (.fh) tree-ring file

Description

This function reads a Heidelberg format file (.fh) containing ring width data and returns the HEADER fields as attributes of the data.frame´with the measurement data.

The Heidelberg file format is described in detail here: https://www.treeringsociety.org/resources/SOM/Brewer_Murphy_SupplementaryMaterial.pdf

Usage

read_fh(fname, BC_correction = FALSE, verbose = TRUE, header = FALSE)

Arguments

fname

A character vector specifying the name of the .fh file to read.
BC_correction

A logical. If TRUE the correction moves BC-dates one year forward.
verbose

A logical. If FALSE, messages are suppressed during the reading process.
header

A logical. If TRUE the HEADER fields are returned as a data.frame; if FALSE, the measurement data is returned.

Details

This function reads .fh file with ring width data in either block (decadal format) or column format (e.g., with comment flags) as used by TSAP program. The function is also capable of reading chronologies or half-chronos in decadal format. The read_fh function is case-insensitive. Information found in the HEADER fields is listed as attributes of the data.frame´with the measurement data. .

The header fields harvested from the .fh file include:

"Project", "FirstMeasurementDate", "Location", "Town", "Street", "Client", "Longitude", "Latitude", "DateOfSampling", "FirstMeasurementDate", "SapWoodRings", "Comment", "MissingRingsAfter", "InvalidRingsAfter", "MissingringsBefore", "DeltaMissingringsBefore", "ChronoMemberKeycodes", "PersId"

Value

If header is TRUE, a data.frame is returned with HEADER fields as attributes. If header is FALSE, a data.frame of class rwl with ring-width measurements in columns is returned, with (calendar) years as row names.'

Author(s)

The original read.fh() function is part of the dplR package (https://github.com/opendendro/dplR) and was developed by Christian Zang, with new features and patches contributed by Mikko Korpela and Ronald Visser. This read_fh() function expands the functionalities of the original dplR::read.fh().

References

This function is an extension of read.fh() from the dplR package (https://github.com/opendendro/dplR), developed and maintained by Prof. dr. Andy Bunn (Bunn 2008, Bunn 2010, Bunn et al. 2022) on https://opendendro.org/.

Examples

Doel1 <- system.file("extdata", "DOEL1.fh", package = "fellingdater")
Doel1_trs <- read_fh(Doel1, verbose = FALSE)
head(Doel1_trs, 10)

Doel1_header <- read_fh(Doel1, verbose = FALSE, header = TRUE)
Doel1_header

Sohar et al. 2012 sapwood data set.

Description

Sapwood data set for Eastern Estonia, Latvia, Lithuania, published by Sohar et al. in 2012.

Usage

Sohar_2012_ELL_c

Format

A tibble of 2 variables:

n_sapwood

number of sapwood rings

count

number of times n_sapwood was observed

Details

sample size = 562 observations
!!! sapwood determined by _color_

Source

Sohar K., Vitas A. & Läänelaid A. 2012. Sapwood estimates of pedunculate oak (Quercus robur L.) in eastern Baltic, Dendrochronologia 30.1, 49–56. https://doi.org/10.1016/j.dendro.2011.08.001

Examples

sw_data_info("Sohar_2012_ELL_c")

sw_model("Sohar_2012_ELL_c", plot = TRUE)

Sohar et al. 2012 sapwood data set.

Description

Sapwood data set for Eastern Estonia, Latvia, Lithuania, published by Sohar et al. in 2012.

Usage

Sohar_2012_ELL_t

Format

A tibble of 2 variables:

n_sapwood

number of sapwood rings

count

number of times n_sapwood was observed

Details

sample size = 533 observations
!!! sapwood determined by presence of _tyloses_

Source

Sohar K., Vitas A. & Läänelaid A. 2012. Sapwood estimates of pedunculate oak (Quercus robur L.) in eastern Baltic, Dendrochronologia 30.1, 49–56. https://doi.org/10.1016/j.dendro.2011.08.001

Examples

sw_data_info("Sohar_2012_ELL_t")

sw_model("Sohar_2012_ELL_t", plot = TRUE)

Sohar et al. 2012 sapwood data set.

Description

Sapwood data set for Southern Finland and western Estonia, published by Sohar et al. in 2012.

Usage

Sohar_2012_FWE_c

Format

A tibble of 2 variables:

n_sapwood

number of sapwood rings

count

number of times n_sapwood was observed

Details

sample size = 98 observations
!!! sapwood determined by _color_

Source

Sohar K., Vitas A. & Läänelaid A. 2012. Sapwood estimates of pedunculate oak (Quercus robur L.) in eastern Baltic, Dendrochronologia 30.1, 49–56. https://doi.org/10.1016/j.dendro.2011.08.001

Examples

sw_data_info("Sohar_2012_FWE_c")

sw_model("Sohar_2012_FWE_c", plot = TRUE)

Sohar et al. 2012 sapwood data set.

Description

Sapwood data set for Southern Finland and western Estonia, published by Sohar et al. in 2012.

Usage

Sohar_2012_FWE_t

Format

A tibble of 2 variables:

n_sapwood

number of sapwood rings

count

number of times n_sapwood was observed

Details

sample size = 97 observations
!!! sapwood determined by the presence of _tyloses_

Source

Sohar K., Vitas A. & Läänelaid A. 2012. Sapwood estimates of pedunculate oak (Quercus robur L.) in eastern Baltic, Dendrochronologia 30.1, 49–56. https://doi.org/10.1016/j.dendro.2011.08.001

Examples

sw_data_info("Sohar_2012_FWE_t")

sw_model("Sohar_2012_FWE_t", plot = TRUE)

Compute a single felling date range by combining multiple sapwood estimates

Description

This function assesses whether it is possible to combine multiple sapwood estimates into a single felling date range.

Usage

sw_combine(
  x,
  series = "series",
  last = "last",
  n_sapwood = "n_sapwood",
  waneyedge = "waneyedge",
  sw_data = "Hollstein_1980",
  densfun = "lognormal",
  cred_mass = 0.954,
  hdi = TRUE,
  plot = FALSE
)

Arguments

x

A data.frame with at least four columns, providing information on the ID's of the tree-ring series, the number of sapwood rings observed, the presence of waney edge and the calendar date assigned to the last measured ring. A column describing the sapwood data set to be used for modelling and the computation of the hdi can be provided as well.
series

Name of the column in x where ID's of the tree-ring series are listed as character values.
last

Name of the column in x where calendar years assigned to the last measured ring are listed (should be numeric).
n_sapwood

Name of the column in x where the number of observed sapwood rings are listed (should be numeric).
waneyedge

Name of the column in x indicating the presence (TRUE)/absence (FALSE) of waney edge (should be a logical vector).
sw_data

The name of the sapwood data set to use for modelling. It should be one of the data sets listed in sw_data_overview(), or the name of a data.frame with sapwood data in columns n_sapwood and count.
densfun

Name of the density function fitted to the sapwood data set. Should be one of:

  • lognormal (the default value),

  • normal,

  • weibull,

  • gammma.

cred_mass

A scalar [0, 1] specifying the mass within the credible interval (default = .954).
hdi

A logical parameter. If TRUE, the lower and upper limit of the highest density interval (credible interval) is given for the combined felling date. When FALSE, a matrix is returned with scaled p values for calendar years covering the combined estimate of the felling date range.
plot

A logical parameter. If TRUE a ggplot-plot style graph is returned of the individual and combined estimate of the felling date. If FALSE, a list with numeric output of the modelling process is returned.

Value

Depends on the value of plot. If TRUE a ggplot-style is returned, when FALSE a list with the combined probability ($raw_data$comb), the modelling parameters ($sapwood_data, $sapwood_model, $cred_mass), the Highest Posterior Density Interval for combined combined felling date interval ($hdi_combine), and the Agreement indices for the model ($A_model) and individual series ($individual_series$agr_index). The rationale of the agreement index is outlined by Bronk Ramsey (1995; 2009)

References

See Also

sw_combine_plot()

Examples

# a data set in which all series have preserved sapwood

sw_combine(trs_example1, plot = TRUE)

# a data set in which one series has an exact felling date (= waney edge preserved)

trs_example2
sw_combine(trs_example2, plot = TRUE)

# a data set in which multiples series have an exact felling date

trs_example3
sw_combine(trs_example3, plot = FALSE)

Plot the output of sw_combine()

Description

This function plots the result of sw_combine() and the interval for, or the exact felling date of, a group of tree-ring series, with agreement indices for the global model.

Usage

sw_combine_plot(x)

Arguments

x

Output of sw_combine().

Value

A ggplot-style graph, with calendar years on the X-axis and the probability (p) on the Y-axis. Dots represent exact felling dates.

Examples

trs_example2
tmp <- sw_combine(trs_example2)
sw_combine_plot(tmp)

Detailed information on a sapwood data set

Description

This function returns more information on a sapwdood data set. It lists the correct citation for the data set, the area the data set is supposed to represent, the number of observations and summary stats of the raw data.

Usage

sw_data_info(x = NULL)

Arguments

x

The name of a sapwood data set. you can use sw_data_overview() to get an overview of available data sets.

Value

A list with the following components:

  • data: the name of the data set,

  • citation: the correct citation for the data set,

  • area: the area represented by the data set,

  • n_observations: the number of observations in the data set and,

  • summary_raw_data: summary stats of the raw data.

Examples

# Get detailed information on a sapwood data set
sw_data_info("Hollstein_1980")

# Retrieve the citation for a specific data set
sw_data_info("Sohar_2012_FWE_c")$citation

Overview of available sapwood data sets in the fellingdater package

Description

This function provides an overview of the available sapwood data sets and models within the fellingdater package.

Usage

sw_data_overview()

Value

A character vector with the names of all available data sets with sapwood counts in the fellingdater package.

Examples

# Get an overview of available sapwood data sets
sw_data_overview()

Computes the limits of the felling date range

Description

This function computes the probability density function (PDF) and the highest posterior density interval (hdi) of the felling date range based on the observed number of sapwood rings, their chronological dating, and the selected sapwood data and model.

Usage

sw_interval(
  n_sapwood = NA,
  last = 1,
  hdi = FALSE,
  cred_mass = 0.954,
  sw_data = "Hollstein_1980",
  densfun = "lognormal",
  plot = FALSE
)

Arguments

n_sapwood

A numeric. The number of observed sapwood rings.
last

A numeric. The calendar year assigned to the outermost sapwood ring (optional, default = 0).
hdi

A logical. If TRUE, the lower and upper limit of the highest density interval (credible interval) are returned. When FALSE, a matrix is returned with scaled p-values for each number of observed sapwood rings.
cred_mass

A scalar in the range of ⁠[0, 1]⁠ specifying the mass within the credible interval (default = .954)
sw_data

The name of the sapwood data set to use for modelling. It should be one of the data sets listed in sw_data_overview(), or the name of a data.frame with sapwood data in columns n_sapwood and count.
densfun

Name of the density function fitted to the sapwood data set. Should be one of:

  • lognormal (the default value),

  • normal,

  • weibull,

  • gammma.

plot

A logical.

  • If TRUE, a ggplot-style graph is returned of the individual sapwood model and estimate of the felling date range.

  • If FALSE, a list with the numeric output of the modelling process is returned.

Value

Depends on the value of hdi.

  • If hdi = TRUE, a ⁠numeric vector⁠ reporting the upper and lower limit of the hdi (attributes provide more detail on cred_mass and the applied sapwood model (sw_data)).

  • If hdi = FALSE, a data.frame with scaled p values for each number of observed sapwood rings.

Examples

# 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 = FALSE
)
# same example as above, but with numerical output (hdi = FALSE):
sw_interval(
  n_sapwood = 10,
  last = 1234,
  hdi = FALSE,
  cred_mass = .95,
  sw_data = "Wazny_1990",
  densfun = "lognormal",
  plot = FALSE
)

Plot function for the output of sw_interval()

Description

Returns a ggplot-style graph of the probability density function for the felling date range, as computed by sw_interval().

Usage

sw_interval_plot(x, area_fill = "tomato3", line_color = "tomato3")

Arguments

x

Output of sw_interval().
area_fill

Fill color for the area under fitted distribution.
line_color

Line color for the fitted distribution.

Value

A ggplot-style graph, with calendar years on the X-axis and the probability (p) on the Y-axis.

Examples

tmp <- sw_interval(
  n_sapwood = 10,
  last = 1000,
  hdi = FALSE,
  cred_mass = .95,
  sw_data = "Hollstein_1980",
  densfun = "lognormal",
  plot = FALSE
)
sw_interval_plot(tmp, area_fill = "forestgreen", line_color = "forestgreen")

Model sapwood data and compute the highest posterior density interval

Description

This function fits a distribution to a data set of observed sapwood numbers and computes the highest posterior density interval (hdi) for a given credibility mass.

Usage

sw_model(
  sw_data = "Hollstein_1980",
  densfun = "lognormal",
  cred_mass = 0.954,
  source = NA,
  plot = FALSE
)

Arguments

sw_data

The name of the sapwood data set to use for modelling. It should be one of the data sets listed in sw_data_overview(), or the name of a data.frame with sapwood data in columns n_sapwood and count.
densfun

Name of the density function to fit to the sapwood data set. Should be one of:

  • lognormal (the default value),

  • normal,

  • weibull,

  • gammma.

cred_mass

A scalar in the range of ⁠[0, 1]⁠ specifying the mass within the credible interval (default = .954).
source

A character string with info on the data source. This info is incorporated in the titel of the plot when a sapwood data set is provided from a user-defined data.frame.
plot

A logical. If TRUE a plot of the fitted density function is returned. When FALSE, a list with numeric output of the modelling process is returned.

Value

The return value depends on the plot parameter.

  • if plot is TRUE, a ggplot-style graph is returned.

  • if plot is FALSE, a list with the numeric output of the modelling process is returned.

Examples

sw_model(sw_data = "Sohar_2012_ELL_c",
          densfun = "lognormal",
          cred_mass = .095,
          plot = FALSE)

sw_model("Hollstein_1980")

Plot function for the output of sw_model()

Description

Returns a ggplot-style graph of the probability density function modelled to a data set of observed sapwood numbers, as computed by sw_model().

Usage

sw_model_plot(
  x,
  bar_fill = "steelblue3",
  bar_color = "grey60",
  line_color = "red3"
)

Arguments

x

Output of sw_model().
bar_fill

Fill color for the bars (original data).
bar_color

Line color for the bars (original data).
line_color

Line color for the fitted distribution.

Value

A ggplot-style graph.

Examples

tmp <- sw_model(
  sw_data = "Hollstein_1980",
  densfun = "lognormal",
  cred_mass = .95,
  plot = FALSE
)
sw_model_plot(tmp,
              bar_fill = "forestgreen",
              bar_color = "darkgreen",
              line_color = "tomato3")

Compute the summed probability of multiple felling date ranges

Description

Computes the summed probability density (SPD) for a set of felling date ranges.

Usage

sw_sum(
  x,
  series = "series",
  last = "last",
  n_sapwood = "n_sapwood",
  waneyedge = "waneyedge",
  sw_data = "Hollstein_1980",
  densfun = "lognormal",
  cred_mass = 0.954,
  plot = FALSE,
  scale_p = FALSE
)

Arguments

x

A data.frame with columns c("series", "swr", "waneyedge" , "last"), Column "sw_model" is optional. Could be the output of read_fh(x, header = TRUE)
series

Name of the column in x where ID's of the tree-ring series are listed as character values.
last

Name of the column in x where calendar years assigned to the last measured ring are listed (should be numeric).
n_sapwood

Name of the column in x where the number of observed sapwood rings are listed (should be numeric)
waneyedge

Name of the column in x indicating the presence (TRUE)/absence (FALSE) of waney edge (should be a logical).
sw_data

The name of the sapwood data set to use for modelling. It should be one of the data sets listed in sw_data_overview(), or the name of a data.frame with sapwood data in columns n_sapwood and count.
densfun

Name of the density function fitted to the sapwood data set. Should be one of:

  • lognormal (the default value),

  • normal,

  • weibull,

  • gammma.

cred_mass

A scalar [0, 1] specifying the mass within the credible interval (default = .954).
plot

A logical.

  • If TRUE, sw_sum_plot() is triggered and a ggplot-style graph is returned with the summed probability density (SPD).

  • If FALSE, a list with the numeric output of the modelling process is returned.

scale_p

A logical. If TRUE the summed probability density is scaled to 1 (default).

Value

Depends on the value of plot.

See Also

sw_sum_plot()

Examples

trs_example7

sw_sum(trs_example7, densfun = "lognormal", cred_mass = 0.63, plot = FALSE)

Plot the output of sw_sum()

Description

This function plots the result of sw_sum() - both the SPD and the occurrence of exact felling dates - and adds a smoothing spline to the SPD.

Usage

sw_sum_plot(
  x,
  bar_col = "steelblue",
  trend_col = "red3",
  dot_col = "steelblue4",
  dot_size = 2,
  dot_shape = 21,
  window_smooth = 11
)

Arguments

x

The output of sw_sum().
bar_col

The fill color for the bars.
trend_col

The line color of the fitted smoothing spline.
dot_col

The color of the shapes that represent exact felling dates.
dot_size

A size argument for the shapes that represent exact felling dates.
dot_shape

Number corresponding to the point symbol available in R for the shapes that represent exact felling dates.
window_smooth

A numeric value for the window width of the trend line

Value

A ggplot style graph, with calendar years on the X-axis and the probability (p) on the Y-axis.

Examples

trs_example6 <- trs_example6
trs_example6
tmp <- sw_sum(trs_example6)
sw_sum_plot(tmp, bar_col = "burlywood1",
                 trend_col = "brown",
                 dot_col = "orange",
                 dot_shape = 23, dot_size = 5)

Example dataset 0

Description

A dataset in which all series have preserved sapwood. Unconventional variable names.

Usage

trs_example0

Format

A tibble of 4 variables:

trs

unique ID of the tree-ring series

end

calendar year assigned to the last measured ring

swr

number of observed sapwood rings

bark

waney edge present TRUE/FALSE

Examples

trs_example0

Example dataset 1

Description

A dataset in which all series have preserved sapwood rings.

Usage

trs_example1

Format

A tibble of 4 variables:

series

unique ID of the tree-ring series

last

calendar year assigned to the last measured ring

n_sapwood

number of observed sapwood rings

waneyedge

waney edge present TRUE/FALSE

Examples

trs_example1

Example dataset 2

Description

A dataset in which one series has an exact felling date (= waney edge present).

Usage

trs_example2

Format

A tibble of 4 variables:

series

unique ID of the tree-ring series

last

calendar year assigned to the last measured ring

n_sapwood

number of observed sapwood rings

waneyedge

waney edge present TRUE/FALSE

Examples

trs_example2

Example dataset 3

Description

A dataset with multiple exact felling dates.

Usage

trs_example3

Format

A tibble of 4 variables:

series

unique ID of the tree-ring series

last

calendar year assigned to the last measured ring

n_sapwood

number of observed sapwood rings

waneyedge

waney edge present TRUE/FALSE

Examples

trs_example3

Example dataset 4

Description

A combination of series with and without sapwood rings.

Usage

trs_example4

Format

A tibble of 4 variables:

series

unique ID of the tree-ring series

last

calendar year assigned to the last measured ring

n_sapwood

number of observed sapwood rings

waneyedge

waney edge present TRUE/FALSE

Examples

trs_example4

Example dataset 5

Description

None of the series in this dataset have preserved sapwood rings.

Usage

trs_example5

Format

A tibble of 4 variables:

series

unique ID of the tree-ring series

last

calendar year assigned to the last measured ring

n_sapwood

number of observed sapwood rings

waneyedge

waney edge present TRUE/FALSE

Examples

trs_example5

Example dataset 6

Description

A test dataset for sw_sum().

Usage

trs_example6

Format

A tibble of 4 variables:

series

unique ID of the tree-ring series

last

calendar year assigned to the last measured ring

n_sapwood

number of observed sapwood rings

waneyedge

waney edge present TRUE/FALSE

Examples

trs_example6

Example dataset 7

Description

A test dataset for sw_sum().

Usage

trs_example7

Format

A tibble of 4 variables:

series

unique ID of the tree-ring series

last

calendar year assigned to the last measured ring

n_sapwood

number of observed sapwood rings

waneyedge

waney edge present TRUE/FALSE

Examples

trs_example7

van Daalen (unpublished) sapwood data set.

Description

Sapwood data set for historical timbers found in the Netherlands en Belgium, with a local provenance. Unpublished data by S. van Daalen (version 19 Dec 2022, Van Daalen Dendrochronologie - <www.dendro.nl>).

Usage

vanDaalen_NLBE

Format

A tibble of 2 variables:

n_sapwood

number of sapwood rings

count

number of times n_sapwood was observed

Details

sample size = 644 observations

Source

S. van Daalen, unpublished dataset (version: 19 Dec 2022).

Examples

sw_data_info("vanDaalen_NLBE")

sw_model("vanDaalen_NLBE", plot = TRUE)

van Daalen (unpublished) sapwood data set.

Description

Sapwood data set for historical timbers found in the Netherlands that were imported from Norway. Unpublished data by S. van Daalen (version 19 Dec 2022, Van Daalen Dendrochronologie - <www.dendro.nl>).

Usage

vanDaalen_Norway

Format

A tibble of 2 variables:

n_sapwood

number of sapwood rings

count

number of times n_sapwood was observed

Details

sample size = 104 observations

Source

S. van Daalen, unpublished dataset (version: 19 Dec 2022).

Examples

sw_data_info("vanDaalen_Norway")

sw_model("vanDaalen_Norway", plot = TRUE)

Wazny 1990 sapwood data set.

Description

Sapwood data set for Poland, published by Wazny in 1990.

Usage

Wazny_1990

Format

A tibble of 2 variables:

n_sapwood

number of sapwood rings

count

number of times n_sapwood was observed

Details

sample size = 206 observations

Source

Wazny T. 1990. Aufbau und Anwendung der Dendrochronologie für Eichenholz in Polen (PhD dissertation). Hamburg University, Hamburg.

Examples

sw_data_info("Wazny_1990")

sw_model("Wazny_1990", plot = TRUE)