---
output: github_document
bibliography: inst/REFERENCES.bib
---

<!-- README.md is generated from README.Rmd. Please edit that file -->

```{r setup, echo = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>",
  fig.path = "README-"
)
```

```{r packages, echo = FALSE, include=FALSE}
# packages
library(magrittr)
library(stringr)
library(purrr)
```


```{r metadata-manuscript, echo = FALSE, include=FALSE}
# Manuscript metadata
manuscript1_yaml <- rmarkdown::yaml_front_matter("analysis/paper/001-paper-main.Rmd")
manuscript2_yaml <- rmarkdown::yaml_front_matter("analysis/paper/002-reply-main.Rmd")

## info to display

# manuscript1
manuscript1 <- list()
manuscript1$authors <-
  manuscript1_yaml$author %>%
  purrr::map_chr(function(x) paste0(x$given_name, " ", x$surname)) %>%
  knitr::combine_words()

manuscript1$year <- 
  paste0("(",  eval(parse(text = stringr::str_extract(manuscript1_yaml$date, pattern = "^\\d+"))), "):")

manuscript1$title <-
  manuscript1_yaml$title %>%
  paste0(".")

manuscript1$journal <-
  eval(parse(text = manuscript1_yaml$journal %>% stringr::str_remove("^`r ") %>% stringr::str_remove("`$"))) %>%
  names()

manuscript1$doi <-
  manuscript1_yaml$doi %>%
  paste0(".")

# manuscript2
manuscript2 <- list()
manuscript2$authors <- "Henning Teickner and Klaus-Holger Knorr"

manuscript2$year <- 
  paste0("(",  eval(parse(text = stringr::str_extract(manuscript2_yaml$date, pattern = "^\\d+"))), "):")

manuscript2$title <-
  manuscript2_yaml$title %>%
  paste0(".")

manuscript2$journal <-
  eval(parse(text = manuscript2_yaml$journal %>% stringr::str_remove("^`r ") %>% stringr::str_remove("`$"))) %>%
  names()

manuscript2$doi <-
  manuscript2_yaml$doi %>%
  paste0(".")
```

[![DOI](https://zenodo.org/badge/465653387.svg)](https://zenodo.org/badge/latestdoi/465653387) ![Last-changedate](https://img.shields.io/badge/last%20change-`r gsub('-', '--', Sys.Date())`-brightgreen.svg)

# hklmirs

This repository contains the data and code for our two manuscripts (in preparation):

> `r paste(manuscript1$authors, "(in preparation):", manuscript1$title)`

> `r paste(manuscript2$authors, "(in preparation):", manuscript2$title)`

### How to cite

Please cite this compendium as:

> Henning Teickner and Klaus-Holger Knorr, (`r format(Sys.Date(), "%Y")`). _Compendium of R code and data for "`r manuscript1_yaml$title`" and "`r manuscript2_yaml$title`"_. Accessed `r format(Sys.Date(), "%d %b %Y")`. Online at <https://doi.org/10.5281/zenodo.6325760>


## Contents

The **analysis** directory contains:

- [:file\_folder: paper](/analysis/paper): R Markdown source documents needed to reproduce the manuscript, including figures and tables. The main script is [001-paper-main.Rmd](analysis/paper/001-paper-main.Rmd). This script produces both manuscripts and the corresponding supplementary information. Additional scripts are:  
    - [002-paper-m-original-models.Rmd](analysis/paper/002-paper-m-original-models.Rmd): Computes the original models used in @Hodgkins.2018 and models with the same model structure, but as Bayesian models.  
    - [003-paper-m-gaussian-beta.Rmd](analysis/paper/003-paper-m-gaussian-beta.Rmd): Computes models assuming a Beta distribution for holocellulose and Klason lignin contents and compares them to the original models.
    - [004-paper-m-reduce-underfitting.Rmd](analysis/paper/004-paper-m-reduce-underfitting.Rmd): Extents the Beta regression models by including additional variables (additional peaks) or using a different approach (using measured spectral intensities of binned spectra instead of extracted peaks), and validates these models using LOO-CV.
    - [005-paper-m-minerals.Rmd](analysis/paper/005-paper-m-minerals.Rmd): Uses the models from `003-paper-m-gaussian-beta.Rmd` to test how accurate a model for holocellulose content is which is also calibrated on training samples with higher mineral contents.
    - [006-paper-m-prediction-domain.Rmd](analysis/paper/006-paper-m-prediction-domain.Rmd): Analyzes the prediction domain [@Wadoux.2021] of the original models and the modified models and identifie under which conditions models extrapolate for peat and vegetation smaples from @Hodgkins.2018.
    - [007-paper-m-prediction-differences.Rmd](analysis/paper/007-paper-m-prediction-differences.Rmd): Compares predictions for the training data and the peat and vegetation data from @Hodgkins.2018 for the original models from @Hodgkins.2018 and the modified models from `004-paper-m-reduce-underfitting.Rmd`.
    - [008-paper-supplementary.Rmd](analysis/paper/008-paper-supplementary.Rmd): Computes supplementary analyses and figures for the first manuscript.
    - [001-reply-main.Rmd](analysis/paper/001-reply-main.Rmd): This is the main script for manuscript 2. It is run from within `001-paper-main.Rmd` and produces the supplementary information for manuscript 2.
    - [002-reply-main.Rmd](analysis/paper/002-reply-main.Rmd): This script produces the document for manuscript 2. It is run from within `001-reply-main.Rmd`.
    
- [:file\_folder: data](/analysis/data): Data used in the analysis. Note that raw data is not stored in [:file\_folder: raw_data](/analysis/data/raw_data) (empty folder), but in [:file\_folder: /inst/extdata](/inst/extdata). [:file\_folder: derived_data](/analysis/data/derived_data) contains derived data computed from the scripts. The raw data are derived from @Hodgkins.2018.

- [:file\_folder: stan_models](/analysis/stan_models): The Stan model used in `001-reply-main.Rmd`.

The other folders in this directory follow the standard naming scheme and function of folders in R packages. There are the following directories and files:  

- `README.md`/`README.Rmd`: Readme for the compendium.  
- `DESCRIPTION`: The R package DESCRIPTION file for the compendium.  
- `NAMESPACE`: The R package NAMESPACE file for the compendium.  
- `LICENSE.md`: Details on the license for the code in the compendium.  
- `CONTRIBUTING.md` and `CONDUCT.md`: Files with information on how to contribute to the compendium.  
- `Dockerfile`: Dockerfile to build a Docker image for the compendium.  
- `.Rbuildignore`, `.gitignore`, `.dockerignore`: Files to ignore during R package building, to ignore by Git, and to ignore while building a Docker image, respectively.  
- `renv.lock`: renv lock file (Lists all R package dependencies and versions and can be used to restore the R package library using renv). `renv.lock` was created by running     `renv::snapshot()` in the R package directory and it uses the information included in the `DESCRIPTION` file.  
- `.Rprofile`: Code to run upon opening the R-project.  
- `R`, `man`, `inst`, `data-raw`, `data`, `src`: Default folders for making the R package run.
- Folder `inst/extdata`: Folder with the raw data used for the analyses. All files in this folder are derived from @Hodgkins.2018.  
    

## How to run in your broswer or download and run locally

You can download the compendium as a zip from from these URLs: <https://github.com/henningte/hklmirs/> or <https://doi.org/10.5281/zenodo.6325760>

Or you can install this compendium as an R package, hklmirs, from GitHub with:

```{r installation, eval=FALSE}
remotes::install_github("henningte/hklmirs")
```


## How to use

#### Reproduce the analyses

To reproduce the analyses for the paper, open the Rstudio project included in this research compendium and run the Rmarkdown script in `analysis/paper/001-paper-main.rmd`.

Running the whole script takes about 12 hours and occupies additional disk space of ~2 Gb.  

Alternatively, the [Dockerfile](Dockerfile) can be used to build a Docker image from which all analyses can be reproduced. The Dockerfile ensures that all required dependencies are installed (e.g. specific R packages; this is managed using the R package [renv](https://rstudio.github.io/renv/articles/renv.html)).  

The [Dockerfile](Dockerfile) provides instructions how to build a Docker image from the Dockerfile and how to run the image in a Docker container. It occupies disk space of ~7 Gb.

When the Docker image runs in a container, go to `localhost:8787` in your Browser. You will find an RStudio interface where you can log in with username `rstudio` and password `hkl`. Here you can find the Rmarkdown scripts (`hklmirs/analysis/paper/001-paper-main.rmd`) as described above.  


### Licenses

**Text and figures :**  [CC-BY-4.0](http://creativecommons.org/licenses/by/4.0/)

**Code :** See the [DESCRIPTION](DESCRIPTION) file

**Data :** [CC-0](http://creativecommons.org/publicdomain/zero/1.0/) attribution requested in reuse. See the sources section for licenses for data derived from external sources and how to give credit to the original author(s) and the source.


### Sources

All files in `inst/extdata` are derived from @Hodgkins.2018. These data are licensed under the [CC-BY 4.0](http://creativecommons.org/licenses/by/4.0/) license (see https://www.nature.com/articles/s41467-018-06050-2#rightslink).

The format of this research compendium is inspired by @Marwick.2018 and was created with rrtools [@Marwick.2019]. The Rmarkdown template for the main article is from the rticles package [@Allaire.2020].

### Contributions

We welcome contributions from everyone. Before you get started, please see our [contributor guidelines](CONTRIBUTING.md). Please note that this project is released with a [Contributor Code of Conduct](CONDUCT.md). By participating in this project you agree to abide by its terms.

### Funding

This study was funded by the Deutsche Forschungsgemeinschaft (DFG, German Research Foundation) grant no. KN 929/23-1 to Klaus-Holger Knorr and grant no. PE 1632/18-1 to Edzer Pebesma. We acknowledge support from the Open Access Publication Fund of the University of Münster.

### References


