stopifnot(require(knitr))
knitr::opts_chunk$set(collapse = T, comment = "#>")
options(tibble.print_min = 4L, tibble.print_max = 4L,width = 90)
opts_chunk$set(
  comment = NA,
  message = FALSE,
  warning = FALSE,
  dev = "png",
  dpi = 150,
  fig.asp = 0.8,
  fig.width = 5,
  out.width = "100%",
  fig.align = "center"
)
library(devtools)
devtools::install_github("rosalieb/serac")
library(serac)

The present vignette helps you compute your first age-depth model with serac, an R package for ShortlivEd RAdionuclide Chronology of recent sediment cores.

Note that the package evolves with time, so be sure to update your version when starting a new project.

Since its publication in 2020, we added a few options to the code. The most detailed list of arguments are in the help notice (?serac in the console). We are also including a few of the new options in this vignette (see sections [NEW] below)

1 First time user

1.1 Setting up the folders

Which folder are your currently working in?

getwd()

If you want to work in another folder, change it with setwd(), e.g.:

setwd("~/myProject/Age depth model")

Line below will create the Cores folder if it does not exist already

dir.create(file.path(getwd(), 'Cores'), showWarnings = FALSE)

Within the Cores folder, user needs to create one folder per core.

dir.create(file.path(paste0(getwd(),'/Cores'), 'serac_example_ALO09P12'), showWarnings = FALSE)

We are writing in this subfolder an example dataset (Source: Wilhelm et al., 2012).

Format your own data following this template, or get help with formatting using the serac_input_formatting() function.

?serac_example_ALO09P12
write.table(x = serac_example_ALO09P12, file = paste0(getwd(),'/Cores/serac_example_ALO09P12/serac_example_ALO09P12.txt'),col.names = T, row.names = F,sep="\t")
# Including proxy data for this core too
write.table(x = serac_example_ALO09P12_proxy, file = paste0(getwd(),'/Cores/serac_example_ALO09P12/serac_example_ALO09P12_proxy.txt'),col.names = T, row.names = F,sep="\t")

1.2 User metadata (optional)

One of our goal with serac is to improve reproducibility and data management.
A first and easy step is to associate the name of the scientist (you!) to each model built. To enter personal data (recommended: name, affiliation, ORCID number and email), tape in the following line in the console, and follow instructions.

user_infos()

2 Run serac

2.1 Minimum arguments

At the minimum, your function will be need the name of the core and the coring year. In the example below, I included the save_code argument because Rmarkdown does not save code history the way the code can use it. Unless you are including a plot in a Rmarkdown, I recommend you do not specify this argument, or turn it to its default, i.e., TRUE. That way, you can go back and see your code.

serac(name="serac_example_ALO09P12",coring_yr=2009,
      save_code=FALSE) #do not include 'save_code' if you are working outside a Rmarkdown document

2.2 Final model

Several sedimentation hypotheses were tested, and this is what the authors (Wilhelm et al, 2012) chose as the best model (type in only the function serac -- everything that appears below ("Sediment accumulation rate ...") are model outputs):

model_ALO09P12 <-
  serac(name="serac_example_ALO09P12", coring_yr=2009, model=c("CFCS"),
      plotphoto=FALSE, minphoto=c(0), maxphoto=c(210),
      plot_Pb=T, plot_Am=T, plot_Cs=T, Cher=c(30,40), Hemisphere=c("NH"), NWT=c(51,61),
      sedchange=c(75.5),
      plot_Pb_inst_deposit=T, inst_deposit=c(20,28,100,107,135,142,158,186),
      suppdescriptor=TRUE, descriptor_lab=c("Ca/Fe"),
      historic_d=c(20,28,100,107,135,142,158,186),
      historic_a=c(1994,1920,1886,1868),
      historic_n=c("sept 1994 flood","1920 flood","1886 flood","1868 flood ?"), 
      min_yr=c(1750),
      dmax=c(180), 
      plotpdf=T, preview=T,
      save_code=FALSE)

If you want to see the preview, change preview=T in the code. Before that, make sure to extend your window in RStudio (large plot!)

model_ALO09P12$plot

2.3 Plot against mass_depth

The plotting options are quite flexible (colors, text size).
We also offer the possibility to plot the figure against mass depth, using mass accumulation rate instead of sediment accumulation rate for the CFCS model. The code is similar to what we used previously, you just need to add mass_depth = TRUE to your function.

model_ALO09P12_mass_depth <-
  serac(name="serac_example_ALO09P12", coring_yr=2009, preview = T,save_code=FALSE, Pbcol = "orange", modelcol = "midnightblue", mycex = .8,
      mass_depth=TRUE)

Note that you can then decide to enter the depth data for the Cesium peaks, instantaneous deposit, and points to ignore in the unit g.cm-2. If you want to do that, add the argument input_depth_mm = FALSE.

model_ALO09P12_mass_depth$plot

2.4 Add varves counting

If varves counting are available, you can display the dates on the age-depth model.

To do so, include in your project's folder a text file (tab delimited) with two columns: "Age" and "Depth". Depths must be entered in mm. The file must be named with the name of your sediment core (e.g., "MyCore"), and the append "_varves.txt".

For example, for the example core serac_example_ALO09P12, you would need to include in the serac_example_ALO09P12 folder a file named serac_example_ALO09P12_varves.txt. Below is an example of what the file would look like:

| Age | Depth | |--------|---------| | 2009 | 0 | | 2008 | 5 | | 2007 | 10 | | 2006 | 15 | | 2005 | 20 | | 2004 | 30 | | 2003 | 35 | | 2002 | 40 | | 2001 | 45 |

2.5 Set detection limits for the radionuclides [NEW]

New arguments were added in March 2023 to enter detection limits for Pb, Cs and Am. The arguments are respectively DL_Pb, DL_Cs, and DL_Am. Any value below what is specified will be plotted with a different color and not included in the model (they are treated the same as the depths entered in the ignore argument).

An example of how to use it is provided below with the hiatus example.

If any value was below the detection limit, a message will be printed in the console

Example: 3 Pbex values were below the detection limit set by the user (25)

2.6 Add a hiatus [NEW]

As of November 15th, 2024, the function was modified to allow for hiatuses to be included in the model.

The description of the new argument and how to use it:

If there are any hiatus, enter it/them here. The input form is a list of as many vectors as there are hiatuses, and each vector is made of two elements minimum: the depth of the hiatus in mm and the length, in years. For example, enter 'hiatus = list(c(100, 5))' for a 5-years hiatus at 100mm. By default, "hiatus" will be printed on the graph. Optionally, the user can specify a name and a color to the by adding element to the vector in the list. Example: hiatus = list(c(100, 5, "hiatus", "blue"), c(100, 5, "", "red")) will had two hiatuses. Only the first one will have a name, and they will each be plotted with a different colors. Default = NULL.

Below is an example of how to use the new argument hiatus, with the example data included in the R package. Note that the hiatuses are not real for this core and that mass depth is not the recommended approach.

model_ALO09P12_hiatus <-
  serac(name="serac_example_ALO09P12", coring_yr=2009, model=c("CFCS"),
        plotphoto=FALSE, minphoto=c(0), maxphoto=c(210), mass_depth = TRUE,
        plot_Pb=T, plot_Am=T, plot_Cs=T, Cher=c(30,40), Hemisphere=c("NH"), NWT=c(51,61),
        sedchange=c(75.5),
        plot_Pb_inst_deposit=T, inst_deposit=c(20,28,100,107,135,142,158,186),
        suppdescriptor=TRUE, descriptor_lab=c("Ca/Fe"),
        historic_d=c(20,28,100,107,135,142,158,186),
        historic_a=c(1994,1920,1886,1868),
        historic_n=c("sept 1994 flood","1920 flood","1886 flood","1868 flood ?"), 
        min_yr=c(1750),
        dmax=c(180), 
        plotpdf=T, preview=T,
        save_code=FALSE,
        plot_unit = "mm", 
        DL_Pb = 25, DL_Cs = 25, DL_Am = 3, 
        hiatus = list(c(50, 5, "test hiatus", "black"), c(132, 15)))

3 Explore outputs

Files with age-depth model and metadata are automatically saved in your working folder. If you assign your function to an object, serac will return a list with the parameters.

mymodel1 <- serac(name="serac_example_ALO09P12", coring_yr=2009, preview = T,save_code=FALSE)

As always when computing a new code, serac will check whether you tried the code combination previously. Here, we used the same code than in the previous section, so the code display a message before the outputs.

Note that several objects are accessible from mymodel1: r paste("</br> - ",names(mymodel1)).
Depending on the code you chose (and the number of models you visualize), the list of objects increases or decreases.

mymodel1$plot 
# Visualize the input data
knitr::kable(mymodel1$data, format = "markdown")
# Visualize the inventories (if density was in the input data file)
mymodel1$Inventories
# Save the plot with custom parameters, e.g., Courier font and grey scale without editing default colors.
pdf(paste0(getwd(),"/Cores/serac_example_ALO09P12/serac_example_ALO09P12_custom.pdf"),width = 10, height = 5, family="Courier", colormodel = "grey")
mymodel1$plot
dev.off()

4 Other functions

4.1 help_serac()

Another way to read some help.

4.2 serac_input_formatting()

If you unsure about the input format of your core (if you have depth in mm, or column names that do not follow our example), you can use the function serac_input_formatting(name = "MyCore") (MyCore being the name of your core and folder in which the data are located) and follow the steps.

4.3 core_metadata()

Enter here a more extensive list of parameters associated to your core. Current list of parameters includes:

4.4 serac_map()

If you entered GPS coordinates for your core in the previous step, tape in serac_map() into your console and view the location of all the systems you entered GPS coordinates for.
If you enter a vector, e.g., serac_map(c("Lake1", "Lake2", "Lagoon1")), then the map will be generated solely for these systems.

# remove folder that was created for compilation of this vignette.
unlink(paste0(getwd(),"/Cores"), recursive = TRUE)
# copy and run that line in the console to build vignette
# devtools::build_vignettes()

5 Citation

If you use serac, please cite our paper describing the package:

Bruel, R., Sabatier, P., 2020. serac: an R package for ShortlivEd RAdionuclide chronology of recent sediment cores. Journal of Environmental Radioactivity 225, 106449. https://doi.org/10.1016/j.jenvrad.2020.106449



rosalieb/serac documentation built on Nov. 16, 2024, 11:21 a.m.