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: <a href:“https://www.sciencedirect.com/science/article/pii/S0033589412000294”>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.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)


 ________________________
Running serac for core 'serac_example_ALO09P12'.


 Sediment accumulation rate (CFCS model) 0-75.5mm: SAR= 1.18 mm/yr, R2= 0.93
                          Error:     +/- 0.1 mm/yr

 Sediment accumulation rate (CFCS model) 75.5mm-bottom: SAR= 0.8 mm/yr, R2= 0.923
                          Error:     +/- 0.08 mm/yr
 Approximation of age at change(s) in sedimentation rate:
     Best Age: 1952 (uncertainty: 1947-1957)


 Age approximation of instantaneous deposit(s) from CFCS model:
     The instantaneous deposit at 20-28 mm has an estimated range of: 1991-1994.
     The instantaneous deposit at 100-107 mm has an estimated range of: 1913-1929.
     The instantaneous deposit at 135-142 mm has an estimated range of: 1874-1898.
     The instantaneous deposit at 158-186 mm has an estimated range of: 1852-1880.

 Inventory (Lead): 10287.66 Bq/m2 (+/- 232.9 Bq/m2)
 Inventory (Cesium): 19023.688 Bq/m2 (+/- 149.7 Bq/m2)


 ________________________

 The calculation took 0.5153 secs.

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

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)


 ________________________
Running serac for core 'serac_example_ALO09P12'.


 Mass accumulation rate (CFCS model): MAR= 0.065 g/cm2/yr, R2= 0.959
                              Error:     +/- 0.003 g/cm2/yr
 Inventory (Lead): 11707.91 Bq/m2 (+/- 253.2 Bq/m2)
 Inventory (Cesium): 21549.328 Bq/m2 (+/- 151.9 Bq/m2)


 ________________________

 The calculation took 0.0244 secs.

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.

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:

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


 ________________________
Running serac for core 'serac_example_ALO09P12'.

9 Cs values were below the detection limit set by the user (25): the Cs values and the corresponding Cs_er will be shown with a different colour on the plot.  
3 Pbex values were below the detection limit set by the user (25): the corresponding depths were added to the 'ignore' vector: 129.5, 140.5, 154.5.  

 Mass accumulation rate (CFCS model) 0-75.5mm: MAR= 0.065 g/cm2/yr, R2= 0.925
                              Error:     +/- 0.006 g/cm2/yr

 Mass accumulation rate (CFCS model) 75.5mm-bottom: MAR= 0.038 g/cm2/yr, R2= 0.895
                              Error:     +/- 0.005 g/cm2/yr
 Approximation of age at change(s) in sedimentation rate:
     Best Age: 1956 (uncertainty: 1951-1961)


 Age approximation of instantaneous deposit(s) from CFCS model:
     The instantaneous deposit at 20-28 mm has an estimated range of: 1997-1996.
     The instantaneous deposit at 100-107 mm has an estimated range of: 1919-1910.
     The instantaneous deposit at 135-142 mm has an estimated range of: 1861-1846.
     The instantaneous deposit at 158-186 mm has an estimated range of: 1838-1819.

 Inventory (Lead): 10227.167 Bq/m2 (+/- 231.2 Bq/m2)
 Inventory (Cesium): 19053.007 Bq/m2 (+/- 152.8 Bq/m2)


 ________________________

 The calculation took 0.0784 secs.

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:

• ISGN
  
• sample date (YYYY-MM-DD)
  
• latitude (in WGS84)
• longtiude (in WGS84)
• coring method (e.g., gravity corer, piston corer, percussion, etc.)
  
• subsampling method at the laboratory (e.g., calibrated volumetric sampler, extrusion, etc.)
  
• instrument type (e.g., alpha spectrometry, well-type germanium detector, P-type germanium detector)
  
• start of the measurements (YYYY-MM-DD)
  
• end of the measurements (YYYY-MM-DD)
  
• any additional comment (e.g., 210Pb background reached, first centimetres lost during coring, etc.)
  

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.