added vignette on dendrochronological data

Author: RonaldVisser

NEWS.md

@@ -13,6 +13,7 @@
 ### Documentation fixes
 
 -   added descriptions of Cytoscape in the readme and vignettes
+-   added vignette: dendrochronological_data which describes the data to be used.
 
 ### Continous integration
 

R/RING_Visser_2021.R

@@ -1,4 +1,4 @@
-#' Roman tree-ring site chronologies from Hollstein
+#' Roman tree-ring site chronologies
 #'
 #' Dendrochronological site chronologies published by Visser (2021, 2022). These (pre) Roman site chronologies date between 520 BC and AD 663 and are based on the material of RING (full references to the source data can be found in the supplementary data of Visser 2021)
 #' The series are named based on their location, species and type of standardisation

man/RING_Visser_2021.Rd

@@ -17,7 +17,7 @@ The package is written for dendrochronologists and have a general knowledge on t
 
 The package aims to make the creation of dendrochronological (provenance) networks as easy as possible. To be able to make use of all options, it is assumed that Cytoscape [@shannon2003] is installed (<https://cytoscape.org/>). Cytoscape is open source software and platform independent and provides easy visual access to complex networks, including the attributes of both nodes and edges in a network (see the [Cytoscape-website](https://cytoscape.org/what_is_cytoscape.html) for more information). Some data is included in this package, namely the Roman data published by Hollstein [@hollstein1980].
 
-The first steps are visualized in the flowchart below, including community detection using either (or both) the Girvan-Newman algorithm [@girvan2002] and Clique Percolation Method [@palla2005] for all clique sizes. Both methods are explained very well in the papers, and on wikipedia for both [CPM](https://en.wikipedia.org/wiki/Clique_percolation_method) and the [Girvan-Newman algorithm](https://en.wikipedia.org/wiki/Girvan%E2%80%93Newman_algorithm).
+The first steps are visualized in the flowchart below, including community detection using either (or both) the Girvan-Newman algorithm [@girvan2002] and Clique Percolation Method [@palla2005] for all clique sizes. Both methods are explained very well in the papers, and on wikipedia for both [CPM](https://en.wikipedia.org/wiki/Clique_percolation_method) and the [Girvan-Newman algorithm](https://en.wikipedia.org/wiki/Girvan%E2%80%93Newman_algorithm). More information on the dendrochronological data can be found in a separate [vignette](dendrochronological_data.html).
 
 ```{r flowchart_workflow, echo=FALSE, fig.width=5}
 DiagrammeR::grViz("

vignettes/dendroNetwork.Rmd

@@ -0,0 +1,44 @@
+---
+title: "dendrochronological data"
+output: rmarkdown::html_vignette
+vignette: >
+  %\VignetteIndexEntry{dendrochronological_data}
+  %\VignetteEngine{knitr::rmarkdown}
+  %\VignetteEncoding{UTF-8}
+bibliography: references.bib
+---
+
+```{r, include = FALSE}
+knitr::opts_chunk$set(
+  collapse = TRUE,
+  comment = "#>"
+)
+```
+
+```{r setup}
+library(dendroNetwork)
+```
+
+# Dendrochronological data (or tree-ring data)
+
+The package dendroNetwork is based on using dendrochronological (or tree-ring) data. This data is the input for creating networks and uses the same data format as used in dplR [@bunn2008]. The base format is rwl-format as described here: <https://www.ncei.noaa.gov/pub/data/paleo/treering/treeinfo.txt>. This data can be imported into R using `dplR::read.tucson("filename.rwl")` . The resulting dataframe has the series in columns and the years as rows, as shown below for a selection of data from one of the sample data sets in `dendroNetwork::hol_rom[400:410,1:4]` :
+
+```{r, echo=FALSE}
+knitr::kable(hol_rom[400:410,1:4])
+```
+
+The row names are the years to which the tree rings are dated, in this case the years -103 to -93, in other words 102 to 92 BCE (the year 0 does not exist, only mathematically). The column headers are the identification or names of the tree-ring series. The values represent the width of a tree ring in millimeters. While dendroNetwork is written based on measurements of tree-ring widths, other time series with a similar rwl-format can also be used as input.
+
+The packages comes with two sample data sets to try the package.
+
+## hol_rom: Roman tree-ring site chronologies from Hollstein
+
+These are dendrochronological site chronologies published by Ernst Hollstein in the 1970s and 1980s [@hollstein1972; @hollstein1980]. These 52 (pre) Roman site chronologies date between 502 BC and AD 550. This selection of (pre)Roman site-chronologies was also used in an earlier study.
+
+## RING_Visser_2021: Roman tree-ring site chronologies
+
+Dendrochronological site chronologies published earlier [@visser; @visser2021a]. These (pre) Roman site chronologies date between 520 BC and AD 663 and are based on the material from RING (full references to the source data can be found in the [supplementary data](https://github.com/RonaldVisser/ProvenanceNetworks/blob/master/SupplementaryTables/Supplementary_table_1a_DOI_data.csv) [@visser2021a].
+
+The series are named based on their location, species and type of standardisation For example: ABC_Q1M or ABC_Q1C consist of the same material from the site ABC (Abcoude), species Q(uercus), chronology 1 and standardisation C(ofecha) and M(eans). See Visser(2021) for more explanation.
+
+# References

vignettes/dendrochronological_data.Rmd

@@ -118,3 +118,50 @@ @book{cook1990
 	publisher = {Kluwer Academic Publishers},
 	address = {Dordrecht}
 }
+
+@article{bunn2008,
+	title = {A dendrochronology program library in R (dplR)},
+	author = {Bunn, Andrew G},
+	year = {2008},
+	month = {10},
+	date = {2008-10},
+	journal = {Dendrochronologia},
+	pages = {115{\rule{1em}{1pt}}124},
+	volume = {26},
+	number = {2},
+	doi = {https://doi.org/10.1016/j.dendro.2008.01.002},
+	url = {https://www.sciencedirect.com/science/article/abs/pii/S1125786508000350}
+}
+
+@article{hollstein1972,
+	title = {Dendrochronologische Datierung von Hölzern aus Wederath (Belginum)},
+	author = {Hollstein, Ernst},
+	year = {1972},
+	date = {1972},
+	journal = {Trierer Zeitschrift},
+	pages = {123--125},
+	volume = {35}
+}
+
+@misc{visser,
+	title = {Dendrochronological Provenance Patterns. Code and Data of Network Analysis of Tree-Ring Material},
+	author = {Visser, Ronald M.},
+	doi = {10.5281/zenodo.10200361}
+}
+
+@article{visser2021a,
+	title = {Dendrochronological Provenance Patterns. Network Analysis of Tree-Ring Material Reveals Spatial and Economic Relations of Roman Timber in the Continental North-Western Provinces},
+	author = {Visser, Ronald M.},
+	year = {2021},
+	month = {11},
+	date = {2021-11-26},
+	journal = {Journal of Computer Applications in Archaeology},
+	pages = {230--253},
+	volume = {4},
+	number = {1},
+	doi = {10.5334/jcaa.79},
+	url = {http://journal.caa-international.org/article/10.5334/jcaa.79/},
+	note = {Number: 1
+Publisher: Ubiquity Press},
+	langid = {en}
+}