In special-uor/ageR: Supervised Age Modelling

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

ageR: Supervised Age Modelling

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")

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 development version from GitHub with:

# 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

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 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 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 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 ageR::create_input(data = list(sample_depths = sample_depths, core = core, # Optional hiatus = hiatus), wdir = "./", entity = "X", am = "bacon")

Run Bacon

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:

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.

ageR::Bacon(wdir = "./", entity = "X", acc_lower = 10, acc_upper = 20, dry_run = TRUE, quiet = TRUE)

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 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 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 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().

`%>%` <- 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:

out <- ageR::pb(ageR::Bacon(wdir = "./", entity = "X", cpus = 2))

Run example

`%>%` <- magrittr::`%>%`
out <- ageR::Bacon(wdir = "./", entity = "X", cpus = 8, verbose = FALSE) %>%
  ageR::pb()

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)

print(out$log[[idx]])

- Accumulation Rate: Posterior vs Prior

print(out$acc[[idx]])

. <- lapply(list.files(".", "X_"), file.remove)
unlink("X", TRUE, TRUE)
unlink("ccurves", TRUE, TRUE)

special-uor/ageR documentation built on July 10, 2024, 10:08 p.m.