Developing the R package dendroNetwork for dendro-archaeology: lessons learned

Ronald M. Visser

Content

  • Open Science
  • Research
    • Developing a new method
      • Problem: Wood provision unknown
      • Solution: Dendrochronological provenance patterns
  • Package
    • ROpenSci
    • Creation
    • Review
    • Dissemination
  • Conclusions + recommendations

Open Science

  • Open scientific knowledge
  • Open science infrastructures
  • Open engagement of societal actors
  • Open dialogue with other knowledge systems

UNESCO. 2021. UNESCO Recommendation on Open Science. Paris: United Nations Educational, Scientific and Cultural Organization. DOI: https://doi.org/10.54677/MNMH8546.

Open Science pillars

Research

Research context: Roman wood provision

  • Many finds of wood from Roman period
  • Archaeological context known
  • Provenance of wood unknown

Main research question

  • How was the procurement of wood organised in the German provinces of the Roman empire during first four centuries AD?

Dendrochronology

  • Annual ring of wood around tree
  • Tree ring width depends on
    • Soil
    • (micro)Climate
    • Local factors
    • Disturbance
  • Growth season: spring and summer

Dendroprovenance

Provenance of wood based on comparison tree-ring curves with calenders

Problems

  • Often based on single measure
  • Comparison individual curves
  • Complex with large datasets
  • Clustering problems common interval

Solution: network analyses

Dendrochronological networks

  • Nodes: Site chronologies (tree ring data)
  • Edges: statistical similarity
    • Correlation (r ≥ 0,5)
    • Overlapping tree rings (n ≥ 50)
    • SGC (% (Improved statistic, formerly Gleichläufigkeit: ≥ 70%)
    • Probability of exceedence (p, <= 0.0001)

Provenance in network

  • Closer in network = similar growth conditions
  • Communities share growth conditions
  • Assess spatial distances
  • Contexts

Open Science in research

Publication: Open Access

  • Visser, RM. 2021 Dendrochronological Provenance Patterns. Network Analysis of Tree-Ring Material Reveals Spatial and Economic Relations of Roman Timber in the Continental North-Western Provinces. Journal of Computer Applications in Archaeology 4(1): 230–253. DOI: https://doi.org/10.5334/jcaa.79.
  • Visser, RM and Vorst, Y. 2022b Connecting Ships: Using Dendrochronological Network Analysis to Determine the Wood Provenance of Roman-Period River Barges Found in the Lower Rhine Region and Visualise Wood Use Patterns. International Journal of Wood Culture 3(1–3): 123–151. DOI: https://doi.org/10.1163/27723194-bja10014.

Scripts and data: Open

  • Visser, RM. 2022 Dendrochronological Provenance Patterns. Code and Data of Network Analysis of Tree-Ring Material. DOI: https://doi.org/10.5281/zenodo.10200361.
  • Visser, RM and Vorst, Y. 2022a Analyses, data and figures related to: ‘Connecting ships: using dendrochronological network analysis to determine the wood provenance of Roman-period river barges found in the Lower Rhine region and to visualise patterns of wood use’. DOI: https://doi.org/10.5281/zenodo.7243539.

Everything open and accessible

Open Science and reproducibility

  • Scripts available
  • Comments available
  • Hard to use for others

Package enables reuse of method for other purposes

Package: do we need another?

Package: do we need another?

Workflow idea behind package use

Learning and starting out

  • https://devguide.ropensci.org/

  • https://r-pkgs.org/

  • https://carpentries-incubator.github.io/lesson-R-packaging/

rOpenSci

rOpenSci

  • Creating technical infrastructure in the form of carefully vetted, staff and community-contributed R software tools that lower barriers to working with scientific data sources on the web
  • Making the right data, tools and best practices more discoverable
  • Creating social infrastructure through a welcoming and diverse community
  • Promoting advocacy for a culture of data sharing and reusable software
  • Building capacity of software users and developers and fostering a sense of pride in their work

https://ropensci.org/

## Resources: rOpenSci and others

Package: Creating functions

  • Converting scripts to functions
  • Naming functions
    • snake_case
    • object_verb()
    • existing names
  • Simple programming
    • Loops
    • Assigning variables
    • Logical thinking

Package: Creating documentation

  • Manual pages

  • Vignettes

Package: Manual pages source

Package: Manual pages (online)

Package: Vignette source

Package: Vignette webpage

Package: Creating tests

  • check input
  • check results
  • check functions

testthat package!

Package: Continous integration

“Continuous integration automatically runs tests on software. In the case of rOpenSci, CI practically means that a set of tests will be automatically run via GitHub, every time that you make a commit or pull request to GitHub.”

https://devguide.ropensci.org/pkg_ci.html

  • usethis package!
  • Github Actions

Package: Review

  • Github issue: https://github.com/ropensci/software-review/
  • Developers test your package
  • Feedback
  • Improvement of code
  • Improvement of documentation
  • Open peer review

Package: Dissemination

  • Source: https://github.com/ropensci/dendroNetwork/
  • Documentation: https://docs.ropensci.org/dendroNetwork/
  • CRAN: https://cran.r-project.org/package=dendroNetwork
  • Blog: https://ropensci.org/blog/2024/06/06/from-scripts-to-package/
  • Social media: Mastodon, LinkedIn, Facebook..
  • Write paper (still to publish)

Conclusions + recommendations

Creating a package is a challenge, but fun!

  • Be nice, and share and document your code!
  • Develop functions not scripts.
  • Develop a package from the start, especially when devising a new method(ology).
  • Read the documentation (or: RTFM)
  • Submit to rOpenSci and enjoy!

References

Visser, RM. 2021a Dendrochronological Provenance Patterns. Network Analysis of Tree-Ring Material Reveals Spatial and Economic Relations of Roman Timber in the Continental North-Western Provinces. Journal of Computer Applications in Archaeology 4(1): 230–253. DOI: https://doi.org/10.5334/jcaa.79.

Visser, RM. 2021b On the similarity of tree-ring patterns: Assessing the influence of semi-synchronous growth changes on the Gleichläufigkeitskoeffizient for big tree-ring data sets. Archaeometry 63(1): 204–215. DOI: https://doi.org/10.1111/arcm.12600.

Visser, RM. 2024 dendroNetwork: a R-package to create dendrochronological networks. DOI: https://doi.org/10.5281/zenodo.10636310.

Visser, RM. forthcoming (2025). Relating Roman Rings. An interdisciplinary study using archaeology, data science and tree rings to understand timber provision in the German Provinces of the Roman Empire. PhD Thesis. Amsterdam: Vrije Universiteit.

Visser, RM and Vorst, Y. 2022 Connecting Ships: Using Dendrochronological Network Analysis to Determine the Wood Provenance of Roman-Period River Barges Found in the Lower Rhine Region and Visualise Wood Use Patterns. International Journal of Wood Culture 3(1–3): 123–151. DOI: https://doi.org/10.1163/27723194-bja10014.

rOpenSci in general

Source of these slides: https://github.com/RonaldVisser/dendroNetwork_presentation_JCM_CAA

JCM CAA-NLFl CAA-DE: 2024-10-23