README.Rmd

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

```{r, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>",
  fig.path = "man/figures/README-",
  out.width = "100%",
  dpi = 300, 
  fig.width = 15
)
```

# ageR: Supervised Age Modelling
<!-- <img src="inst/images/logo.png" alt="logo" align="right" height=200px/> -->

<!-- badges: start -->
`r badger::badge_devel("special-uor/ageR", "yellow")`
`r badger::badge_github_actions("special-uor/ageR")`
`r badger::badge_doi("10.5281/zenodo.4636715", "black")`
`r badger::badge_cran_release("ageR", "red")`
<!-- `r badger::badge_codecov("special-uor/ageR", "Q6SYL7AOGR")` -->
<!-- badges: end -->

The goal of ageR is to provide functions that facilitate the creation of age 
models using different data sources, including databases, comma and tab 
separated files.

## Installation

<!-- You can install the released version of ageR from [CRAN](https://CRAN.R-project.org) with: -->

<!-- ``` r -->
<!-- install.packages("ageR") -->
<!-- ``` -->

You can install the development version from 
[GitHub](https://github.com/special-uor/ageR) with:
``` r
# install.packages("remotes")
remotes::install_github("special-uor/ageR", "dev")
```

## Example
:warning: __Users of Windows:__ `ageR::Bacon` creates symbolic links (think of them as shortcuts), you should run RStudio in "Administrator mode" to avoid error messages.

### Bacon model
#### Input structure
For an entity X, the input structure should look like
```{r bacon-file-structure}
ageR::file_structure(entity = "X", am = "bacon")
```

The function `ageR::create_input` can be used to automatically create the 
appropriate file structure (as shown previously).

#### Create input structure
1. Start by creating a data frame for the sampling depths, this should have two 
numeric columns called `id` and `depth`:
    ```{r bacon-create-input-step1}
    sample_depths <- data.frame(id = 1:100,
                                depth = seq(0, 500, length.out = 100))
    knitr::kable(head(sample_depths))
    ```

2. Create a data frame with the core's data, this should have at least four 
columns. The first column can be of character type and the remaining must be
numeric. The column names should be `labID`, `age`, `error`, and `depth`. 
Optionally, a fifth column, `cc`, can be included to manually select the 
calibration curve for each observation.
    ```{r bacon-create-input-step2}
    core <- data.frame(labID = paste0("X", sprintf("%03d", 1:5)),
                       age = c(50, 200, 1150, 2060, 4050),
                       error = c(10, 15, 5, 1, 70),
                       depth = c(5, 100, 230, 300, 450),
                       cc = 1)
    knitr::kable(core)
    ```

3. (Optional) Create a data frame with the hiatuses depths, this should have two
numeric columns called `id` and `depth`:
    ```{r bacon-create-input-step3}
    hiatus <- data.frame(id = c(1, 2),
                         depth = c(50, 150))
    knitr::kable(hiatus)
    ```
  
4. Call the `ageR::create_input` function. The first parameter should be a list
containing the previous data frames, which must be called `sample_depths`, 
`core`, and `hiatus` (if included). 
Next, a working directory (`wdir`), the entity's name, and optionally the age 
model's name (by default is Bacon).
    ```{r bacon-create-input-step4, eval = TRUE}
    ageR::create_input(data = list(sample_depths = sample_depths, 
                                   core = core,
                                   # Optional
                                   hiatus = hiatus), 
                       wdir = "./", 
                       entity = "X",
                       am = "bacon")
    ```

#### Run Bacon
```{r bacon-run-fx-call, eval = FALSE}
ageR::Bacon(wdir = "./", 
            entity = "X", 
            # Optional parameters
            cpus = 1,
            postbomb = 0,
            cc = 0,
            seed = NA,
            alt_depths = NULL,
            quiet = FALSE,
            acc_step = 5,
            acc_lower = NULL,
            acc_upper = NULL,
            thick_step = 5,
            thick_lower = NULL,
            thick_upper = NULL,
            dry_run = FALSE,
            ...)
```

##### Dry-run
Dry-runs are useful to check how many scenarios will be generated with the current configuration:
```{r bacon-run-dr}
ageR::Bacon(wdir = "./", entity = "X", dry_run = TRUE, quiet = TRUE)
```

##### Change upper and lower bounds
Based on a dry-run, we might want to constraint our execution to a smaller set of scenarios. This can be done for both accumulation rate and core segment thickness.
```{r bacon-run-acc-bounds}
ageR::Bacon(wdir = "./", entity = "X", acc_lower = 10, acc_upper = 20, dry_run = TRUE, quiet = TRUE)
```

```{r bacon-run-thick-bounds}
ageR::Bacon(wdir = "./", entity = "X", thick_lower = 10, thick_upper = 30, dry_run = TRUE, quiet = TRUE)
```

##### Use mixed calibration curves
This is particular useful for "neo-tropical" sites. It involves three steps:

1. Assign `cc = 4` to the `core` data:
    ```{r bacon-run-mix-curves-step1}
    core <- data.frame(labID = paste0("X", sprintf("%03d", 1:5)),
                       age = c(50, 200, 1150, 2060, 4050),
                       error = c(10, 15, 5, 1, 70),
                       depth = c(5, 100, 230, 300, 450),
                       cc = 4)
    knitr::kable(core)
    ```
2. Create a mixed calibration curve with `ageR::mix_curves`. The following example uses a 50/50 mix between `IntCal20` (`cc1 = 1`) and `SHCal20` (`cc2 = 3`).
    ```{r bacon-run-mix-curves-step2}
    ccdir <- "./ccurves"
    ageR::mix_curves(proportion = 0.5, cc1 = 1, cc = 3, name = "neotropics.14C", dir = ccdir)
    ```
3. Add two new parameters to the `ageR::Bacon` call:
    ```{r bacon-run-mix-curves-step3, eval = FALSE}
    out <- ageR::Bacon(wdir = "./", entity = "X", cc4 = "neotropics.14C", ccdir = ccdir)
    ```

##### Display progress bar
A progress bar can be displayed for long computations. Just "pipe" the
function call to `ageR::pb()`.
```{r, eval = FALSE}
`%>%` <- magrittr::`%>%`
out <- ageR::Bacon(wdir = "./", entity = "X", cpus = 8, verbose = FALSE) %>%
  ageR::pb()
```

Alternatively, if you are not familiar with the "pipe" operator, you can run the
following code:
```{r, eval = FALSE}
out <- ageR::pb(ageR::Bacon(wdir = "./", entity = "X", cpus = 2))
```

##### Run example
```{r bacon-run, cache = TRUE, fig.height=20}
`%>%` <- magrittr::`%>%`
out <- ageR::Bacon(wdir = "./", entity = "X", cpus = 8, verbose = FALSE) %>%
  ageR::pb()
```

```{r bacon-run-stats, echo = FALSE}
out$stats$bias_rel <- format(out$stats$bias_rel, digits = 3)
knitr::kable(out$stats, col.names = c("Acc. Rate", 
                                      "Thickness",
                                      "Area Between Curves",
                                      "Relative Bias"))
best_scenario <- out$stats[1, 1:2]
idx <- as.numeric(rownames(best_scenario))
```

###### Best Scenario (Acc. Rate: `r best_scenario[1]` & Thicknes: `r best_scenario[2]`)

**- Log of posterior (MCMC)**

```{r bacon-run-log-posterior, echo = FALSE}
print(out$log[[idx]])
```

**- Accumulation Rate: Posterior vs Prior**
```{r bacon-run-acc-rate, echo = FALSE}
print(out$acc[[idx]])
```

```{r clean-outputs, echo = FALSE, eval = TRUE}
. <- lapply(list.files(".", "X_"), file.remove)
unlink("X", TRUE, TRUE)
unlink("ccurves", TRUE, TRUE)
```