---
title: "Get started with RCarb"
author: "Sebastian Kreutzer<sup>1,2</sup> & Barbara Mauz<sup>3</sup>"
date: "Last modified: `r Sys.Date()` ('RCarb' version: `r packageVersion('RCarb')`)"
output: 
  rmarkdown::html_vignette:
  self-contained: yes
  toc: yes
  toc_depth: 4
  number_sections: yes
standalone: yes
vignette: >
  %\VignetteEncoding{UTF-8}
---

<sup>1</sup>Institute of Geography, Universität Heidelberg, Germany<br>
<sup>2</sup>Archéosciences Bordeaux, UMR 6034, CNRS-Université Bordeaux Montaigne (France)<br>
<sup>3</sup>Department of Geography and Geology, University of Salzburg, Salzburg (Austria)"

```{r, echo = FALSE, fig.align='center', out.width=100}
knitr::include_graphics("../man/figures/Logo_RCarb.svg")
```

# Scope

Getting started with a new **R** package can be a very tedious business (if not to say annoying). 
This document was written with the intention to make your first steps as painless as possible. 

# Quick start with the example dataset

If you have no idea what a function does and how it works, it is always a good idea to have a 
closer look into the example sections of the package functions. The package `'RCarb'` has 
one central function named `model_DoseRate()`. The example given in the example section in 
the manual will be used in the following to illustrate the central package functionality in 
three steps.

## Load 'RCarb'
```{r}
library(RCarb)
```

## Load example data

```{r}
##load example data
data("Example_Data", envir = environment())
```

To get a first impression on how the example dataset looks like, you call the function `head()` to
print the first five rows of a `data.frame` on the terminal.

```{r}
head(Example_Data)
```

Unfortunately, the naming of the table columns is not straightforward to understand. The good news 
is that each column carries additional information that can be seen in the **R** terminal by 
typing, e.g., for the column 'K' (which is the 2nd column):

```{r}
attributes(Example_Data$K)
```

It reveals that the numbers in the column correspond to the potassium concentration and are
given in '%'. Similar all other columns can be inspected.

And here the full overview
```{r, echo=FALSE, message=FALSE}
##extract attributes
attributes <- lapply(1:ncol(Example_Data), function(x) attributes(Example_Data[[x]]))
attributes <- as.data.frame(data.table::rbindlist(attributes), stringAsFactors = FALSE)

df <- cbind(COLUM = colnames(Example_Data), attributes)
knitr::kable(df)
```

## Run dose rate modelling

Now we want to start the modelling using the data given for the first sample only.

```{r, fig.height=7, fig.width=5, fig.align='center'}
##extract only the first row 
data <- Example_Data[1,]

##run model 
results <- model_DoseRate(
  data = data,
  DR_conv_factors = "Carb2007",
  n.MC = 10, 
  txtProgressBar = FALSE)
```

The function returns a terminal output along with two plots, which are mostly similar to the
original graphical output provided by the 'MATLAB' program 'Carb'. 

In the example above the function `model_DoseRate()` was called with three additional 
arguments, `DR_conv_factors = "Carb2007"`, `n.MC = 10`, `txtProgressBar = FALSE`. The first
argument selects the dose rate conversion factors used by 'RCarb'. The second argument limits the number of 
Monte Carlo runs for the error estimation to 10 and the second argument prevents the plotting of the progress bar, indicating the progression of the calculation. Both arguments were solely set to reduce calculation time and output in this vignette.

Obviously, you do not want to run each row in the input table separately to model all dose rates,
so to run all the modelling for all samples in the example dataset you can call the model without subsetting the dataset first. **Be careful, the calculation may take some time**.

```{r, eval = FALSE}
results <- model_DoseRate(
  data = Example_Data)
```

*A note on the used dose rate conversion factors: For historical reasons 'Carb' has its own set of dose rate
conversion factors, which differ slightly from values in the literature (e.g., Adamiec \& Atiken, 1998)
and are used in `'RCarb'` as default values. However, with `'RCarb' >= 0.1.3` you can select other dose rate conversion factors. Please type `?RCarb::Reference_Data` in your **R** terminal for further details.*

# Using your own dataset

Running only the example dataset is somewhat dissatisfactory, and the usual case will be that
you provide your own dataset as input. While you can enter all data directly using R, the package
offers another way, using external spreadsheet software such as 'Libre Office' (or, of course, MS Excel).
The procedure is sketched in the following. 

## Create template table

The function `write_InputTemplate()` was written to create a template table (a CSV-file) that 
can be subsequently opened and filled. Using the function ensures that your input data have the 
correct structure, e.g., the correct number for columns and column names. 

```{r}
write_InputTemplate(file = "files/RCarb_Input.csv")
```

The path given with the argument `file` can be modified as needed.

## Enter own data & back import into R

Own data are added using an external spreadsheet program and then save again as CSV-file. 

```{r, fig.align='center', echo = FALSE, out.width = "400px"}
knitr::include_graphics(path = "files/Screenshot.png")
```

For re-importing, the data standard R functionality can be used. 

```{r}
data <- read.csv(file = "files/RCarb_Input.csv")
```

## Model the dose rate

The final modelling does not differ from the call already show above (here without a plot output):

```{r, fig.height=7, fig.width=6, fig.align='center'}
##run model 
results <- model_DoseRate(
  data = data,
  n.MC = 10, 
  txtProgressBar = FALSE, 
  plot = FALSE)
```


# I don't like R

Well, then you are wrong here. However, if you are just tired of using the **R** terminal and you want to have a graphical user interface to interact with 'RCarb'? Surprise: We also spent countless hours to develop a shiny application called 'RCarb app', and we ship it as part of the **R** package ['RLumShiny'](https://CRAN.R-project.org/package=RLumShiny).

## References {-}

Adamiec, G., Aitken, M.J., 1998. Dose-rate conversion factors: update. Ancient TL 16, 37–50. http://ancienttl.org/ATL_16-2_1998/ATL_16-2_Adamiec_p37-50.pdf
