RCarb/0000755000176200001440000000000013475122242011245 5ustar liggesusersRCarb/inst/0000755000176200001440000000000013475061757012237 5ustar liggesusersRCarb/inst/doc/0000755000176200001440000000000013475061757013004 5ustar liggesusersRCarb/inst/doc/GetStarted.html0000644000176200001440000051345413475061757015754 0ustar liggesusers Get started with RCarb

Get started with RCarb

Sebastian Kreutzer1 & Barbara Mauz2

Last modified: 2019-05-19 (‘RCarb’ version: 0.1.3)

1IRAMAT-CRP2A, UMR 5060, CNRS - Université Bordeaux Montagine (France)
2Department of Geography and Geology, University of Salzburg, Salzburg (Austria)"

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’

Load example data

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.

##   SAMP_NAME     K   K_X    T  T_X    U  U_X U238 U238_X U234_U238
## 1     BN107 0.080 0.010 1.64 0.08 1.90 0.08    0      0         0
## 2     BN102 0.170 0.009 2.59 0.03 3.02 0.07    0      0         0
## 3     BN106 0.560 0.030 1.80 0.11 0.83 0.03    0      0         0
## 4      LV61 0.131 0.005 0.85 0.03 0.86 0.11    0      0         0
## 5      LV99 0.047 0.003 0.59 0.03 1.94 0.11    0      0         0
## 6      D101 0.105 0.004 0.65 0.02 1.25 0.08    0      0         0
##   U234_U238_X WCI WCI_X WCF WCF_X CC CC_X DIAM DIAM_X COSMIC COSMIC_X
## 1           0  20     7   7     7 62    1  180     10  0.180   0.0100
## 2           0  20    10  10    10 68    1  180     22  0.180   0.0100
## 3           0  20     6   6     6 49    1  145     15  0.180   0.0100
## 4           0  12     5   2     2 17    1  210     30  0.069   0.0035
## 5           0   8     3   5     5 61    3  210     30  0.182   0.0090
## 6           0   8     3   2     2 59    2  210     20  0.180   0.0100
##   INTERNAL INTERNAL_X ONSET ONSET_X FINISH FINISH_X  DE DE_X
## 1        0          0   100      10     40       10  98    9
## 2        0          0   100      10     40       10 130   10
## 3        0          0   100      10     40       10 120   10
## 4        0          0   120      10     40       10  52    5
## 5        0          0    60      10     40       10  50    4
## 6        0          0   180      10    130       10  81    5

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

## $UNIT
## [1] "%"
## 
## $DESCRIPTION
## [1] "K concentration"

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

COLUM UNIT DESCRIPTION
SAMP_NAME NA Sample name, unique identifier
K % K concentration
K_X % K concentration standard error
T ppm Th concentration
T_X ppm Th concentration standard error
U ppm U concentration
U_X ppm U concentration standard error
U238 ppm U-238 concentration
U238_X ppm U-238 concentration standard error
U234_U238 NA U-234/U-238 activity ratio
U234_U238_X NA U-234/U-238 activity ratio standard error
WCI % dry wt. Initial water content
WCI_X % dry wt. Initial water content standard error
WCF % dry wt. Final water content
WCF_X % dry wt. Final water content standard error
CC % dry wt. Carbonate content
CC_X % dry wt. Carbonate content standard error
DIAM m x 10^-6 Grain diameter
DIAM_X m x 10^-6 Grain diameter standard error
COSMIC Gy/ka Cosmic dose rate
COSMIC_X Gy/ka Cosmic dose rate standard error
INTERNAL Gy/ka Internal dose rate
INTERNAL_X Gy/ka Internal dose standard error
ONSET ka Carbonate onset
ONSET_X ka Carbonate onset standard error
FINISH ka Carbonate completion
FINISH_X ka Carbonate completion standard error
DE Gy Equivalent dose
DE_X Gy Equivalent dose standard error

Run dose rate modelling

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

## 
## [model_DoseRate()]
## 
##  Sample ID:       BN107 
##  Equivalent dose:     98  ±  9 Gy
##  Diameter:        180 µm 
##  MC runs error estim.:    10  
##  ------------------------------------------------ 
##  Age (conv.):         133.451  ±  9.451  ka
##  Age (new):       117.443  ±  6.074  ka
## 
##  Dose rate (conv.):   0.734  ±  0.033  Gy/ka
##  Dose rate (onset):   0.97  ±  0.062  Gy/ka
##  Dose rate (final):   0.743  ±  0.024  Gy/ka
##  ------------------------------------------------

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.

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.

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.

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

Model the dose rate

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

## 
## [model_DoseRate()]
## 
##  Sample ID:       1 
##  Equivalent dose:     98  ±  9 Gy
##  Diameter:        180 µm 
##  MC runs error estim.:    10  
##  ------------------------------------------------ 
##  Age (conv.):         133.451  ±  16.014  ka
##  Age (new):       117.443  ±  8.7  ka
## 
##  Dose rate (conv.):   0.734  ±  0.065  Gy/ka
##  Dose rate (onset):   0.974  ±  0.06  Gy/ka
##  Dose rate (final):   0.748  ±  0.053  Gy/ka
##  ------------------------------------------------

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’.

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

RCarb/inst/doc/GetStarted.html.asis0000644000176200001440000000023213355136342016661 0ustar liggesusers%\VignetteIndexEntry{Get started with RCarb} %\VignetteEngine{R.rsp::asis} %\VignetteKeyword{HTML} %\VignetteKeyword{vignette} %\VignetteKeyword{package} RCarb/tests/0000755000176200001440000000000013372276013012411 5ustar liggesusersRCarb/tests/testthat.R0000644000176200001440000000006513372276001014372 0ustar liggesuserslibrary(testthat) library(RCarb) test_check("RCarb")RCarb/tests/testthat/0000755000176200001440000000000013475122242014247 5ustar liggesusersRCarb/tests/testthat/test_.cal_DoseRate.R0000644000176200001440000000047213400277126020037 0ustar liggesuserscontext("Test .calc_DoseRate()") test_that("Full function test", { testthat::skip_on_cran() ##load Example dataset data("Example_Data", envir = environment()) ##simple run to check the 'ref' fall back expect_type(RCarb:::.calc_DoseRate(x = 10, data = Example_Data[14,], ref = NULL), type = "list") })RCarb/tests/testthat/test_write_InputTemplate.R0000644000176200001440000000040213372277346021446 0ustar liggesuserscontext("Test write_InputTemplate()") test_that("Full function test", { testthat::skip_on_cran() ##simple run expect_type(write_InputTemplate(), type = "list") ##write on template folder expect_silent(write_InputTemplate(file = tempfile())) })RCarb/tests/testthat/test_model_DoseRate.R0000644000176200001440000000414513470063613020324 0ustar liggesuserscontext("Test model_DoseRate()") test_that("Full function test", { testthat::skip_on_cran() ##load Example dataset data("Example_Data", envir = environment()) ##break function expect_error(model_DoseRate(data = "test"), regexp = "'data' is not a 'data.frame'") expect_error(model_DoseRate(data = data.frame(x = 1)), regexp = "The column names of your input data.frame do not match the requirements.") expect_error(model_DoseRate(data = data.frame()), regexp = "'data' is empty!") expect_error(model_DoseRate(data = data.frame(x = NA), regexp = "'data' is empty!")) expect_error( model_DoseRate(data = Example_Data[23,], n.MC = 10),regexp = "Modelling failed, please check your input data, they may not be meaningful!") expect_type( model_DoseRate(data = Example_Data[23:24,], n.MC = 10), type = "list") expect_error(model_DoseRate(data = Example_Data[14,], DR_conv_factors = "error", n.MC = 2, txtProgressBar = FALSE ), regexp = "'error' does not correspond to an available dose rate conversion dataset.\n Allowed are: Carb2007, Adamiec_Aitken_1998, Guerin_et_al_2011, Liritzis_et_al_2013") ##run simple example expect_type(model_DoseRate(data = Example_Data[14,], n.MC = 2, txtProgressBar = FALSE ), type = "list") ##run with different conversion factors expect_type( model_DoseRate( data = Example_Data[14, ], DR_conv_factors = "Adamiec_Aitken_1998", n.MC = 2, txtProgressBar = FALSE ), type = "list" ) ##run extrem case warning temp <- Example_Data[14, ] temp$DE <- 550 expect_warning( model_DoseRate( data = temp, n.MC = 2, txtProgressBar = FALSE ), regexp = "Extrem case detected: DE > max cumulative dose rate!" ) ##run two example expect_type(model_DoseRate( data = Example_Data[13:14, ], n.MC = 5, txtProgressBar = TRUE ), type = "list") ##run with n.MC == 1 expect_type(model_DoseRate( data = Example_Data[14, ], n.MC = 1, txtProgressBar = FALSE ), type = "list") })RCarb/NAMESPACE0000644000176200001440000000106313475061747012500 0ustar liggesusers# Generated by roxygen2: do not edit by hand export(model_DoseRate) export(write_InputTemplate) import(utils) importFrom(grDevices,rgb) importFrom(graphics,abline) importFrom(graphics,axis) importFrom(graphics,lines) importFrom(graphics,mtext) importFrom(graphics,par) importFrom(graphics,plot) importFrom(graphics,plot.default) importFrom(graphics,points) importFrom(graphics,polygon) importFrom(graphics,text) importFrom(stats,approx) importFrom(stats,density) importFrom(stats,na.exclude) importFrom(stats,nlminb) importFrom(stats,rnorm) importFrom(stats,sd) RCarb/NEWS.md0000644000176200001440000000223513475061750012353 0ustar liggesusers ## RCarb 0.1.3 (2019-06-02) ### New features - The reference dataset got a new dataset called `Reference_Data$DR_conv_factors` to support different dose rate conversion factors - The function `model_DoseRate()` gained are new argument `DR_conv_factors` to support different dose rate conversion factors ### Bugfixes - In case values for U-238 and U-234 were provided, for the gamma-dose rate contribution, erroneously the beta-dose water correction factors were used; now corrected (internal function `.calc_DoseRata()`). This bug already existed in *Carb* and was probably introduced by copy & paste actions. ### Other modifications - Add README.md - Modify output graphics and add more information - Update dependency and package version requirements ## RCarb 0.1.2 (2018-12-02) - Update internal references - Modify example in write\_InputTemplate() to comply with CRAN requests ## RCarb 0.1.1 (2018-11-20) - Internal changes only to account for CRAN comments on inital submission. ## RCarb 0.1.0 (2018-11-12) - Initial version RCarb/data/0000755000176200001440000000000013354625247012167 5ustar liggesusersRCarb/data/Example_Data.RData0000644000176200001440000000422013371044064015415 0ustar liggesusers7zXZi"6!X&nT])TW"nRʟOqcWK>=klt˙[bvܦ(]Y %̧( 5T*{"Z)~h|Ӽ%q^fHeMHL'nz,NzS瞫.:Kа O܍Ĺl>^?a\+IJ` @z"deB=3:V:)sx@j5@er'r62<.ACXvSIiJ7FqMpR5nr'o{,OGrTeIבp:oj |_R+׈kU`PKW)ɰ) G:ÃJ^\!ILNPSbO& d i8/7bshP`tB{”78E^.jþ~ړt #&D:lsvj#X £ "֏?2QHzUmRdx"BDD(\.1r[Hn)TUd7Rř "דI8=,{0ƛoʌ:Ai[*'TIJfwozbf;s.43te9Pر63 q٨ɬP"͌lrZY;|/MNSn*`qerrt-}>?jzi^-!0kB ![ʍmf[~SsUC7]gۜ !9׊󧁋$u)ݫon6uO_m ӳ9? ҰGJTFy?yH0)1< _Xpmgd$W#`UgΛtq]4T`V 7v@?Vx@`0W|ճ;feQlq&qdJa yon1ty^g]7Ԍ i/0ك+fFb>Y5Rb:z!0ai5LAfa.&"0_9U~%)OuvJ2^gfoP ;$usaȝV% Dտb#m=3HwTKPk'WhN}{Ul祿njU(˂4d";~4(Ҙ~(f<![X_TrP/J.-]!Z=W{gZ.WVK=jwiBߓ>U2s믾2ʩd5ѐAt4{ua 8'FE]o920sR*$%.Ļih¡F.X+y΁㤛U)QXw5Ң=PtI՞HMO~>vpLmn>q©ɋ7G-6 hΛR`#.:dd Ҧ]m.LKyi($XP37n5[4X?{bμ3ם)9FuɆ"RĆ*@?YD q&bk5>![U%Q[#ѧۮ.ui*kYM=2P>rΗ!g?lIqe[uIz,9\ʛ"b󶖬Djngzhgޙݨ5Z')1 Z " <2}~mפ2*p,'NʎM[ntؒy7L A\a+(EwOGU\&@m orҤ,$|(umٔbzj O<7+dė4X RRC0ZYFQ)=>TzLt`Qyแ=xgFf1__s,5S,As#:Ay| $e: ILl5>0 YZRCarb/data/Reference_Data.RData0000644000176200001440000000457013470043143015725 0ustar liggesusers7zXZi"6!X- <])TW"nRʟA,ʿBJƩ̸QľKx'Cp FK(ؽ\q/ ǽ# 5xJ)q=Kt0cAOA"R3`HJ e3FxC+ϵZ\܉qG=x._b=pAdg"Ҽ;*6K`(do0У1z^ΆE2җ$aߌl[#Ot^C <3tʧ-8#hi:iM#Az5aAʍC,9;x,Ͽ&NT[cCce+~fDZjfZ/hᾊ۳dV}"N}B3ҢgGWI YmWZaWm ED}0t`/ZDըbWω>kkcK>-\Riw,Үך. < VRrBsEd;QV5 *e.}腢FԟvT:Qį{ H6~O`,[Uэṟ%exU%u:|Wpq\ `Z"-uغg^-7^:WPsrmr%dkƎcx7\,ۼԋNdn$VGK \U`rd :Q1owN:X02j?&^B-m)^7IoD>7-?3܉Ty HPy)K-vÛV]A$c]0](Ӈob`3!QHP(@m"} !$vbpaFP!Ip룮2/&V/6 x41Nnvrq=Gtp= IP?ZSP1Q.L3pbƬve4ҋ&SEp_p aG[Q;a@9q-o ,yzةuc3J8sOHFϚې&k>g[goE!I’2Lp3^9U_e.@8^w0;~ V,ͩzfPZ!ZX`>nW;9ǩhO_M~%thI.t\#B4,շaf֫ՙ̹|P}2FT3x˜2'B C e-&dbTEU<#!/]m#HQU[88k@d'ʳWIn\bqG/c:w_+l%ܖp}zz' 5޶WN?2k!*1>;+^4 ,m)dWg 7s/JFG&e_Xhgt:8ob5fc~_c۾{FO[kNs?hOݘ^d6BpOw9Ku} 8֨<BiN9s5DoΦXCb|19GۑuD! &\}C8PٷN䶜4uu}=x>ss5LƋu噬֬ $̽BdaE;&ZNʀ/ Z*jzȐ8u(ء'VV̋Wb>r]?lI?wEKf 2'M=?,8Xt^U[.7mfjBc1]=/6-C3lA d) Bz /[ 4KuH$4HƉWbNNP(bgwL75g.(bt\T$_V;/}#wp[ @en![39iījSQ2iBu4g M|~2?;-!V8,L$sgnOU@N@tژ!ٯ1nKkbA3,+o`4,1\? {eMƾ()m/"X:6L%+yOj7=PaYˑۿ_4 Zq.4JBt*u``C׌Hzܫ&֤|twtSe[]>>0 YZRCarb/data/datalist0000644000176200001440000000003313354625273013712 0ustar liggesusersExample_Data Reference_DataRCarb/R/0000755000176200001440000000000013361410610011437 5ustar liggesusersRCarb/R/calc_DoseRate.R0000644000176200001440000002743113470222725014272 0ustar liggesusers#' @title Internal function to calculate date for a given maximum time #' #' @description This is the real worker function based on the *Carb* MATLAB function 'datalu1.m'. To #' avoid overhead, the function does not double check the input parameters and is thus not exposed #' and it does not appear in the manual #' #' @param x [numeric] (**required**): time for which the scenario is calculated #' #' @param data [data.frame] (**required**): input data, only a data.frame is allowed #' #' @param DR_conv_factors [character] (*optional*): select dose rate converson factors, `NULL` #' uses the original *Carb* values #' #' @param ref [list] (**optional**): list of reference data provided with this package, if nothing #' is provided the function will load package reference data via `data("Reference_Data", envir = environment())`. #' #' @param length_step [numeric] (with default): step length used for the calculation #' #' @param max_time [numeric] (with default): maximum time span to be evaluated #' #' @param mode_optim [logical] (with default): switch output mode, if `TRUE` only a scalar is returned, #' this reduces the used memory consumption for the calculation #' #' @author Sebastian Kreutzer, IRAMAT-CRP2A, UMR 5060, CNRS - Université Bordeaux Montaigne (France) based #' on the MATLAB code in the file 'datalu1.m' from Carb_2007a #' #' @section Function version: 0.2.0 #' #' @example #' ## the function can be run manually, however, this is not recommended, example: #' data("Example_Data", envir = environment()) #' RCarb:::.calc_DoseRate( #' x = 10, #' data = Example_Data[14,] #' ) #' #' @md #' @noRd .calc_DoseRate <- function( x, data, DR_conv_factors = NULL, ref = NULL, length_step = 1, max_time = 500, mode_optim = FALSE ){ ## load reference data if needed; we should try to load them externally before, ## however if this function is run internally for tests we want to have ## the comfort if(is.null(ref)){ Reference_Data <- NULL data("Reference_Data", envir = environment()) ref <- Reference_Data rm(Reference_Data) } ##rewrite variables, to keep the naming consistent with the original MATLAB code TIMEMAX <- x STEP1 <- length_step[1] ##initialise dose rate conversion factors (error catching we do a level up) if(is.null(DR_conv_factors)){ DR_ID <- 1 }else{ DR_ID <- grep( x = ref[["DR_conv_factors"]][["REFERENCE"]], pattern = DR_conv_factors, fixed = TRUE) } handles.UB <- ref[["DR_conv_factors"]][["UB"]][DR_ID] handles.TB <- ref[["DR_conv_factors"]][["TB"]][DR_ID] handles.KB <- ref[["DR_conv_factors"]][["KB"]][DR_ID] handles.UG <- ref[["DR_conv_factors"]][["UG"]][DR_ID] handles.TG <- ref[["DR_conv_factors"]][["TG"]][DR_ID] handles.KG <- ref[["DR_conv_factors"]][["KG"]][DR_ID] # STEP 1: Find U, Th, K values for the sediment ----------------------------------------------- ##transfer U, Th, and K value KA <- data[["K"]] UA <- data[["U"]] TA <- data[["T"]] K <- KA * (1 + data[["CC"]] / 100) U <- UA * (1 + data[["CC"]] / 100) T <- TA * (1 + data[["CC"]] / 100) # STEP 2: Derive carbonate model (daterlu1.m) ------------------------------------------------- ##2.1. - create vectors with variables, the maxium length is determined by max_time ##C >> CARBONATE C <- c( rep(1, data[["FINISH"]] / STEP1) * data[["CC"]] / 100, seq(data[["CC"]] / 100, 1e-05, length.out = (data[["ONSET"]] - data[["FINISH"]]) / STEP1 + 1), rep(0, (max_time - data[["ONSET"]]) / STEP1) + 1e-05 ) ##WC >> WATER CONTENT WC <- c( rep(1, data[["FINISH"]] / STEP1) * data[["WCF"]] / 100, seq(data[["WCF"]] / 100, data[["WCI"]] / 100, length.out = (data[["ONSET"]] - data[["FINISH"]]) / STEP1 + 1), rep(0, (max_time - data[["ONSET"]]) / STEP1) + data[["WCI"]] / 100 ) ##2.2. - create additional objects WF <- C + WC WFA <- data[["WCF"]] / 100 LEN <- length(C) ##2.3 - create time matrix TIME <- matrix(seq(0, max_time, STEP1), nrow = 1) TIME_ <- seq(0,round(TIMEMAX * STEP1)/STEP1) TIME_ <- c(rep(0,max_time - max(TIME_)), TIME_) # STEP 3: Derive linear uptake mode of uranium (code from Forbes Quarry work) (daterlu1.m) --------- lam_u235 <- log(2) / 703800000 lam_u238 <- log(2) / 4.4680e+09 ##combine in matrix Aa <- .rad_pop_LU(data[["U234_U238"]], TIME_) ##flip matrix row order Aa <- apply(Aa, 2, rev) ##note: the MATLAB code now throws all variables, ##namely, "N_u238", "N_u234", "N_t230", "N_u235", "N_p231" ##Of course we do not do this here, since this is an R package and the last thing ##we want to have is a package writting unexpectedly into the Global Environment ##In the following the objects are accessed by accessing the matrix ## Parent activity (Bq/mg) ... from A&A (1998) A_u238 <- lam_u238 * 6.022e+023 * 1e-3 / (238 * 31.56e+06) A_u235 <- lam_u235 * 6.022e+23 * 1e-03 / (235 * 31.56e+06) ## dose rate per ppm of parent conv_const <- 5.056e-03 CONST_Q_U238 <- 0.9927 CONST_Q_U235 <- 1 - CONST_Q_U238 D_b_u238 <- conv_const * A_u238 * 0.8860 * CONST_Q_U238 D_b_u234 <- conv_const * A_u238 * 0.0120 * CONST_Q_U238 D_b_t230 <- conv_const * A_u238 * 1.3850 * CONST_Q_U238 D_b_u235 <- conv_const * A_u235 * 0.1860 * CONST_Q_U235 D_g_u238 <- conv_const * A_u238 * 0.0290 * CONST_Q_U238 D_g_u234 <- conv_const * A_u238 * 0.0020 * CONST_Q_U238 D_g_t230 <- conv_const * A_u238 * 1.7430 * CONST_Q_U238 ## i-m dose rate - no grain size correction U238_b_diseq <- D_b_u238 * Aa[,"N_u238"] * data[["U238"]] U234_b_diseq <- D_b_u234 * Aa[,"N_u234"] * data[["U238"]] T230_b_diseq <- D_b_t230 * Aa[,"N_t230"] * data[["U238"]] U238_g_diseq <- D_g_u238 * Aa[,"N_u238"] * data[["U238"]] U234_g_diseq <- D_g_u234 * Aa[,"N_u234"] * data[["U238"]] T230_g_diseq <- D_g_t230 * Aa[,"N_t230"] * data[["U238"]] # STEP 4: Calculate time-dependent dose rate -------------------------------------------------- ##this step uses the data by Mejdahl and interpolates the value for the given diamter MK <- 1 - exp( approx(x = log(ref$mejdahl[[1]]), y = log(ref$mejdahl[[2]]), xout = log(data[["DIAM"]]/1000), rule = 2)$y) MT <- 1 - exp( approx(x = log(ref$mejdahl[[1]]), y = log(ref$mejdahl[[3]]), xout = log(data[["DIAM"]]/1000), rule = 2)$y) MU <- 1 - exp( approx(x = log(ref$mejdahl[[1]]), y = log(ref$mejdahl[[4]]), xout = log(data[["DIAM"]]/1000), rule = 2)$y) MU238 <- MU234 <- MT230 <- MU235 <- MP231 <- 1 ##prepare data, to avoid that this is called over and over again when .griddata is called x_grid <- as.numeric(colnames(ref$DATAek)) y_grid <- x_grid x_grid <- log(rep(x_grid, length(x_grid))) y_grid <- log(rep(y_grid, each = length(y_grid))) xo <- log(WC) yo <- log(C) ##run surface interpolation calculations to get the ##water correction factors ##nomenclature: ## ++++++++++++++++ RCarb calculation ++++++++++++++++++++++++ ##beta water correction factors XKB <- .griddata(x_grid, y_grid, ref$DATAek, xo, yo) XTB <- .griddata(x_grid, y_grid, ref$DATAet, xo, yo) XUB <- .griddata(x_grid, y_grid, ref$DATAeu, xo, yo) XU238B <- .griddata(x_grid, y_grid, ref$DATAeu238, xo, yo) XU234B <- .griddata(x_grid, y_grid, ref$DATAeu234, xo, yo) XT230B <- .griddata(x_grid, y_grid, ref$DATAet230, xo, yo) ##gamma water correction factors XKG <- .griddata(x_grid, y_grid, ref$DATApk, xo, yo) XTG <- .griddata(x_grid, y_grid, ref$DATApt, xo, yo) XUG <- .griddata(x_grid, y_grid, ref$DATApu, xo, yo) XU238G <- .griddata(x_grid, y_grid, ref$DATApu238, xo, yo) XU234G <- .griddata(x_grid, y_grid, ref$DATApu234, xo, yo) XT230G <- .griddata(x_grid, y_grid, ref$DATApt230, xo, yo) ##perform dose rate correction with the before set factors ##beta water correction factors DRKB <- MK * K * handles.KB / (1 + XKB * WF) DRTB <- MT * T * handles.TB / (1 + XTB * WF) DRUB <- MU * U * handles.UB / (1 + XUB * WF) DRU238B <- MU238 * U238_b_diseq / (1 + XU238B * WF) DRU234B <- MU238 * U234_b_diseq / (1 + XU234B * WF) DRT230B <- MU238 * T230_b_diseq / (1 + XT230B * WF) ##gamma water corrections factors DRKG <- MK * K * handles.KG / (1 + XKG * WF) DRTG <- MT * T * handles.TG / (1 + XTG * WF) DRUG <- MU * U * handles.UG / (1 + XUG * WF) DRU238G <- MU238 * U238_g_diseq / (1 + XU238G * WF) DRU234G <- MU238 * U234_g_diseq / (1 + XU234G * WF) DRT230G <- MU238 * T230_g_diseq / (1 + XT230G * WF) ##calculate final dose rate DR <- DRKB + DRTB + DRUB + DRKG + DRTG + DRUG + data[["COSMIC"]] + data[["INTERNAL"]] + DRU238B + DRU234B + DRT230B + DRU238G + DRU234G + DRT230G ## ++++++++++++++++ Conventinal calculation ++++++++++++++++++++++++ ##set alternative, the commonly used water correction factors ##after Zimmerman, 1971 (Archaeometry); cf. also Aitken (1985) ##after no interpolation is needed since these factors remain constant XKBA <- XTBA <- XUBA <- XU238BA <- XU234BA <- XT230BA <- 1.25 XKGA <- XTGA <- XUGA <- XU238GA <- XU234GA <- XT230GA <- 1.14 ##beta DRKBA <- MK * KA * handles.KB / (1 + XKBA * WFA) DRTBA <- MT * TA * handles.TB / (1 + XTBA * WFA) DRUBA <- MU * UA * handles.UB / (1 + XUBA * WFA) DRU238BA <- MU238 * U238_b_diseq / (1 + XU238BA * WFA) DRU234BA <- MU238 * U234_b_diseq / (1 + XU234BA * WFA) DRT230BA <- MU238 * T230_b_diseq / (1 + XT230BA * WFA) ##gamma DRKGA <- MK * KA * handles.KG / (1 + XKGA * WFA) DRTGA <- MT * TA * handles.TG / (1 + XTGA * WFA) DRUGA <- MU * UA * handles.UG / (1 + XUGA * WFA) DRU238GA <- MU238 * U238_g_diseq / (1 + XU238GA * WFA) DRU234GA <- MU238 * U234_g_diseq / (1 + XU234GA * WFA) DRT230GA <- MU238 * T230_g_diseq / (1 + XT230GA * WFA) ##calculate alternative (conventional) dose rate DRA <- DRKBA + DRTBA + DRUBA + DRKGA + DRTGA + DRUGA + data[["COSMIC"]] + data[["INTERNAL"]] + DRU238BA + DRU234BA + DRT230BA + DRU238GA + DRU234GA + DRT230GA ##replace NA values by 0, otherwise the function crashes ##The NA values come from the surface (line 175) interpolation and replacing them by 0 ##does not affect the results, but allows the code to run without taking other precautions. DR[is.na(DR)] <- 0 DRA[is.na(DRA)] <- 0 # STEP 5: Calculate date ---------------------------------------------------------------------- ##calculate the cummulated absorbed dose ##Is this correct, starting from index 1? Yes, it is, we have set the maximum manually to ##500, if we would reverse the vector, we would pretend that we know the age of the sample ##already, but then we would not need this modelling. CUMDR <- cumsum(c(0, (DR[1:(length(DR) - 1)] + DR[2:length(DR)]) * STEP1 / 2)) CUMDRA <- cumsum(c(0, (DRA[1:(length(DRA) - 1)] + DRA[2:length(DRA)]) * STEP1 / 2)) if(data[["DE"]] > max(CUMDR)) ##modified before it was Age > 500 ka, which did not fit. warning("[.calc_DoseRate()] Extrem case detected: DE > max cumulative dose rate!", call. = FALSE) ##RCarb ages AGE <- try( approx(x = CUMDR, y = as.numeric(TIME), xout = data[["DE"]], method = "linear", rule = 2)$y, silent = TRUE) ##conventional age AGEA <- try( approx(x = CUMDRA, y = as.numeric(TIME), xout = data[["DE"]], method = "linear", rule = 2)$y, silent = TRUE) ##sometimes the input values are not meaningful (for example data row 23 in the example dataset) ##and the approximation failed, ##we here provide a clean crash if(class(AGE) == 'try-error' || class(AGEA) == 'try-error') stop("[.calc_DoseRate()] Modelling failed, please check your input data, they may not be meaningful!", call. = FALSE) ##calculate age ABS <- abs(AGE - TIMEMAX) # RETURN -------------------------------------------------------------------------------------- if(mode_optim){ results <- ABS }else{ results <- list( ABS = ABS, AGE = AGE, AGEA = AGEA, LEN = LEN, DR = DR, DRA = DRA, CUMDR = CUMDR, CUMDRA = CUMDRA ) } return(results) } RCarb/R/RCarb-package.R0000644000176200001440000002224313470231066014156 0ustar liggesusers#' @title RCarb - Dose Rate Modelling of Carbonate-Rich Samples #' #' @description The package provides a dose rate modelling for carbonate-rich samples in the #' context of trapped charged dating (e.g., luminescence dating) applications. #' #' #' \if{html}{ #' \figure{Logo_RCarb.svg}{options: width="50px" alt="https://github.com/R-Lum/RCarb"}\cr #' } #' #' #' @details #' #' **Funding** #' #' Between 2018-2019, the work of Sebastian Kreutzer as maintainer of the package was supported #' by LabEx LaScArBxSK (ANR - n. ANR-10-LABX-52). #' #' @name RCarb-package #' #' @aliases RCarb-package RCarb #' #' @docType package #' #' @keywords package #' #' @import utils #' #' #' @references #' #' This package bases on a 'MATLAB' programme with name 'Carb', details can be found the #' following references:\cr #' #' Mauz, B., Hoffmann, D., 2014. What to do when carbonate replaced water: Carb, the model for estimating the #' dose rate of carbonate-rich samples. Ancient TL 32, 24-32. \url{http://ancienttl.org/ATL_32-2_2014/ATL_32-2_Mauz_p24-32.pdf} #' #' Nathan, R.P., Mauz, B., 2008. On the dose-rate estimate of carbonate-rich sediments for trapped charge dating. #' Radiation Measurements 43, 14-25. \doi{10.1016/j.radmeas.2007.12.012} #' #' **Further reading** #' #' Nathan, R.P., 2010. Numerical modelling of environmental dose rate and its application to trapped-charge dating. #' DPhil thesis, St Hugh's College, Oxford. \url{https://ora.ox.ac.uk/objects/ora:6421} #' #' @importFrom grDevices rgb #' @importFrom graphics plot plot.default abline lines par mtext polygon points axis text #' @importFrom stats approx nlminb rnorm sd na.exclude density #' #' @md NULL #' Example data #' #' @name Example_Data #' #' @description #' Example data as shipped with *Carb* by Mauz \& Hoffmann (2014). In contrast to the original #' data, `NA` values have been replaced by 0 and columns and rows have been transposed. Samples #' are now organised in rows and parameters in columns. #' #' The data can be used to test 'RCarb' and play with the secondary carbonatisation process. #' Sample HD107 was remnamed to LV107 for the sake of consistency with Fig. 4 in Mauz \& Hoffmann (2014). #' #' #' @format #' #' `Example_Data`: [data.frame] (28 x 29) #' #' Each column has two attributes: #' #' - `UNIT`: the unit, so far applicable, e.g. "ppm" #' - `DESCRIPTION`: the column description #' #' @section Version: 0.1.0 #' #' @keywords datasets #' #' @author Mauz \& Hoffmann (2014), with minor modifcations by Sebastian Kreutzer, IRAMAT-CRP2A, UMR 5060, #' CNRS-Université Bordeaux Montaigne (France) #' #' #' @references #' #' Mauz, B., Hoffmann, D., 2014. What to do when carbonate replaced water: Carb, the model #' for estimating the dose rate of carbonate-rich samples. Ancient TL 32, 24-32. #' #' @examples #' #' ## show first elements of the example data #' data(Example_Data, envir = environment()) #' head(Example_Data) #' #' ##show only column U230 #' Example_Data$U238 #' #' @docType data #' @md NULL #' Reference data #' #' @name Reference_Data #' #' @description Reference data and correction factors for beta and gamma radiation used for internal calculations. #' These values are used instead of the correction factors given in Aitken (1985) for the carbonate model. #' #' @details The reference values are used internally to account for: (1) grain size depend beta-attenuation #' factors (Mejdahl, 1979) and (2) to correct nuclide dependent beta and gamma radiation for water/carbonate proportions. #' The latter values are given as matrix and precise values are interpolated during the modelling process. #' #' Additionally 'RCarb' provides and own set of dose rate conversion factors to convert concentrations #' of U, Th, and K to dose rate values. Historically *Carb* (and thus 'RCarb') as its own dose rate #' conversion factors, which differ slightly from other published values. To provide a consistent #' calculation approach by default the 'old' *Carb* values are used, but the user can further #' switch (see [model_DoseRate]) to values provided by Adamiec \& Aitken (1998), Guérin et al. (2011) #' or Liritzis et al (2013). #' #' Different values quoted for U-238 and U-234 accounts for different activity ratios. For further details #' on the origin of these data we refer to Nathan \& Mauz (2008) and Nathan (2010).\cr #' #' **Nuclear data origin according to Nathan \& Mauz (2008)** #' #' The gamma primary energy spectra of uranium, thorium and potassium are drawn from #' Evaluated Nuclear Structure Data File (ENSDF) database at \url{http://www.nndc.bnl.gov} (2002-01-16) #' and the beta primary energy spectra was derived from ENSDF end-point energies using a #' Fermi beta decay model (Evans, 1955) modified by Behrens \& Szybisz (1976). #' For the simulations of the collisional mass stopping powers for quartz the software ESTAR #' (Berger et al., 2000) was used. The mass energy-absorption coefficients for quartz were #' tabulated by Hubbell \& Seltzer (2004). #' #' *For further details and references please read Nathan \& Mauz (2008)* #' #' #' @format #' #' `Reference_Data`: [list] \cr #' #' \tabular{llll}{ #' **NAME** \tab **TYPE** \tab **DIM** \tab **DESCRIPTION**\cr #' DATAek \tab `matrix` \tab 4 x 4 \tab correction factors for electrons for water and carbonate to sediment mass ratio for K\cr #' DATAet \tab `matrix` \tab 4 x 4 \tab correction factors for electrons for water and carbonate to sediment mass ratio for Th \cr #' DATAet230 \tab `matrix` \tab 4 x 4 \tab correction factors for electrons for water and carbonate to sediment mass ratio for Th-230\cr #' DATAeu \tab `matrix` \tab 4 x 4 \tab correction factors for electrons for water and carbonate to sediment mass ratio for U\cr #' DATAeu234 \tab `matrix` \tab 4 x 4 \tab correction factors for electrons for water and carbonate to sediment mass ratio for U-234\cr #' DATAeu238 \tab `matrix` \tab 4 x 4 \tab correction factors for electrons for water and carbonate to sediment mass ratio for U-238\cr #' DATApk \tab `matrix` \tab 4 x 4 \tab correction factors for photons for water and carbonate to sediment mass ratio for K\cr #' DATApt \tab `matrix` \tab 4 x 4 \tab correction factors for photons for water and carbonate to sediment mass ratio for T\cr #' DATApt230 \tab `matrix` \tab 4 x 4 \tab correction factors for photons for water and carbonate to sediment mass ratio for Th-230\cr #' DATApu \tab `matrix` \tab 4 x 4 \tab correction factors for photons for water and carbonate to sediment mass ratio for U\cr #' DATApu234 \tab `matrix` \tab 4 x 4 \tab correction factors for photons for water and carbonate to sediment mass ratio for U-234\cr #' DATApu238 \tab `matrix` \tab 4 x 4 \tab correction factors for photons for water and carbonate to sediment mass ratio for U-238\cr #' mejdahl \tab `data.frame` \tab 36 x 4 \tab beta-dose attenuation values for quartz grains according to Mejdahl (1979) \cr #' DR_conv_factors \tab `data.frame` \tab 4 x 13 \tab beta and gamma dose rate conversion factors used internally (see details) #' } #' #' @section Version: 0.2.0 #' #' @keywords datasets #' #' @references #' #' Adamiec, G., Aitken, M.J., 1998. Dose-rate conversion factors: update. #' Ancient TL 16, 37–50. \url{http://ancienttl.org/ATL_16-2_1998/ATL_16-2_Adamiec_p37-50.pdf} #' #' Guérin, G., Mercier, N., Adamiec, G., 2011. Dose-rate conversion factors: update. Ancient TL 29, 5–9. #' \url{http://ancienttl.org/ATL_29-1_2011/ATL_29-1_Guerin_p5-8.pdf} #' #' Liritzis, I., Stamoulis, K., Papachristodoulou, C., Ioannides, K., 2013. #' A Re-Evaluation of Radiation Dose-Rate Conversion Factors. #' Mediterranean Arhaeology and Archaeometry 12, 1–15. #' \url{http://maajournal.com/Issues/2012/pdf/FullTextLiritzis.pdf} #' #' Mejdahl, V., 1979. Thermoluminescence dating: beta-dose attenuation in quartz grains. Archaeometry 21, 61-72. #' \url{http://ancienttl.org/ATL_32-2_2014/ATL_32-2_Mauz_p24-32.pdf} #' #' Nathan, R.P., Mauz, B., 2008. On the dose-rate estimate of carbonate-rich sediments for trapped charge dating. #' Radiation Measurements 43, 14-25. \doi{10.1016/j.radmeas.2007.12.012} #' #' Nathan, R.P., 2010. Numerical modelling of environmental dose rate and its application to trapped-charge dating. #' DPhil thesis, St Hugh's College, Oxford. \url{https://ora.ox.ac.uk/objects/ora:6421}\cr #' #' **Further reading** #' #' Aitken, M.J., 1985. Thermoluminescence dating. Academic Press. #' #' Berger, M.J., Coursey, J.S., Zucker, M.A., 2000. ESTAR, PSTAR, and #' ASTAR: Computer Programs for Calculating Stopping-Power and Range #' Tables for Electrons, Protons, and Helium Ions (version 1.2.2). #' http://physics.nist.gov/Star (2005-08-09). #' National Institute of Standards and Technology, Gaithersburg, MD. #' #' Behrens, H., Szybisz, L., 1976. Shapes of beta spectra. Physics Data 6-1, #' Zentralstelle fuer Atomkernenergie-Dokumentation (ZAED), Germany. #' #' Evans, R.D., 1955. The Atomic Nucleus. McGraw-Hill, NY. #' #' Hubbell, J.H., Seltzer, S.M., 2004. Tables of X-Ray Mass Attenuation Coefficients and Mass #' Energy-Absorption Coefficients (version 1.4). http://physics.nist.gov/xaamdi #' (2005-08-09). National Institute of Standards and Technology, Gaithersburg, MD. #' #' #' @examples #' #' data(Reference_Data, envir = environment()) #' str(Reference_Data) #' Reference_Data$DATAek #' #' @docType data #' @md NULLRCarb/R/write_InputTemplate.R0000644000176200001440000000440513401212423015567 0ustar liggesusers#' @title Write table input template #' #' @description This function creates a template table that can be used as input for the function #' [model_DoseRate] #' #' @param file [character] (optional): output path, if `NULL` nothing is written, but a template #' [data.frame] is returned. #' #' @param ... additional arguments that can be passed to function [write.table] if `file != NULL`. #' Supported arguments are: `sep`, `dec, `fileEncoding` #' #' @author Sebastian Kreutzer, IRAMAT-CRP2A, UMR 5060, CNRS - Université Bordeaux Montaigne (France) #' #' @section Function version: 0.1.0 #' #' @examples #' #' ##create template without file creation #' write_InputTemplate() #' #' \dontrun{ #' ##Example with file output #' #' ## set temporary filename #' ## (replace by own path if needed) #' temp_file <- tempfile(pattern = "template", fileext = ".csv") #' write_InputTemplate(file = temp_file) #' #' } #' #' @seealso [Example_Data], [write.table] #' #' @md #' @export write_InputTemplate <- function( file = NULL, ... ){ ##load example data, this is our starting point Example_Data <- NULL data("Example_Data", envir = environment()) df <- Example_Data ##remove all rows, except the first df <- df[1,] ##replace name df$SAMP_NAME[1] <- "EXAMPLE" ##restore attributes df_list <- lapply(1:ncol(df), function(x){ attr.names <- names(attributes(Example_Data[[x]])) attributes(df[[x]])[attr.names] <- attributes(Example_Data[[x]])[attr.names] return(df[[x]]) }) ##restore names names(df_list) <- colnames(Example_Data) ##transform to data.frame df <- as.data.frame(df_list,stringsAsFactors = FALSE) attr(df, which = "pacakge") <- "RCarb" # Output -------------------------------------------------------------------------------------- if(is.null(file)){ return(df) }else{ ##allow some flexibility write_settings <- list( sep = ",", dec = ".", fileEncoding = "" ) ##modify if needed write_settings <- modifyList(x = write_settings, val = list(...)) ##write table write.table( x = df, file = file, append = FALSE, quote = FALSE, row.names = FALSE, col.names = TRUE, sep = write_settings$sep, fileEncoding = write_settings$fileEncoding ) } }RCarb/R/internals_RCarb.R0000644000176200001440000000664313372120350014644 0ustar liggesusers#################################################################################################### ## INTERNAL HELPER FUNCTIONS RCarb ## #################################################################################################### #+++++++++++++++++++++ #+ .rad_pop_LU() + #+++++++++++++++++++++ #' @title Calculate Ra population based in a given activity ratio and time #' #' @description This function is a direct translation from the Matlab function `rad_pop_LU` to R from the #' software 'Carb' (version 2007a). The function is called from within the function [calc_DoseRate]. #' #' @author Sebastian Kreutzer, IRAMAT-CRP2A, Université Bordeaux Montagine (France); based on Matlab #' code provided by the authors of 'Carb' #' #' @param ACT_RATIO [numeric] (**required**): activity ratio (a scalar) #' #' @param t [numeric] (**required**): time for which the Ra populations is calculated #' #' @section Function version: 0.1.0 #' #' @return This function returns a [matrix] of dimension `length(t) x 4` #' #' @md #' @noRd .rad_pop_LU <- function( ACT_RATIO, t ){ a <- 1 / rev(t)[1] L234 <- log(2) / 2.455e+05 L235 <- log(2) / 7.038e+08 L238 <- log(2) / 4.468e+09 L230 <- log(2) / 7.538e+04 L231 <- log(2) / 3.276e+04 c <- ACT_RATIO * L238 / L234 U238 <- a * t b <- a U235 <- b * t P231 <- (b * L235 / L231^2) * (exp(-L231 * t) + L231 * t - 1) P231 <- P231 * (L231 / L235) U234 <- ((L238 * a / L234 ^ 2) - (a * c / L234)) * exp(-L234 * t) + (L238 * a / L234) * t + a * c / L234 - L238 * a / L234 ^ 2 U234 <- U234 * (L234/L238) T230 <- (L238 * a/(L234*(L230-L234)) - a*c/(L230-L234)) * exp(-L234 * t) + (a*c/(L230-L234) - L238*a/(L234*(L230-L234)) + L238*a/L230^2 + L238*a/(L230*L234) - a*c/L230 ) * exp(-L230 * t) + (L238*a/L230) * t + a*c/L230 - L238*a/(L230*L234) - L238*a/L230^2 T230 <- T230 * (L230 / L238) ##combine in matrix m <- matrix(c(U238, U234, T230, U235, P231), ncol = 5, byrow = FALSE) ##provide column headers (this helps later) colnames(m) <- c("N_u238", "N_u234", "N_t230", "N_u235", "N_p231") return(m) } #+++++++++++++++++++++ #+ .griddata() + #+++++++++++++++++++++ #' @title Point interpolation on for irregular surface data #' #' @description This function mimics the MATLAB function 'griddata', addpated for the specific #' problemns in context of this package. Internally the function [interp::interpp] is used. Please #' note that this function should not be used outside of the context of this package. #' #' @return The function returns a vector with the interpolated values #' #' @param x [numeric] (**required**): vector of x-coordinates #' #' @param y [numeric] (**required**): vector of y-coordinates #' #' @param z [numeric] (**required**): vector of z-coordinates #' #' @param xo [numeric] (**required**): vector of x-coordinates for the output grid #' #' @param yo [numeric] (**required**): vector of y-coordinates for the output grid #' #' @param ... further arguments passed to [inter::interpp] #' #' @author Sebastian Kreutzer, IRAMAT-CRP2A, Université Bordeaux Montagine (France) #' #' @section Function version: 0.1.0 #' #' @seealso [interp::interpp], [calc_DoseRate] #' #'@md #'@noRd .griddata <- function(x_grid = x_grid, y_grid = y_grid, z, xo = xo, yo = yo, ...){ interp::interpp( x = x_grid, y = y_grid, z = as.numeric(z), xo = xo, yo = yo, ... )$z } RCarb/R/model_DoseRate.R0000644000176200001440000004424413470236347014476 0ustar liggesusers#' @title Model dose rate evolution in carbonate-rich samples #' #' @description This function models the dose rate evolution in carbonate enrich environments. For the #' calculation internal functions are called. #' #' @details This function is the starting point for the dose rate modelling for carbonat enrich #' environments. It provides basically the same functionality as the original version of 'Carb', i.e. #' you should be also aware of the limitations of this modelling approach. In particular: The model #' assumes a linear carbonate mass increase due to post-depositional processes. Please read the #' references cited blow.\cr #' #' **Uncertainty estimation** #' #' For estimating the uncertainties, Monte-Carloe (MC) simulation runs are used. For very #' small values (close to 0) this can, however, lead to edge effects (similar in 'Carb') since #' values below 0 are set to 0. #' #' @param data [data.frame] (**required**): input data following the structure given #' in the example data set `data(Example_Data)`. The input [data.frame] should have at least #' one row (i.e. values for one sample). For multiple rows the function is automatically re-called. #' #' @param DR_conv_factors [character] (*optional*): applied dose rate conversion factors, #' allowed input values are `"Carb2007"`, `"Adamiec_Aitken_1998"`, `"Guerin_et_al_2011"`, #' `"Liritzis_et_al_2013"`. `NULL` triggers the default, which is `"Carb2007"` #' #' @param length_step [numeric] (with default): step length used for the calculation #' #' @param max_time [numeric] (with default): maximum temporal search range #' #' @param n.MC [numeric] (with default): number of Monte Carlo runs used for the error calculation #' #' @param method_control (*optional*): additional arguments that can be provided to the control the #' the modelling. See details for further information. #' #' @param txtProgressBar [logical] (with default): enables/disables the `txtProgressBar` for the MC runs #' #' @param verbose [logical] (with default): enables/disables verbose mode #' #' @param plot [logical] (with default): enables/disables plot output #' #' @param ... further arguments passed to the underyling plot functions, see also details for further information. Supported standard arguments are `mfrow`, `xlim`, `xlab`. #' #' @return The function returns numerical and graphical output #' #' -----------------------------------\cr #' `[ NUMERICAL OUTPUT ]`\cr #' -----------------------------------\cr #' * A [data.frame] which is the combination of the input and values calculated by this function. #' #' -----------------------------------\cr #' `[ GRAPHICAL OUTPUT ]`\cr #' -----------------------------------\cr #' #' **Upper plot:** Dose rate evolution over time backwards. The solid black line is the calculation #' output, the grey shaded area indicates the 2-sigma error margins. The dashed blue line is an indicator #' of the quality of the error estimations based on Monte Carlo (MC) runs.The closer it follows the #' black line, the more reliable are the given error margins. \cr #' #' **Lower plot:** Totally absorbed dose over time. The plot is an representation of the 'new' #' age based on the carbonat modelling. #' #' #' @examples #' ##load example data #' data("Example_Data", envir = environment()) #' #' ##run the function for one sample from #' ##the dataset #' model_DoseRate( #' data = Example_Data[14,], #' n.MC = 2, #' txtProgressBar = FALSE #' ) #' #' #' @author Sebastian Kreutzer, IRAMAT-CRP2A, UMR 5060, Université Bordeaux Montagine (France); based #' on 'MATLAB' code given in file Carb_2007a.m of *Carb* #' #' @section Function version: 0.2.0 #' #' @references #' Mauz, B., Hoffmann, D., 2014. What to do when carbonate replaced water: Carb, the model for estimating the #' dose rate of carbonate-rich samples. Ancient TL 32, 24-32. \url{http://ancienttl.org/ATL_32-2_2014/ATL_32-2_Mauz_p24-32.pdf} #' #' Nathan, R.P., Mauz, B., 2008. On the dose-rate estimate of carbonate-rich sediments for trapped charge dating. #' Radiation Measurements 43, 14-25. \doi{10.1016/j.radmeas.2007.12.012} \cr #' #' **Further reading** #' #' Nathan, R.P., 2010. Numerical modelling of environmental dose rate and its application to trapped-charge dating. #' DPhil thesis, St Hugh's College, Oxford. \url{https://ora.ox.ac.uk/objects/ora:6421} #' #' Zimmerman, D.W., 1971. Thermoluminescent dating using fine grains from pottery. #' Archaeometry 13, 29–52.\doi{10.1111/j.1475-4754.1971.tb00028.x} #' #' @keywords dplot manip #' @md #' @export model_DoseRate <- function( data, DR_conv_factors = NULL, length_step = 1L, max_time = 500L, n.MC = 100, method_control = list(), txtProgressBar = TRUE, verbose = TRUE, plot = TRUE, ... ){ # Self-call ----------------------------------------------------------------------------------- ##we keep it as simple as possible, only a data.frame is allowed, all subsequent tests ##are handed over to the code below if(class(data) == "data.frame" && nrow(data) > 1) { ##split input in a list data_list <- split(data, f = 1:nrow(data)) ##get provided arguments ##by using this option we do not have to double check in future whether we missed arguments args <- as.list(match.call()) ##remove first (the function name) and 'data' args[[1]] <- NULL args$data <- NULL ##run function results_list <- lapply(data_list, function(x){ temp <- try(do.call(model_DoseRate, c(list(data = x),args))) if(class(temp) == "try-error"){ try(stop(paste0("[model_DoseRate()] Calculation for sample ", x[[1]], " failed. NULL returned!"), call. = FALSE)) return(NULL) }else{ return(temp) } }) ##remove NULL elements from failed attempts results_list <- results_list[!sapply(results_list, is.null)] ##combine into one single data.frame results <- do.call(rbind, results_list) ##return return(results) } # Integrity tests ----------------------------------------------------------------------------- ##NOTE: The integrity tests are done mainly here and not in the function '.calc_DoseRate' to ##avoid additional overhead ##checks for data if (class(data) != "data.frame") stop("[model_DoseRate()] 'data' is not a 'data.frame'", call. = FALSE) if (nrow(data) == 0) stop("[model_DoseRate()] 'data' is empty!", call. = FALSE) ##remove NA values if (any(is.na(data))) { data <- na.exclude(data) warning("[model_DoseRate()] 'data' contained NA values; removed.", call. = FALSE) ##re-check; maybe it is empty if (nrow(data) == 0) stop("[model_DoseRate()] 'data' is empty!", call. = FALSE) } ##Now check against the example data Example_Data <- NULL data("Example_Data", envir = environment()) ##check columns if (ncol(Example_Data) != ncol(data) && !all(colnames(Example_Data) == colnames(data))) { stop( "[model_DoseRate()] The column names of your input data.frame do not match the requirements. Please check the example dataset via 'data(head(Example_Data))' to see how it should look like!", call. = FALSE ) } ##remove example data rm(Example_Data) ##check n.MC if(is.null(n.MC) || n.MC[1] <= 1){ n.MC <- 1 txtProgressBar <- FALSE } # Rewrite variables names to match the MATLAB code -------------------------------------------- ERROR <- n.MC[1] STEP1 <- length_step[1] # Prepare data -------------------------------------------------------------------------------- ##load reference data here; we do not provide the option to the user to add it here Reference_Data <- NULL data("Reference_Data", envir = environment()) ref <- Reference_Data rm(Reference_Data) #select dose rate conversion factors and check allowed values if(!is.null(DR_conv_factors) && !any(DR_conv_factors %in% ref$DR_conv_factors$REFERENCE)){ temp_allowed <- paste(ref$DR_conv_factors$REFERENCE, collapse = ", ") stop(paste0( "[model_DoseRate()] '", DR_conv_factors, "' does not correspond to an available dose rate conversion dataset. Allowed are: ", temp_allowed), call. = FALSE) } ##set what is set (but not with the same name here) set_DR_conv_factors <- DR_conv_factors ##minimise potential user problems max_time <- max_time[1] ##method control method_control_default <- list( trace = FALSE, lower = 0, upper = max_time ) method_control <- modifyList(x = method_control_default, val = method_control) # Run optimisation ---------------------------------------------------------------------------- ##+++++++++++++++++++++++++++++++++++++++++++++++++++++++++ ##AGE ##find minimum DATE <- nlminb( start = STEP1, objective = .calc_DoseRate, control = list( trace = method_control$trace), lower = method_control$lower, upper = method_control$upper, data = data, ref = ref, DR_conv_factors = set_DR_conv_factors, length_step = STEP1, mode_optim = TRUE ) ##calculate values with minimum value DATE <- .calc_DoseRate( x = DATE$par, data = data, ref = ref, DR_conv_factors = set_DR_conv_factors, length_step = STEP1, max_time = max_time ) ##+++++++++++++++++++++++++++++++++++++++++++++++++++++++++ ##UNCERTAINTIES ##ceate needed objects according to MATLAB code DE_ <- numeric(ERROR) DR_ <- matrix(0, nrow = DATE[["LEN"]], ncol = ERROR) DRA_ <- matrix(0, nrow = DATE[["LEN"]], ncol = ERROR) CUMDR_ <- matrix(0, nrow = DATE[["LEN"]], ncol = ERROR) AGE_ <- numeric(ERROR) AGEA_ <- numeric(ERROR) ##create variables we want to use (we do not do this in the loop as in MATLAB) ##TODO: We should evtl. set all values below 0 as NA and remove such lines; this might ##be better than setting it to 0. However, for the moment this is precisely what Carb did before DE <- data[["DE"]] + rnorm(n.MC) * data[["DE_X"]] DE[DE < 0] <- 0 COSMIC <- data[["COSMIC"]] + rnorm(n.MC) * data[["COSMIC_X"]] COSMIC[COSMIC < 0] <- 0 INTERNAL <- data[["INTERNAL"]] + rnorm(n.MC) * data[["INTERNAL_X"]] INTERNAL[INTERNAL < 0] <- 0 ONSET <- round(data[["ONSET"]] + rnorm(n.MC) * data[["ONSET_X"]],0) ONSET[ONSET < 0] <- 0 ONSET[ONSET > max_time] <- max_time FINISH <- round(data[["FINISH"]] + rnorm(n.MC) * data[["FINISH_X"]],0) FINISH[FINISH < 0] <- 0 FINISH[FINISH > ONSET] <- ONSET[FINISH > ONSET] DIAM <- data[["DIAM"]] + rnorm(n.MC) * data[["DIAM_X"]] DIAM[DIAM < 0] <- 0 CC <- data[["CC"]] + rnorm(n.MC) * data[["CC_X"]] CC[CC < 1e-03] <- 1e-03 WCF <- data[["WCF"]] + rnorm(n.MC) * data[["WCF_X"]] WCF[WCF < 1e-03] <- 1e-03 WCI <- data[["WCI"]] + rnorm(n.MC) * data[["WCI_X"]] WCI[WCI < 1e-03] <- 1e-03 K <- data[["K"]] + rnorm(n.MC) * data[["K_X"]] K[K < 0] <- 0 U <- data[["U"]] + rnorm(n.MC) * data[["U_X"]] U[U < 0] <- 0 T <- data[["T"]] + rnorm(n.MC) * data[["T_X"]] T[T < 0] <- 0 ##now combine everything in a data.frame, not efficient but ##we want to stick as close ##as possible with the MATLAB code (the order does not matter) data_MC <- cbind(K, T, U, U238 = rep(data[["U238"]],n.MC), U234_U238 = rep(data[["U234_U238"]],n.MC), WCI, WCF, CC, DIAM, COSMIC, INTERNAL, ONSET, FINISH, DE ) rm(K,T,U,WCI,WCF, CC, DIAM, COSMIC, INTERNAL, ONSET, FINISH, DE) ##set txtprogressbar if(verbose && txtProgressBar) pb <- txtProgressBar(min = 1, max = n.MC, style = 3) ##start loop for(i in 1:n.MC){ DATE_MC <- suppressWarnings(nlminb( start = STEP1, objective = .calc_DoseRate, control = list( trace = FALSE), lower = method_control$lower, upper = method_control$upper, data = data_MC[i,], ref = ref, DR_conv_factors = set_DR_conv_factors, length_step = STEP1, mode_optim = TRUE )) ##calculate values with minium value DATE_MC <- .calc_DoseRate( x = DATE_MC$par, data = data_MC[i,], ref = ref, DR_conv_factors = set_DR_conv_factors, length_step = STEP1, max_time = max_time ) ##fill variables DE_[i] <- data_MC[i,"DE"] DR_[,i] <- DATE_MC$DR DRA_[,i] <- DATE_MC$DRA CUMDR_[,i] <- DATE_MC$CUMDR AGE_[i] <- DATE_MC$AGE AGEA_[i] <- DATE_MC$AGEA ##update progressbar if(verbose && txtProgressBar) setTxtProgressBar(pb,i) } ##close pb if(verbose && txtProgressBar) close(pb) # Extract final values ------------------------------------------------------------------------ ##extract all values we want to return in the terimal and in the results data.frame data_results <- round(data.frame( AGE_CONV = DATE$AGEA, AGE_CONV_X = sd(AGEA_), AGE = DATE$AGE, AGE_X = sd(AGE_), DR_CONV = DATE$DRA[1], DR_CONV_X = sd(DRA_), DR_ONSET = rowMeans(DR_)[nrow(DR_)], DR_ONSET_X = sd(DR_[nrow(DR_),1:n.MC]), DR_FINAL = rowMeans(DR_)[1], DR_FINAL_X = sd(DR_[1,1:n.MC]), n.MC = as.integer(n.MC[1]) ),3) # Terminal output ----------------------------------------------------------------------------- if(verbose){ cat("\n[model_DoseRate()]\n\n") cat(" Sample ID:\t\t", data[["SAMP_NAME"]], "\n") cat(" Equivalent dose:\t", round(data[["DE"]],2), " \u00b1 ", round(data[["DE_X"]],2), "Gy\n") cat(" Diameter:\t\t", data[["DIAM"]], "\u00b5m \n") cat(" MC runs error estim.:\t", n.MC," \n") cat(" ------------------------------------------------ \n") cat(" Age (conv.):\t\t",data_results[["AGE_CONV"]], " \u00b1 ", data_results[["AGE_CONV_X"]], " ka\n") cat(" Age (new):\t\t", data_results[["AGE"]], " \u00b1 ", data_results[["AGE_X"]], " ka\n\n") cat(" Dose rate (conv.):\t",data_results[["DR_CONV"]], " \u00b1 ", data_results[["DR_CONV_X"]], " Gy/ka\n") cat(" Dose rate (onset):\t",data_results[["DR_ONSET"]], " \u00b1 ", data_results[["DR_ONSET_X"]], " Gy/ka\n") cat(" Dose rate (final):\t", data_results[["DR_FINAL"]], " \u00b1 ", data_results[["DR_FINAL_X"]], " Gy/ka\n") cat(" ------------------------------------------------ \n") } # Plotting ------------------------------------------------------------------------------------ if(plot){ ##set plot settings plot_settings <- modifyList(x = list( mfrow = c(2,1), xlim = c(0, max(c(DATE[["AGE"]], DATE[["AGEA"]])) * 1.1), xlab = "Time [ka]" ), val = list(...)) ##par settings; including restoring them par.default <- list(mfrow = par()$mfrow) on.exit(do.call(par, args = par.default)) par(mfrow = plot_settings$mfrow) ##calculate some variables needed later DR_rowMeans <- rowMeans(DR_) DR_rowSds <- matrixStats::rowSds(DR_) CUMDR_rowMeans <- rowMeans(CUMDR_) CUMDR_rowSds <- matrixStats::rowSds(CUMDR_) ## +++++++++++++++++ ##(A) dose rate plot plot( NA, NA, xlim = plot_settings$xlim, ylim = if(n.MC > 2){ range(c(DR_rowMeans - DR_rowSds, DR_rowMeans + DR_rowSds)) }else{ range(DR_rowMeans) }, xlab = plot_settings$xlab, ylab = "Dose rate [Gy/ka]", main = data[["SAMP_NAME"]] ) ##abline abline(v = 0, lty = 2) text(x = 0, mean(DATE[["DR"]]), labels = "(sampling)", srt = 90, cex = .5, pos = 2) axis( side = 3, at = c(data[["ONSET"]], data[["FINISH"]], DATE[["AGE"]]), tick = FALSE, labels = c(expression(t[m[0]]),expression(t[m[1]]), expression(t[0])), padj = 1.2) ##error polygon polygon( x = c(0:max_time, max_time:0), y = c( DR_rowMeans + DR_rowSds, rev(DR_rowMeans - DR_rowSds)), col = rgb(0, 0, 0, .1), border = NA ) ##add center line lines(x = 0:max_time, y = DATE[["DR"]], lwd = 1) ##set mean line (give a good indication whether the n.MC runs had been enough) lines(x = 0:max_time, y = rowMeans(DR_), lwd = 1, lty = 2, col = "blue") ## +++++++++++++++++ ##(B) accummulated dose and age plot( NA, NA, xlim = plot_settings$xlim, ylim = c(0, data[["DE"]] * 1.2), xlab = plot_settings$xlab, ylab = "Absorbed dose [Gy]", main = data[["SAMP_NAME"]], sub = paste0("(n.MC = ",n.MC,")") ) ##add error polygon polygon( x = c(0:max_time, max_time:0), y = c( CUMDR_rowMeans + CUMDR_rowSds, rev(CUMDR_rowMeans - CUMDR_rowSds)), col = rgb(0, 0, 0, .1), border = NA ) ##lines showing the De distribution used for MC runs density_De_y <- seq(0, data[["DE"]] * 1.2, length.out = 100) density_De_x <- (1 / sqrt(2 * pi * data[["DE_X"]]^2)) * exp(-(density_De_y - data[["DE"]])^2 / 2 * data[["DE_X"]]^2) ##this looks weird, otherwise the plot is not really right and we have overplotting ##issues density_De_x <- (density_De_x * -par()$usr[1])/ max(density_De_x) + par()$usr[1] density_De_x[which.min(density_De_x)] <- min(density_De_x) density_De_x[density_De_x <= par()$usr[1]] <- par()$usr[1] - 0.2 lines(x = density_De_x, density_De_y, col = "red") ##centre lines horizontal (De) lines( x = c(0, DATE[["AGE"]]), y = rep(data[["DE"]], 2), col = "red", lty = 2 ) ##center lines vertical (age) lines(x = rep(DATE[["AGE"]], 2), y = c(0, data[["DE"]]), col = "red", lty = 2) ##add density (two times, 1st density lines, then colour) if(n.MC > 1){ temp_density <- density(AGE_) polygon( x = c(temp_density$x, rev(temp_density$x)), y = c((temp_density$y * data[["DE"]]) / max(temp_density$y), rep(0,length(temp_density$x))), lty = 1, density = 10, col = "grey" ) polygon( x = c(temp_density$x, rev(temp_density$x)), y = c((temp_density$y * data[["DE"]]) / max(temp_density$y), rep(0,length(temp_density$x))), lty = 0, col = rgb(1,0,0,.2) ) } ##add lines of absorbed dose lines(x = 0:max_time, y = DATE[["CUMDR"]]) ##add central point points(x = DATE[["AGE"]], y = data[["DE"]], cex = 1.4, pch = 21, col = "red", bg = "grey") ##add mtext mtext(side = 3, text = paste0("Age: ", round(DATE$AGE,2), " \u00b1 ", round(sd(AGE_),2), " ka")) }#end plot # Return value -------------------------------------------------------------------------------- ##the return value is the input data.frame + added lines results <- cbind( data, data_results, stringsAsFactors = FALSE ) ##add attributes to data.frame attr(results, which = "package") <- "RCarb" ##return return(results) }RCarb/vignettes/0000755000176200001440000000000013475061757013272 5ustar liggesusersRCarb/vignettes/GetStarted.Rmd0000644000176200001440000001416213470230566015777 0ustar liggesusers--- title: "Get started with RCarb" author: "Sebastian Kreutzer1 & Barbara Mauz2" 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} --- 1IRAMAT-CRP2A, UMR 5060, CNRS - Université Bordeaux Montagine (France)
2Department 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 RCarb/vignettes/GetStarted.html.asis0000644000176200001440000000023213355136342017147 0ustar liggesusers%\VignetteIndexEntry{Get started with RCarb} %\VignetteEngine{R.rsp::asis} %\VignetteKeyword{HTML} %\VignetteKeyword{vignette} %\VignetteKeyword{package} RCarb/README.md0000644000176200001440000000610113475061750012530 0ustar liggesusers # RCarb [![CRAN](http://www.r-pkg.org/badges/version/RCarb)](https://CRAN.R-project.org/package=RCarb) [![Downloads](http://cranlogs.r-pkg.org/badges/grand-total/RCarb)](https://www.r-pkg.org/pkg/RCarb) [![Build Status](https://travis-ci.org/R-Lum/RCarb.svg?branch=master)](https://travis-ci.org/R-Lum/RCarb) [![Build status](https://ci.appveyor.com/api/projects/status/bjfy5lkqblrgvo15?svg=true)](https://ci.appveyor.com/project/RLumSK/rcarb) [![codecov](https://codecov.io/gh/R-Lum/RCarb/branch/master/graph/badge.svg)](https://codecov.io/gh/R-Lum/RCarb) The **R** package ‘RCarb’ provides a collection of various R functions to model dose rates in carbonate-rich samples. The package is a translation of the ‘MATLAB’ program *Carb* by Roger P. Nathan. ## Installation of the developer version To install the latest development builds of ‘RCarb’ directly from GitHub, run ``` r if(!require("devtools")) install.packages("devtools") devtools::install_github("R-Lum/RCarb@master") ``` To install a developer build other than ‘master’, replace the term ‘master’ in the codeline by the name of the wanted developer build (not available yet). Please further note that our ‘GitHub’ versions are developer versions and subject to daily changes. For stable please versions download the package from [CRAN](https://CRAN.R-project.org/package=RCarb). ## License This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or any later version. This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the [GNU General Public License](https://github.com/R-Lum/RCarb/blob/master/LICENSE) for more details. ## Related projects - [Luminescence](https://github.com/R-Lum/Luminescence) - [RLumModel](https://github.com/R-Lum/RLumModel) - [RLumShiny](https://github.com/R-Lum/RLumShiny) ## References Nathan, R.P., Mauz, B., 2008. On the dose-rate estimate of carbonate-rich sediments for trapped charge dating. Radiation Measurements 43, 14–25. doi: [10.1016/j.radmeas.2007.12.012](https://dx.doi.org/10.1016/j.radmeas.2007.12.012) Mauz, B., Hoffmann, D., 2014. What to do when carbonate replaced water: Carb, the model for estimating the dose rate of carbonate-rich samples. Ancient TL 32, 24–32. **Further reading** Nathan, R.P., 2010. Numerical modelling of environmental dose rate and its application to trapped-charge dating. DPhil thesis, St Hugh’s College, Oxford. ## Funding Between 2018-2019, the work of Sebastian Kreutzer as maintainer of the package was supported by LabEx LaScArBxSK (ANR - n. ANR-10-LABX-52). RCarb/MD50000644000176200001440000000316113475122242011556 0ustar liggesusersecbc5116d26ddb7234ea1df5c32a7fa0 *DESCRIPTION b64e46a0584ad27aa375dbaa291f3ed6 *NAMESPACE 45b35eaff436aa066ec28da1b05278d5 *NEWS.md 37823eb4a2c60737726278ccb0a08047 *R/RCarb-package.R ca118ed01e4b7171c8dc5220315f04af *R/calc_DoseRate.R eb8c33d573dc3dfb9b96b2d1ef6a99c4 *R/internals_RCarb.R 7bbd79454c13e4bcd38d8afe0a8f9455 *R/model_DoseRate.R 06cb81a161d673471db1e9f1797bd7cf *R/write_InputTemplate.R 19f6ebd7baaa18064fdd859035f22edd *README.md 42169a1e076b7fb6393fc6b2ca46673e *build/partial.rdb 1d97e9a73602fe3f41b913fbc2b415d3 *build/vignette.rds 19213478bfe3b7caa1199d5acc0581cb *data/Example_Data.RData df1e2a08bf99c7009b09024dc39f7591 *data/Reference_Data.RData c74ea853cdb6bddad42697fbb4ed148f *data/datalist 71edbce3b3c80492447819cd3cf453da *inst/doc/GetStarted.html 47830939a2d0630243e3589fe76f1cc9 *inst/doc/GetStarted.html.asis b38ea5686271048df6bde6b2374fe9eb *man/Example_Data.Rd e06ee295542b6db0179443b18b1f94a0 *man/RCarb-package.Rd e7040a70ee3acb48f42327edf8614423 *man/Reference_Data.Rd bb07a884909ce8cbd852ae5eb815bbfa *man/figures/Logo_RCarb.svg d4d197e3c97b24cefb4ccde4055f9dee *man/figures/README-unnamed-chunk-2-1.png baf34e2e2262d94e2c57faba14f27d69 *man/model_DoseRate.Rd 5553bd99c5712c99ae17c5243effd0cc *man/write_InputTemplate.Rd 7fed4fcac118ef18b192f1a1ef4ec33b *tests/testthat.R 1da9c063b1ef3ce6d2d7f9b9b14a4cc6 *tests/testthat/test_.cal_DoseRate.R e2c4913a04d3652a630a9abe8a725ea9 *tests/testthat/test_model_DoseRate.R bc5b339437189b193ed3a293dc45d023 *tests/testthat/test_write_InputTemplate.R f9c794dedc601ca2b65ee56fa0840b15 *vignettes/GetStarted.Rmd 47830939a2d0630243e3589fe76f1cc9 *vignettes/GetStarted.html.asis RCarb/build/0000755000176200001440000000000013475061757012361 5ustar liggesusersRCarb/build/vignette.rds0000644000176200001440000000035213475061757014720 0ustar liggesuserseP˪@ : ' FU~v.i)*JXk6u;Sjߟ ,aT` drv+P$,_Y[eDyOO?n!A"tW؝E+!3g?05G?6 ;z1~ڴ,tzțbHMZ{OgURCarb/build/partial.rdb0000644000176200001440000003740013475061756014511 0ustar liggesusers}YsYv^\vlT6 &@ {+:2 ͬbf@ӞF5^ Yp#OvHw+pĴdխB& Èsνg{~~Pi^ (=>b2%;BJ[2_nF~(&1LUP$i_ ʚ#SJ٥ŹǫVR+T}*U/'9!'FT4c<o5ھ7H~Gȵ:h>u~sYm{\5V~^vܺb?:l2@ٺmFnVbj٭W {T~_97JJq^Ϯf N^]ںnWRCӕDT.]feu\^W3NST:$j%VN2G~QI9lO[ SN K}(1/e]m;b5pdG3 *>R{d=(48\>' bJӋP( }$P\=W=G>|cbUڌOsA2EW"4XbE]PكR0Iw`# t?\li̍|6(>JB] ] fbkea @BG?C1F(۱LWmq$OF9]րx̳ɏn7Sg%+jIM6#Km8T6ɚBYޤڍzݴU "-gH?bEKJyƺry\E#C(΍f~ʏ 3ORllG(ikL;ҥ {C߉*tVV5i'4pdqf -V>@;,GRې RR鐑0CʀOm:Y1u܄! }H`gO)_;I{># 8b\?D)?MbIZsh@.c٩ e`!KlMˠG{htn3o (YႬh|Q톥r''R$7O (0átw,/Wj7tǾm))ۡlƳ׎itAYS|n<]~dFuv3㹼OV 3%E/!!=TQx\m!ދ;gea;D[ *̇Qw3*4ٱ4q'Ƚߌu]ɝaNˮ2%g*fR6o c' g׫~ҁ|[ig([ej}E[o d;L\]6ٞhRTW G:Eڝ'ޢVQuk7q[@A}?,aq;{`w􁢨|$=^}ѶelL7,:2PX"_<w`M sI7?#`4p19sqFM { Q 6 dC!c`g5f5/"=vo0_ckv8Ac:bYSu5E^VLK wȓ.{lvSgZaw}}jL{}0Lgo]p%񡣭>]Tk *mxXP6TfiUvdMTB=WUUm]}_{0eu'i`{/f٬!棧Wi8jل:uJӪɝXS)>rC Yo=%P`shK^od۰;6hS3+SmHA+γ"(ӎ@|"=ܪ3NyukCnQ131MlQkګgKtI*6$Z󁓞ʮR[Rjoy?ajMD0j;x~V/<-}ǔ3|b`Gn;vݮn;JF{G`{гv|@8SpBZd ##z[ޭH \zO]0 2(G룭z98UFHc9#߮q#d{s{y4gy-\ J쑲ct :5}uKӡ :C}O׸laS\ϸG(W3^|ڻm)v]6Ů;CvOvPtW/-}nE"bŹxa$BoYp--AEp'!cHN%K\fru?Qaj}Gcs5ٱ4 |'Q@g$~?lϘg "]ټ|g(EC c3^G$yIK бfQV"IlZ?bD*r1-~_b ZW:fFRm@L5w^Ri״!sXґR&wu5[@ #`7t l:ɧ#:_:|Wj5L~OHTB?Gd$"tKD1񄔟'RB&!tjH8Ϲ$ӈ簄 avvMrAKRج./"RYVN@$~@ \V[Wa$D|jrR՛A/I˿叓OK(Q>sҠ~1B.G .bnNaN AAn4Y$h/JւI At50U1x[vgI;K*A9?O>K,F~b2pFxL~\K-]% s.$܅(m.%׋]% ɏUFI_NFA3$aRY "LљGg%`KXcJ7g% :Ι3dq΍!œ؍|fqCƐ sf !;'mK,#FPk?!,ϗ Is!ߚ $8Br7vq lF3{ o^a #N68B:unb#$.<…]!C!!#[2BaN#&8B:ugIζ棓#9GH'97|OFG!vٝ0C9$gG]:!{mb<'d9FP{?%<|N-I is);.SmI#`s)Μa9IA؝0L<'v1'lONꫩ(rUj%? \;<#W#J{ bH uA;J Y)!(@̐JӼ/ŵL\ @ˈp3>l&Ziq,n?] %ՑӊiDvhW]mzCIECWdݒ52cf5HLFs7 S9ğJ۟%鷈vP4p*:] # keXs;zGi tz܅HD@ w|tPHtYFĒm"~t׳qRn"L]'$b|7?b ZM&,7+J 4ղTfa!U( 4 Atɵ^وyzzWxr-<^ƽ{O~XBިD|}i.9>pKV4/cO6Oʲ^Vڙ&,#]huR>lڎ*+Ĭzm53R_ycj9)R)J9t56/;\TTliuPǨ>ͶϣծDVHmf 4 l[{R7d$a|Tˋހ_#ud-7]ŁXD(^FFYW!L1͙lY7pA€HodmbCl7+ hXtj\Vھ5Dadbx.xF"ޥҜWcMA *v1df00`XmsGf|NDi!Mچl4ӏ1AF% H>:5[>a&Q N+dQnqX&R"KH/dw6`X@$-F T*[ܰږj , ܏xPtO;3x;7!H@,Ip1\>TlmP-b8WÒ QK(FmQ+#6vK++/ ͰiGVQvT{-󚮒ѹ+ǘdeFz:6?]ut61 )zf\ᮏ#>Eil>ذt?CM;X>=K,#HezT>IM)3O)麩{^Say·T_[yOVn_W5SԲgKlȆ sSSc;~]J;l6:+JKG%!%7_’%ꔮk6nmǬİZm[WgL!~HYGR;L>\J.c` !r@r6-~EW+nu1D&p_Nw=hJ* a2ML@Yv1Lj%d SdCv">Da3>aױ?A?KL =8_@oD6H{Ҟ᯽)B(,tD<0I(\_"MK3xPalKE|,{@|B{s1FC%o*.T8$ ݪ_9 $憭5)h7iCmgF|G"b BE>a;VE(کvgxXҧ`rw//}yen6Vk}ѲDTqI|IE,k>.C}:v+Q)$cݛ72>\INx2 xkml0GVHZL\ljaį$/o2 A,JO~`,<ƭ]ÅbEJǢS1(3E PE@ Jls}7ӹ5жJkh>w <<*zI-+ 3b KCPvKǵq鱀I.ǥXcK!T%i1\'.CO3[jިijݣU>s]3ϳg(Kk|`YF= DM~9z~2=@ TbSK5b<dU)dWL$EeA:][ՔfgX͓͘@i 7AǒuU!ԑu{ * h"mFVzUnX*{rƐt~*xeFz8=n}evCwۖy]]jhc===]P5F/Ǿ/8sײd,YQ]3]gr M>:?Y+,|8\PEۣz.shg D Rχ)gTicU'iۦ! ;Xוܩ*u~Ɉy{C$LCE,Yܦ$nl]u?*t _VyY/VZ_e[gc'n7'*{hM3ZUNCu~vɶUT:71<1˦a+w|H1E%[%AMgP}P ǜ2qS} t*lN<(릣P9;,MG>EU_ "cNC4֫#65u]]WSd%Z+GcHpӒ3ˌ\4g7l|.`Q+H:h ]E\Ez5tEI>}}~Y;KĒžs`6a'0{cᾐI7@r勺/& 9n`F@,I!1|Թ 2SɲnPp(,"kY~ĭYaV|Y?~(?A ?*"h37Y3 4ՠVoR˖n5>=^aB$+x&( gX? ez|*tyNg&Ӣ8q:|'F\&?9~Ǒ-[+C8]qd~g*=~#=~3_QX7dhNPq E~fU-W "e ]jXACFX'pX)!k +!yQ9Yk2d*UvnLC Υ#\ѡ_tۡT4p8fFG}lÆ2_݃OhZ桠JwCE.c7i!s/ÏcP4O3 ;C-y3@yEJĀQW:v1J OOBf^ƏPR"ȳ$UM}.[d{+f# wݥ .3m or,CRKY)ZP4TPfQGO:ߠ&H/6.:TlD`~> <1p z`%٪cJFHխMR|8A<'?.`3Om<5T[JwC}K~/V.ηdM\f_d떶!;jvCSWhnNS\ݶ''ʹVzUÿzv5[pju-m0|\6eWzfi(~,6EA>fSw\eڽ9½N2_nF~(&1L\J\c/b׉?Χq?m9gM>PH*fn/CwORˎkGEoM}SvQvs漽y+H̡ )- ׸p6w, +fYh)lknуRE QŁKa %81ꀒF'=+w%cIc?ǝ;xs1|.zv>ٌ{h/ ^Dbl>K},o$TYi#6{A!AGzW39%9nj!Z*x۱T xq'>A| tU+*oa';Ȳ}mthnQ-f|7_Qka>n8Qi Mcd_ei T%PAnF F^sԚO_eVp^%Dǐez]īH_0b Tlrrؽo*gj HO҈~Х&z ҟDLJ;Yuv^t9z s8t%Frj5D&:&Y~ 1^5/ }!&K%aZ2(ңɴE1O q,m}^.LuKG!*C h H>A/cd3q;XM3>$P ÒQԶ5{z ~=p"OF)29U7A[ M$ofƆ"t6pt>io q;)1^}^ҝ"=x<u<ҡNy<;xp}=6M5BnZNlUhoǂ!" Р=$cX4ր`R@`B1ΌZ3H ]~w#'ܜVJIآi貥jv{W-R=qQA:lF ,Q=`_KbSӻ7'WjuCoB* 񭉽mP"~>skH8z!ZkDisCyެ HדXր{J@.J< =6\,əsH'p">xmǙsXb{֌1#XU>~PxX.Ēk]ÂCi%ŗ^] &8JCfé74YHǹC[^{bIZawf2A0\EG?vAk.vkΣa(FguSVU"SdQ\zcUa[_.# XebA( @s|(O鿈>THelM葉´AҿJE_!W]jHu-"´@&FO1a"nK|[@,1iL(KQ{*=b Gf.UD: ˰| \n*wJ~#xRtAHÓ|d-~})5 "ቯ's3 dU,hzxPX8(,%c/$oX>W +~Dh?8pXbnpӫx[FKfHzH (ܱS 3ҡaiH`׏xPmհ:ķJK5+W\1tl9T韺2"VV}ƵW^Y}uJZjI րom3&]W~Dػ 3"u=%L9xCb_z氁we`>b]؏ޕ#w1jUgD9^W-3P0"ڏxő."6Lܠî-~md f/u!hK>'+HW"RLuK"vUβʴ qa>mk5Ocdk]3P_EЫ̦iUVAQY;/9[n?ڴ!Yش5a6x,etqvˀeڃE4ﱴlBejjoךiQUu 6(eVpfgcT r~x;ɇ``X:V1g0.GL47ǘ ɪ;ex[ɽl xDd{$xԺ͗`1͑ D0.j+78V>[琸-5?& ]QeViClfnU@QՂbmO,❮ABz 8o.*]z6[w!w+\!CQŁ}P⧫ۑ-FI y 4Ͱ>kFc4A5pȚ]㞒dg)+Zx[`ZuRr/褩qI}93`Pw嵏̆{au 7:ʛu98r`j@NE.WiAŚfXP5jɶݨ l [Bw55M<Ǥk;iEUV9(a", gUԘF~ PiSLYUŵ{KrYU&ɚf>4Ǯl uՊ8̌QȎ.86u[uhБ1D>XM~V^s5JOs> Fuli_a>\?D)?M> oĒ4 ͦ!KFsOB'iў*ÇmezFxS:[?&le[B^n٦pAV4vRܓ)L{zeFz8=n}EG ݱo[Jvhvʳ׎itAYS]xZ%+5k^ʕ>S.7x2WX-,(z q鹠G*>|/vQ_S #u)gTicU'f? ;Xוܩҗ]s?>hnI䙢YTMo؄I{9.V :Uqv֋UFulWlLd fD,VCl3CYA衺W?Vd[*X#b O t>qòi|vϷc47[%oJ>}~" $>s1Cx.=o,7l xP3>^ @hI7?# /cy>y>3q|_ ~Ϛ+H{W0Rt6~ucW8&`ch7&`c.XU7ݪ=b^)7]z9wy ߐ"m)JnH ҃5I_񹺵I=CH%&Xjlh"mb;l&&mM|m3Ֆ:!>GZÍ-Y.=ٺmȎݐlڥnNS\ݶ''ʹVzUÿzv5[phYںnW099ȗʥkx~B\mh{>fS{Q#x h̲\_r-RCarb/DESCRIPTION0000644000176200001440000000263413475122242012760 0ustar liggesusersPackage: RCarb Type: Package Title: Dose Rate Modelling of Carbonate-Rich Samples Version: 0.1.3 Date: 2019-06-02 Author: Sebastian Kreutzer [aut, trl, cre, dtc] (), Roger P. Nathan [aut, cph], Barbara Mauz [aut, cph] () Authors@R: c( person("Sebastian", "Kreutzer", role = c("aut", "trl", "cre", "dtc"), email = "sebastian.kreutzer@u-bordeaux-montaigne.fr", comment = c(ORCID = "0000-0002-0734-2199")), person("Roger P.", "Nathan", role = c("aut", "cph")), person("Barbara", "Mauz", role = c("aut", "cph"), comment = c(ORCID = "0000-0003-1504-333X"))) Maintainer: Sebastian Kreutzer Description: Translation of the 'MATLAB' program 'Carb' (Nathan and Mauz 2008 ; Mauz and Hoffmann 2014) for dose rate modelling for carbonate-rich samples in the context of trapped charged dating (e.g., luminescence dating) applications. Depends: R (>= 3.4.0), utils Imports: interp (>= 1.0), matrixStats (>= 0.54.0) Suggests: testthat (>= 2.1), R.rsp (>= 0.43.0) URL: https://r-lum.github.io/RCarb/ BugReports: https://github.com/R-Lum/RCarb/issues License: GPL-3 Encoding: UTF-8 LazyData: true VignetteBuilder: R.rsp RoxygenNote: 6.1.1 NeedsCompilation: no Packaged: 2019-06-03 00:03:59 UTC; kreutzer Repository: CRAN Date/Publication: 2019-06-03 04:40:02 UTC RCarb/man/0000755000176200001440000000000013475061757012035 5ustar liggesusersRCarb/man/figures/0000755000176200001440000000000013475061757013501 5ustar liggesusersRCarb/man/figures/Logo_RCarb.svg0000644000176200001440000001437013470227122016161 0ustar liggesusersLogo_RCarbRCarb/man/figures/README-unnamed-chunk-2-1.png0000644000176200001440000012336313406151434020166 0ustar liggesusersPNG  IHDRz4iCCPkCGColorSpaceGenericRGB8U]hU>sg#$Sl4t? % V46nI6"dΘ83OEP|1Ŀ (>/ % (>P苦;3ie|{g蹪X-2s=+WQ+]L6O w[C{_F qb Uvz?Zb1@/zcs>~if,ӈUSjF 1_Mjbuݠpamhmçϙ>a\+5%QKFkm}ۖ?ޚD\!~6,-7SثŜvķ5Z;[rmS5{yDyH}r9|-ăFAJjI.[/]mK 7KRDrYQO-Q||6 (0 MXd(@h2_f<:”_δ*d>e\c?~,7?& ك^2Iq2"y@g|U\ @IDATxxEOBI޻HA)R( ~'||D@PEHo"Uz齓?{[MH67;ϳlg9REXHHHHH!݇!    M/ (@͛ P    py3     P$@$@$@$@u7oF$@$@$@$@wHHHHQHHHH(@ 8JQܼ (    G P:7#   ;@$@$@$@$( PGqf$@$@$@$@|HHHH%@(nތHHHH (@͛ P    py3     P$@$@$@$@u7oF$@$@$@$@wHHHHQHHHH(@ 8JQܼ (    G P:7#   ;@$@$@$@$( PGqf$@$@$@$@|HHHH%ѻf$@$L\~]t{[lYӧߞϙ3G 7iD^{5u{)[lK)TU/&&Fڷo/:K/do?^͛'G*UHݥdɒVqɦM}_:uJ*:c$@$0*܉7! dDڵk.]:… ĉ?~h͓'>|X"""w!7nZ#DM^zɈ#.)k a:ydkYf3gʽޫiFf̘Vsgڴi{> 8FCHR*ܹsKƍ?~ܧX>}!iJtt <zѢElذ 0@e&ΝW_}ժ+W.)X`]T)>7HH )p>)$@)O:uʲB$-ZTZ`E)XC`ԨQCOl7o+]-[f6 .SOy py? I C KӧO@!~( , oݺպ֜1LI}*|6mZ=z*u^:6z}O۶mBM$@IE4$@)>ͫ~Wjk(Q6m*9sqV4iq+^T;w̞=[vH?^IvH7^zGC?^~{\LA )˗lZkDף.]ZJHBh| @ `D4~ϒ%h"^Ϙ#GϞ=ka߶3-]Tڵu 7HH P§> իWG<ϟ?_?7HTpa}}#RX1ט-X^իv;$@$q&J$@$ov!DCt \d˴(OK߾}uĉ塇C˳g5ъ+SuZA$@IH4 $@Ƀ͛IBRI&=`Af7^g}V}9sN^I矗39Q03׳ @(|(} @ ZjYc=b: 5kXVOLՒ~z  \!vHH HHtnGnQ Hn(@' @2'tÆ bw`3o^2HHHH|)@6ӷŧԩS4>x ~0eCاK%$@$@$@$@q$ZxqtR} ?tHB$@$@$@$@i>}`67nXc;vȵk $F2-[u7J|ٳAlrM$@$@$@$@ .]Tn޼)wܹs˄ o=ٳ'MXHHHH #GH͚5%SL5kV;dժUyz-;vĘ&    X E{Z)SF-[MѡC     j:uDcC:t`HH"݃HHHHH"P"drQ'|B+W, nݺxEn @,-zAyZjRXX)    p'/Jڴiٲevg}ֽE @, m۶I-ʕ+n 9} 䫯r;    @@ZjUٿjJxkhݥQFRpaٰaCl ҠA-8x2d-DHHHH%Ec HxX=|,b#   )@W^->|5J6m*ճ F=z/!A= C]|(P@| @|F#<|ҫW/= g`oz$@$@$@$@$`' -9sho>٤Iy\rvM$@$@$@$@A+@=F.PA`ɚ51ڼysI.%'    /A Pׯ_Bb/J**m\.9y&4Gݗ7"   tɒ%KNrK__ȑ#eԩmb,YH"EaÆ2`ɔ)Sߙ͑ .tӦM#֭[СΝv Pn] Lڵ a>fhڻwL6M`@u^D$@$@$@$8 Ps]&L _;wN5k&O=C vIHHEAgϞ ŋuT9.?+Ӥq>(Yiƍҭ[7zM! ~ܹr}yKx~Ds= $!   &PTn#pW>!C:thw=zT[G}4J(#ܣ.z" !#  %/XPv576kVB>nbKimݸq#)E@A ;YҦM+X._SE!Sltbz'{ /vgDu9aog?~&$@$@KkQf@B=tC-ZsȐ!bO/_>ٱcQVrnZOTSZ @#.^f2}p ֮]+Ç׳ r%-DϜ9# 2d=vXΝ;뜤H UL$MIH ʫWʅ (F9;wE}"3|hiE ˗y>Mt"0tҥKAk RY't̘1O$@$ @@",n’0N 3gq11ar,)KʖUߢyEQ}N+bԩp %9e){5 Q =MnV…S(ʸ ay(F)?9%LFDtd/2"B){cXW^+-nwO?TE U, ,9B$@$4PRGZLjf#eQ ߾=yT@p9u*nQjb='ϭ|pԱqSչ47u% o A:>?ϽM}5.7n`Xݥ|bo/3MR?>~>P?pO ֭[B :_9 97;߭;xܢo-!@hNzV$@$ @iF$ã6m YF~wP0]f;:EXKS-tʺ[}|JRǕh<q@3gk߶k=w mmd1\26CE9>}801cTmC|`6$X>! H~n&֡3_U%k֬*+K eyYJ*eW1izϘN߭ʠ/bC ^| P H˖-z]Ι3zjmi8q>;Z $$!1zcҥ䧟ˊgӓLּ⋂;sDQ JPP]}*ͳnƱYH )@"K,2{l|{\h ցG;vM,^xAJ,cHHn@d:&rqZ: еWz*Gh>5#Et9*ص!t4&XRr/ Uf z(fلʳ3 Sb! - πa8TΝ3mذAק3~k&&Mx  8X87\&[Dƍʇ3REȻЁȮrJAƕvNI6b&@kB ̶義5Ecmat„ z MDի!+}ᚓ'O<9rH$@$@q#ioBlb3ԩTٔe1[Y`Sc]R~};:F\zn'P(N}COeڵk`>\+ӦMөHUx& P`0NN ~ftr@ QՌ?Ke*hرCjԨ ~y#@N:6SC$@NL͚5ݧDNM7ʑ#ȪU%pYZ5kSM"X34k a7.h(GO=_?o'tԨQ&@CF$@ MN|9LfLUifbF_WD:(Q6B #w91R&Fub&H !O zLf Bb $V7. hI)8ۨs?Ө(5IJ<9%:G]-Eg}VG1v]p7r;5Hv3A;vL:t}< o>4i ,$@$@ X7vyt2 RKZ5M2i^|W+j^u:3f.]VZI*8VM#6iմ>>nONbn7JnP/GwDϝ;W@qχA H+iDR' E&N̠ɣ2`yOrߑkw~啿gMݏ!u;Y '{N<|{/h'L1|Q  [ɤE&Mڶ-J%͛_1 -Fd|[FaqTp8>LY.U%,yPl٠>^sȡEҙjlfJ Zu 8(@W#,,YDׯ/N| @J&`f( iΙNM3#1 R.}(Usl"k׮zH=1!*}Y6)6ͧ5 OzUy'ŋ:h׮]P{Am۶TLLGd'm @>ƲiNMڄU+ =*'F}?_VSZSi&55F෉HȹY xs k}d! ` @T>(?E_F8Vn]pz$@HLtBlٳaWeH-HN<q _/__B$@I@ӪiDgbOWkW凙FY/*AG*c.+?SV-0_zOEgE 6s jiִjV#pWw<(-[̙3/JDX6nXjǯaÆy_#$@$`54Ӭj?gIw튐;5cB ۷O '(qUJެW 'i}Bɇ ,Ӧ3gnEc.G,d|5vM,ｷU.]g UCe˖]y)2B$@)@@k=+g[lWСCz77HHFCӞ8Os۶4ڪkW|ieEtkWT×ڵv%ϷIԴt9%SO= to${v)6b. p@@ZV-%X:!x?c =M')q`& r)4B3ZlW3u"Uʢ\Ru)Q"FJ%<%lŸnɓG[5CiӦҫW/u}I_xwBVLMPh& a+Г| /… "JGG@0²f͚*OPѣGt k>dnZ& Iܚ۷GŗgϋnK=wi&&D&'ȄD0Ynw>tI#,=-n $"LRc!֡ZZ@!eΝ!CvZjRXP}x 9*ߞCI b)4s ܃oL/ ml&ѻdΜZhk& 4!.!4i|L#01dB$@$ $osqtD>aa'Vsx4H+=zt!GEai?./io_<.S=,?ɩɩIW%su܈K۾&1eؗc"bĉcF k#ռ㹴px7T"\w&4o?{xLO Ot@bb)*;EaÆZpb:`2b Ĥ~,!   I P$Gd;N*)@_C"e[k$Y 6!4aĄ E) *Y~k}Mۋ]X&.!6YHHH Iº:g>ЄTv=*֝@m֭ʆ >#֞{?ܺyP˚G o8~8!*O>$k+S`hi.ln7_~-Lx3gz،2dH}w͑V`н#O&U?]Zzܟ(7.[= [רq홰3~:%l1||]՜9b(.yM2f.rS<w؈JKs͛W ̢rY@ /_>apG\\ƺ$@$@$M~}Ud: љ`ڀS`8"xȐ![+QL8Q\R%Lqy@$هP5%m > ^BI{vqZ6Ͼo߶e+&D%FhbrabȄK%4ΣXXHHHRDP$lR s^>@?{WGb!'mb*N?C Ϫ)8ѹ_|Qjժ~O=U79xbuBPj0l{;nٯþmcium/g>39sjժ,Eȼ6 *CLt+FHtpaW^-TQm0 ' 'k JNvx̂{m=<}   !PܹSʗ/ŧg0}٧`qaV,)O>9}MJm$OJuB1b ?L %x7aV䉐 ^b]֮]+:BlٲIxɰx'<}    hQ:rqYb|"{( .hӇb'   H_ʕ+!!Xt҂w_Ξ=;$!7R1 ?z}s<¼˗/=zH׮]C / -ZɾS$@$@$@$ ǴŋwDc!2rHIc̝ 9rX%R4 P0? aiҤ~k׮ikh }2DkZ# s̩#Q+"/^tO @pZ@!^uYh|F f 4hԬYSOnh׭[WEkNNOI!޽{eڴiw43޲ =CR~}QFI̙L3fOT cƢ(+M6 &Ȁ|A    !T"zYnٲEqcV$-YOOD ~8q@,Ç595 $6΄ؤ>|cbb8_G`V+:r/%@-<(g?K*%]Hͥ b }lxHHHHaџ={3<# .nݺɰaôu"70|ڵرcҡCmA0|@'~֬Yz>IHHHH IU͛ŋxWR C|mذ̝;W.x% @b8K"D'**TևCj (IQ 81ʟ?GQ    $P~zH{͚5^O9ͫ-uHHHHH@( H姟~3%,H> @(@1t颅(f?BYlӦNN C+'CqyAQ3ydkN} @,˲zjAtIri"    o0L=˗J*y#$@$@$@$@$_ +WO>z:K#G=mѣGu~O>,$@$@$@$@$,AHO?9R(ˑ#GҥK믿JB}|`zx߽Gjq '̻Lx"oK0a)@w!~oj맹lРŋÇS\ǃadɒs۶mC<%$Fﾓ2ex-8nʺuٳgbŊ;cNqM `&-Zȳ>U7w+:^ @%+W.alٲ^u]vo"d6|_,={HyGd~D`o/giM_xy_8B% v٭ M׿%soay~5!W´̻L{N{35"@W^L2YK(amo"t6)ګ5ʕ5kV>s$1cu֭[ʥԭc Pi\:u{i]Ydq!-rq) ի1n'ݥ,NlٲRԭJ0V0uN$pY?..]ڕ>}z/ʀRӥ g^pk}bI>C `vX`z6mjCJYfYǸA!fժUƫsʃ>Ӫ-[޾5u&e|̒2cQS MnNxǖ.]*ӧOnݺܸqT\Y]ǿՔ׫;w$iӦu{˱c܎qB*N8!Ƅj իWw ܵk,XЭY $wHoơ7O-I0V0u|6΃]wݥZn!@w#.\X}k.IOE~v㱞 \p- PC2 |;{9S3F1rbJ]W5wN۞/̻Lsr hlݺueС`W_}U0۷o_ڀO +f9Bz ?pV>^#(&^ xѣDfݵs7H4iӡ|q@| nS'u?*j w 4H&omh>裏>*XXw!-ruH XE=zUK|ə3g݃?7,܉#`ޭ`񶬞 zvŋe¿^xB‷-$::/`$G+{; ė!3 ooX=a6 #̻L8 H煀K̙3]2oLlS&gHd?SXAq$wD#͟?ߊ7g@1cFVk3`ޭ`Ƽ w\*Uˑ7"oLm'y"TR]{uJR~,~r\| lٲŕ.]:ƥ4԰M6:o/r:tȥ\{v)'}׊+\*ĥG ˥&2̻L%;5K+kԨRc\gGՌn(wo"d6ŒS$Z4jȥ,I#:駟\  ~aur{~ ]*ȥ"]yߥpb#K~0V0ub7ϥ.(8pÂ[zJ>0$&L9V&#~P ۷OXՑ ć@0V0uso^ qWy/(@C`OHHHH U`R$@$@$@$:(@C`OHH qkD@IDATHH UM3HHHBh| cC @ ς=!   TA4U||H   Y'$@$@$@$*PI$@$@$@C4t> HHHR T1!IHHH tPg @ @*>f>$  ,   H(@Ṡ$   !@:{B$@$@$@h$@$@$@$:(@C`OHHHH UM3HHHBh| cC @ ς=!   TA4U||H   Y'$@$@$@$*PI$@$@$@C4t> H <2l0ݻٳː!Ci޼ymذA͛L8jWHK M|/u$@$RtM7nl=/, _|:VjUݡCXuɍ={?/ŊǏ֭[h![l^zIbbbn-^L$@q%@WbO$s=Ŕ~[ {֣Gȓ'-[6An5kV%K9uTFHH X "РA/5wyG|M7nTTI//\.裏L2RB]tI[2-*s֭[ˁuҶm[y({E̙3KjdqmIH H @J&~z9z~?6mXHn*ݻan CVREӆ ʮ]C86bQl۶Mcrui׮o/ 2Ŵ:p!\/_>a} H0 F54 hYxqdO?iʕ+~f͚iK(}8aytI֬Y#-se˖!vX<ϊ\T)Y|9h(2 @BMhlH UDRdd%@sNJ^b}ڵ+9A4Ƶ2c >}%FӦM<^*۷o7<<9 H IA$H1 .%""Bsi/8fʾ}ܹsRfMsZ{^gecR`A5j%Wq * HJ BJJ7 @'`$@$A >I=kLVd p[ iҤ 6N3I&鶦Mvm +Ǖ @Ndɒ.]ٳgL2 g! P:E!   8HHHHQHHHH(@ 8JQܼ (    G P:7#   ;@$@$@$@$( PGqf$@$@$@$@|HHHH%@(nތHHHH (@͛ P    py3     P$@$@$@$@u7oF$@$@$@$@wHHHHQHHHH(@ 8JQܼ (    G P:7#   ;@$@$@$@$( PGqf$@$@$@$@|HHHH%@(nތHHHH (@͛ P    py3     P$@$@$@$@u7oF$@$@$@$@wHHHHQHHHH(@ 8JQܼ (    G P:7#   ;@$@$@$@$( PGqf$@$@$@$@|HHHH%@(nތHHHH (@͛ P    py3     P$@$@$@$@u7oF$@$@$@$@wHHHHQHHHH(@ 8JQܼ @"  &puҥ>QlYӧw̙3G 4i"Ϻ={-[s_~*TȪ#۷J䥗^7Ə/͓GJ*U{RdIʸqdӦM־N:IJ|1 p@KGě @2"p5I.qe…~{ ɟ?@ɓG>,nQ;7nR^dĈzs攵0]OT4%::ZlOssh"K|6lP  ٲesɫjUϕ+,Xku.UU$@$8yO G'Yf:u@$ (aaa+WJǎe׮]z?Em)oZJ/_.kזcz5Q\D U>+z p-NHR,VZIL}NSN:eYE!-O-X@"Ez!0QjԨ'7o.˖-3^˅ }|ꩧ 8Mi @$!C%ӧuyP ?RSp ҷnj]k?y>uSwj N}?S>sI6=W#  P:7$H쾝SL cȼ]vq:iGO:ncT{־m۶~s& "@Ty_ G~y?իW5C(M69ssez4nc*ϝ;WfϞwufsM$@INo2[W6l +V ~yrI$@)R/=:/ș3g|呑kJ|̦Ft=JҥXHH T6d:u(@א 4< !%KiѢE?1|gZmطLK.uvj]  xCEQ>4wIH U^8a ?QR7.\X׶r#S+f6%z깝 $5ŋ˥KܷzHʏ󅼀HB".tN{A0~%{`~i۷8qvСٳ{ldwOXH@8,Y"i+W}a$@$2Sq)$4i[={~țR@9p؃9FPbk*N``RXEL>n?~4,$@$JNb֍9sH*U IHkժexbVX6 N׬YcY[!>1&fB8pוhB$@!@  &_ۛ5kg0YHH!DH  wCʕ+L;vԁI˗ Nk׮&!    Cg&sŋ C? Pcǎ5!    _Z@|4;wn_mcHx4"fdyHHHH U(@a4rKSjԨ!{HHHH+@:$=zE |@1^lYٶmh|dǎ9sf7HHHHH 6>o޼)EÇ3nF^u=M'(f4h95 $SΚ5K/_ܹDDD0,2d t颧z xV     ׯy=XAs޽r…X$ >0_RhQSZۂ*TH01|DjpM$@$@$@$7h^#y_b^$@$@$@$@$`[nP@~Aԩ L2z:MDo߾"N:MO?y     =lR^vmZ̙SYz>|X 裏kIH d DGG &ˇgGߎ`>j+Tg U $>-x,Ydق3fW05'gΜ)#fI ܹS/^\,&]Oq3111=#2eOVZeK_NIl! .yѣҶm[CH"ꫯ >,tw}'\pW~R.M7o`kQF?RZ5s9$@ $ҥzK޸qCO|:IH+Tl޼Y?ٳG:uʫ/=`'UT#G P/^,M#F?Λ5kG*W&\zU T!zM&Ǐˑ#GHE=zĉru;6Xwk}k׮.y~$@! &_qիWPL\g} C`ҥzM zfӧO{=b b9D mawɾ}6nX)YrS6m$A y oܸQ|Mv횤MV;tlݺUڴic{44v 438pk] `=g;ذaGS\[tt]/5k/[{}|7nbAÆ ͘1C~ f!HڵK'Ct< D| 1/f6To?gƍ hqFSt5  ZB$߿_&M@$bŋikBW1Cp9'+/^D)P^0!p|bHڳ@hgǏדw ^:5xɓ'k/³هPD_w!*,LJ<# |E^0w\Ӭ6``p R[nK/ xoϠe% $ uQ_1 TD8Yfu)b=+Z|r܎ahX}Ul٢+R/7oVYn۵`(ۯ2d>:J0ZTc}\76hY,. O+zדO>RBOرU v)I}LWi\"8ʐ!޾ʜ9s1įL]J,j׃H4>lٲuӧvG.åKY0UݶQV?(:KYѭ}l 4HKYݎsH i} ć&8w[ (Ӹ&uZ7\WT[ }-Z$sv!F X( xD#X aT>VVNNH8>|=|Ou~-V={Wr_VZʈ8*Q`}RB'pƐ6 @?={Vt6\:v.m;s,34ǰƏe HI cϨt6hn1GfDգG @$@+b{A!c+n!|yQ^ Q9kWX飭=0YlN ؠA-~B$| x{'gaIB_Q"@y& cxԩZX"o&rEڋ}L~)Fk8zF r~"@pACRGzBi &@1e\8景Ӵa_Rn~ξw *%.8[A<׀ :\&Y se?춍` $,x'S?$@ɇ@qWeOI%b\J :ŜW~.%(\j q.%tO8y]J4T$+xI }-Ƶ*}= BR.ettB.e t)ABpj;%&U up=0 }FL^۷Ԕ. PI͜RۥħK [m7 BRօ_mw!E.a*~Nɪ|x6{A>es"( uЊ(WL9\={}HJKeGp)+wH yOE QDʱ>XH uP2- B~X:&bE԰K TЉ>Zm@ ;Dհu^ s*uu, TMB6auO#t&i:HLoGtPER,n J0TFA=_xF|s & P3S3EiAݻu!Ua^}|l'yP 04B$@q%K bLSOaan \ M_GCoLݎ)5M@L)-Og|[oMs==1@,mv5I X P!k?}9@ 1Ҟ>SV  X "N Icr 8B$@$2  Bc%Kh+Ƀ*H 3!@A0 [XHHR.iW͘y0Ԣ|;+gf=N&2w̜93؍X(@!, Pfd""9/9S)@Sg# i@0k5\m0* lcQQQڷ,T3wϞ=G}(ޗyYf:I0~* eRr<`Hme!  H\"端%U3iAaVk3a۰%J*87 * P" U嘓N:iz'snmP؄ߝW&dslHHR5X2}L|ZPBXbz^L)t ,ҰaC-2!81{&ĥ]hv/K8(n'0UڵkOl{F (f!QFL^fkaB.RPWqF9|4iDSS0^8|V1)ӑ $.F 󓲷es~Q5;T5k%T!8Y3^j.2Fh1DgyF`v3#.Myt _E_|!ӧF  $5k0y ":&{ۓ --yO}6"\V#'C,l^?pW'r1 pU5ٍ4b"ʍ PxM! Z;wnj)y GIX"ʉaJ+HtjQ֒9_U0LB$@$@p2?uZH}q]_?(YF~$Za&&[DfҥiӦ'H7k&D' .7od˖-zI(=zSQ—#5a2rGpm.}(I$Wc.M/#.\T^}]VΰV-$G܎T~v#a^n&OɛG"F w?n/{qޟK?{]}P-,1i"$RREgn/7GJ-|3cڴQnHʅ")``& +hRdF@PH< .Թ?V*ԞF9es;u߂oiBLc ͠,9s0c-U8a _ 6d-nm%TIϺʂwH nxw{!a{eW># >x]Ι$Itɒ%cTYk$@pU~}A2$F$@${Slba9אQn^н]\Q9.#g..cG)΋OK!6o U0P[8f仫,bTq:rT=7XdW! [Pv*>K[Eł =48kz3C\Hzd^ 87/{ MB |2Q{:Gy=jToA7mesHMPgӳ!+rcBBDlN iسf&T!`+@%ٺuZ`ֆ~,zA F$@$ap9vƪ0 F옆QøM2 %`AGfM9zaֺ2Yf(˧KW_ʭޑ j:ZfjVREG}3F{? 6L:*w/w@_]O 6u+IH"i4ZZ$!>9U)%jebh WPA/3"Ӯ[IXK3Qe,MY9l.&N9M$`+@Qs2?ÂKb/keĉ<_HH0.sc4"潅! ÊiFpɓGLLX/t](ΎeFdz=3_/ٯ\ʍsDӾ}J*nWϝ+U5|u1;8[sD֫/^UkWv4p s .zS$@DLOi|.(dD&Fdbd.rԩ%:R ̥J)4;?ٳe͚Ujb)_WSa%2UŊUm1]D?8!ϗʻYA)Bo<W_OVsΝ;X?l K=WIGߖk_+r Qv"O(qije &,z" LOXRÊ]Ig'>Apkkb{n(QYHeأUU)7oYIe ʉ3CGE1v|ʨ\|zh޽7nܐot(CsζW7+ @H4VL3X2ыDXc3~A#0J A`C)[ň#R"-i[|*Kfܡrs2[ c۵) Xߥj]'VUp0:xS_x֭u/_V-PL]{ף>]vr9 D#*1Ǎ4cիWu,&D&b2ѩI"3VR*^ӉqT 4! }ei^z%B3H4ܗx4}x Pa6edm֭dCe̙:C4+#CF)j1 >\d_ `fh(cqcLLT"aUbL4"=XC%>mV&>k=Uvq5Y!NH lh-+O>Z၂_~U_ݰaC@C}6og͚%gqa# X'i&"Vqi#:>!.|`,gM™-ӂ4W*T*Ԅ0 c59$` PdݭZJx8m4묰%K|>FOhI1 >TO `@LZb"C"K#4x.q"6S19Ƕm6u6">&q+%C"* ￗ}/6[$bTF^XtC={)>q>K&L6HHVLo518B qÄk9_l$ h(} "Ӻ,O1GUӧw}'pӇ./ oA`B\pcw:~"G%tTEWzr ><+K:U'`׮~=^/3I T]2O0lȂ^Ŭ4V݊PC 5d5"nH!D *ыZZEYէ7U4B`B\BdR`Z GQ.6YG{IIT(ǖ=x^I `Q'@qYBOL:'!bUdɢLvRL'uH 0 צ"%X/ЄwY8̖-[jqifZ62RJpU4 DEV+5T?7J_}v,L8Q@9tyCvcah׿z\N$]ӈL!*qbbI@9 >֩SG LN]AgRȑdW@S^nRFɸݍ\~$UUOT^XEH =_~L4>٠A"sܸq2zh3fBVZPtB4).< 3% $M &D&% npIKI>9 X Q=V*r}YO/i6Bٶ͛2ذ@J xwi;w|4i 7x=j;Vx^ <<2tPwɥH=Օjp4f*I LɠVbqLCEEDG$<w9l$}*7DD$sf * n l_cWڶm[PPYs1$DWШiO "3f Bg#H_L9p}qi\F`BdMՂ ib/,aeGRj8 %uwA*SY 7p*>;T\7Wf*-ֻZuy*@,^Xǎ`m_|E(,hUVm*ڴ+jKg[leKz Sr$ 4Y&* o %\@\zΝ;7ђ@8sn^uRK|"ӥ4˧:ɤU'5+x/3exxÚgwlD?ہB5ΦM l~ 4Ƚ{X?'D$b]Lϟ?N1<y~"nqILK|؄֗u"QzpL"KjO `з_v)FwsuRT}7= I@M>}K vhU$$Iz@9R6dһwo" qpCTZiz ,1bBҸǑ=p#.1D7 D ?ZwNU˧'5kj&  ga*iH 4W\J\;v*U$w.]dڴiIEbCҮ];-=) /Cy6-%+b^^rEIs qiD&%XJHlذ[\b^$='?u.y]}5w&ޡN~DeRڽf('+^Uyf9={FN Pz/ӎ;t/DyUZ Iae>K@z! Z⃗)%p#b!2<ԩ~&2HA6oٲe,OSLYY`ɦp$@#t\ Gk ޝ#;z\Fi˗K҈L:m߾F䌻L UCZ"T&AE}bE|)5l\F{! %Hٳ~']M5kŋIĥ5҈K% 5jpÚ qF$8꽘M>RKZqT(>,q* 20uR⏩xEHEyuvz=$Lbw.'HKt W8>z kqc).D%&)MH!nf<}FueΜ9m_NGI/>pO\0\k] 9@p%`+@,YuIs ]]쎂xIƚKeb; Gu J#.aDRDFLbyz =!pG$NceKSrPxݥ~(oU;ެal(ub^pw֗* bKeL=riZ&7ri%Dg,Y?nA$%_YRnD,+?R\TuaE؜f|->N~8y,pTReHۻ5?Ϟ=_}n9Nr \D%dcDlʇaEk|_bB aHC/Ż GL|›ڏ*&ꥌqpzŶ^ц_@[Ut2i$Ah -=e1 q!BP!1 0"Ҹa'Ɗc=$x$@NlݰAduznkפҼ\_Rb?M4ՕExIN1xd+@2gիbh(?n8=k肏8&n"7VK6QGɱ&M'NXEgK$<;.-Օk">۽ϛIY$`C-ಪ:2ejN΋_f7nM6i', E]Ї<kn-u h,&Ccįrnݺ:!,F$@v-٬tkrCv?HSK|c>fZ>+.I*T)(Ypܑ&X(Wk/Xzy;v1xe %J"}IDAT+;G7VK "_ka i,(8'b;; XdgdWOP[>=Y]%"qRH[bN0G%  -rB/@FQ2>([rN5!.oܸLKX/ {&HJ`ڵIʼnWPm?t`lXlPЭ7HZwƉewUR HuԩRlY]btȑ1c~\1wɎ.J#.1rDF\5+5"qn%f|+ @$|!rܣ<,IyQufs~zYuSqp9儀E!z} 2 R޽oN:u_N^։,xtaiI䁠4VKUH0RB`֯__!4,r:Hyl\_ħqV26HEu?BŸ`0*@Qri/*iӦ:%m6o,~<"5!5~x9sU7=16lXXSZp#ZRm%N! cU8{y LSJݦ,u+T19-}gj[>=+GrgTE@<[kUHLs}N?^յ¸rJ1!oYa"aÆR.]th,oڜf͒ٳgҥKYm~!8y "MTbMKnS҈IXKd# HJYzDG)ONK&5/Zyțt#/SVu.xrZ ,_m9'auG#MJz82mܟ5So&w&UsUVC)=v,K[ԗo>u/\P'đzJm&Hu>xjJǮz i;}1n59f|e+:]G?h!mb-[iYz2 3vʲ篛A 7K$%/7CޔES|Ȝ*Y%C ^ni9ʔI\2-esL/SFǏZ?>S=jZlP.X@wXAXRW\Ϟ=}O_̙*(?a„d\[v=zjjlP!CJZ!BI" *,93֟^5riv .O=jHڰatW"  1F$/DyX7 DGE*ILV?nݺIFcǎ:8p]'"ݻw8Gpӧ \pӇM8Qo|wvhaqׄ Ph đ,iYTNfwިPl$@$@$@$@A@3o{W10!!AOk @ݡC]wҦMx#GX!Gy$@$@$@$@ Pd#CkFUzwرas5    ՟ [ŧя#G,IHHHH/[<Jw鹈$@$@$@$@$mٲQ>}E\.]tщ~Q} 豓k og̘! pr,E!~" Rti܋Νc~pQh _rʡ)(|Y~*[l(kIq$@$@$@$@闀cz~!VQP~o^ m (:qDmC|6hb}ų Se  7ֽ曺5kҷo_z$@$@$@$@$ .>Lx  ^(Զm[oږ-[{FRdf$`K֭[Ү];yǓrNsF;Hv/_d:kG9|&Ö3l-(6ߠAr+WU 4Ѱue۶mOe/ ":x^ճg$9di_~>e̘1;vrKΜ9˔)֍"(S߶k.̹=zӧOw'+C s7سgK.Pw @]zСC]Kk.eapy!O6KY\*/U`AIVqro9Y'N9.\֭~//_ޥj'zft)Rd0ZXR}W< ПNʕ+'+W6m~z1Ҏ3YtBip7@0`Ѭ^ޅz$/w6 ۷o/Ν 6Y@2x[͛7{9spZJ̙#D/4^Co:kmݰaÒ1+W k֬2~x oqt7EӧO;$9{`,^R%}_^ɄflQHW_}U *k8\3jԨco͜975PK~`#=d}@X2&x({z%KZ78 Dɽdʕcy!@-W\zOkdθ)B1ǏK׮]> ٯsiiL6m*(?OE׸qc<@~G<=LCT&3ŋBM9r.wv@[N \?WZ5rdz$#A-[VICݖ)Q2eKt-jwKh۶m]dpF(Yȑ#.R%\ʕೞYʎ­bݻ]\Ƶw^rT2Kexq r_ RAk׺TrK`5\  uro9Y'[oʞ={+CZj̵h"U.RuuH3#J‹JVXR u @_x4G#,.btΝE'    R,@} HHHHHB~"    hȸ @0(@mIHHH&@02n@$@$@$@$  `q[    P C4zܖHHHH `#$@$@$@$@ %   hȸ @0(@mIHHH&@02n@$@$@$@$  `q[    P C4zܖHHHH `#$@$@$@$@ %   hȸ @0(@mIHHH&@02n@$@$@$@$  `q[    P 7{8cΗ/=: *>m۶?>sk֬YHH 2tCnG$@@~or(%JU^]w]*WɑzJ|I)U9s&CkNv-=ܸq#}qc hĸ> @#Pn]ǴW_}U Їzr}]xG ,( !9lkjմ8m޼ hPrG$@Hbtٲen8.]fҥ5Eɷ~W_}%֭mڴ[n-Htzx-իlذAVX!昫W.vX<ϊ\\9Yf h@2 @ P(G$S<29sfK8BK7mf$'@?/sΕ9sE0ѪU+)7C n= @jM <& @!qim3f\ZvQxԩSr=s/3d)ZL0AǒZWn~ħF$@IIHI&zVqbͫ!HF~P)S 4O>3ڨQ#Yx?^r PCC "@Zy\ $XA!6,mݦk~3ILLĐ"}РApX'Nq$ỳ HH (@CI" |G;a䣏>l{12QPg+5h@߯> =zeLq hxr$@$߮]W^-[dkKwߝd@&k \ .t/,{W[?4d5% SF+wH$@y5;mWF__]׺NT7]vVXb# H`|H8$@$A %E=va;iLmW $@$AtG6E$@@2em۶f͚ ]$@$ н'D+[d˖-pz9sKF$@"@)< &@|xu^u/ K4XܞH *@>#Zs{s?OUVyΖ/٭[7A!xoڴ`dۄjÇ]v֧>Q#г/_.5*9r ޗ'IH uB D5CtUy#cƌRn]믵pΜ9RzuٸqubXLm/"O<ڵKr^>Џ=Z`:uΪV?~\Ə˚5(QB*U$&M~:} P& HFQL7n,/DΝ;W~̙3ռ;w-d?Gjj¢h.]1c$fǓ'OXF}B:x``g"d'=Rti"=$%ڷo/C 6HÆ z;v}̣{Olb# ` PKۓ ypֻ[J>}x⺏tX'G {Md=]V4hׅ%qŊA /ߴiNW{u\ro>ݿ.Ĥzk86bM|"\~$v)֭[8Qkĸ @(@%I4?S;&Hlg0"mxb[ t͚5PXQVeH'% :k c]#fϜ9SpH nJ$@ib/oݺ3=I@F|bz(sĢigv'y/v˗/aZn=jmϵk׬5{&  H) Дv$@QA(|ܘH e hCwyfp#{͛lWX1AzK?i޼.ل2Q&l!"{׉֭['o 6L>Y^*2+rHu D'!h/v_i8Q\.y_-W\2oD/>cmE(߯k~Zvf( @rB#H*ZB?Җ>ϓ'OLs`ѣG5d{6S2$6  PP>H<r\l ܹSG u5$ (@s\ tFkժ!˗/]].gϞja2H 5 $$@$&h̙<sGףl$@$J&E$@$@$@$`K^PFIENDB`RCarb/man/model_DoseRate.Rd0000644000176200001440000001176413475061747015222 0ustar liggesusers% Generated by roxygen2: do not edit by hand % Please edit documentation in R/model_DoseRate.R \name{model_DoseRate} \alias{model_DoseRate} \title{Model dose rate evolution in carbonate-rich samples} \usage{ model_DoseRate(data, DR_conv_factors = NULL, length_step = 1L, max_time = 500L, n.MC = 100, method_control = list(), txtProgressBar = TRUE, verbose = TRUE, plot = TRUE, ...) } \arguments{ \item{data}{\link{data.frame} (\strong{required}): input data following the structure given in the example data set \code{data(Example_Data)}. The input \link{data.frame} should have at least one row (i.e. values for one sample). For multiple rows the function is automatically re-called.} \item{DR_conv_factors}{\link{character} (\emph{optional}): applied dose rate conversion factors, allowed input values are \code{"Carb2007"}, \code{"Adamiec_Aitken_1998"}, \code{"Guerin_et_al_2011"}, \code{"Liritzis_et_al_2013"}. \code{NULL} triggers the default, which is \code{"Carb2007"}} \item{length_step}{\link{numeric} (with default): step length used for the calculation} \item{max_time}{\link{numeric} (with default): maximum temporal search range} \item{n.MC}{\link{numeric} (with default): number of Monte Carlo runs used for the error calculation} \item{method_control}{(\emph{optional}): additional arguments that can be provided to the control the the modelling. See details for further information.} \item{txtProgressBar}{\link{logical} (with default): enables/disables the \code{txtProgressBar} for the MC runs} \item{verbose}{\link{logical} (with default): enables/disables verbose mode} \item{plot}{\link{logical} (with default): enables/disables plot output} \item{...}{further arguments passed to the underyling plot functions, see also details for further information. Supported standard arguments are \code{mfrow}, \code{xlim}, \code{xlab}.} } \value{ The function returns numerical and graphical output -----------------------------------\cr \code{[ NUMERICAL OUTPUT ]}\cr -----------------------------------\cr \itemize{ \item A \link{data.frame} which is the combination of the input and values calculated by this function. } -----------------------------------\cr \code{[ GRAPHICAL OUTPUT ]}\cr -----------------------------------\cr \strong{Upper plot:} Dose rate evolution over time backwards. The solid black line is the calculation output, the grey shaded area indicates the 2-sigma error margins. The dashed blue line is an indicator of the quality of the error estimations based on Monte Carlo (MC) runs.The closer it follows the black line, the more reliable are the given error margins. \cr \strong{Lower plot:} Totally absorbed dose over time. The plot is an representation of the 'new' age based on the carbonat modelling. } \description{ This function models the dose rate evolution in carbonate enrich environments. For the calculation internal functions are called. } \details{ This function is the starting point for the dose rate modelling for carbonat enrich environments. It provides basically the same functionality as the original version of 'Carb', i.e. you should be also aware of the limitations of this modelling approach. In particular: The model assumes a linear carbonate mass increase due to post-depositional processes. Please read the references cited blow.\cr \strong{Uncertainty estimation} For estimating the uncertainties, Monte-Carloe (MC) simulation runs are used. For very small values (close to 0) this can, however, lead to edge effects (similar in 'Carb') since values below 0 are set to 0. } \section{Function version}{ 0.2.0 } \examples{ ##load example data data("Example_Data", envir = environment()) ##run the function for one sample from ##the dataset model_DoseRate( data = Example_Data[14,], n.MC = 2, txtProgressBar = FALSE ) } \section{How to cite}{ Kreutzer, S., 2019. model_DoseRate(): Model dose rate evolution in carbonate-rich samples. Function version 0.2.0. In: Kreutzer, S., Nathan, R.P., Mauz, B., 2019. RCarb: Dose Rate Modelling of Carbonate-Rich Samples R package version 0.1.3. https://r-lum.github.io/RCarb/ } \references{ Mauz, B., Hoffmann, D., 2014. What to do when carbonate replaced water: Carb, the model for estimating the dose rate of carbonate-rich samples. Ancient TL 32, 24-32. \url{http://ancienttl.org/ATL_32-2_2014/ATL_32-2_Mauz_p24-32.pdf} Nathan, R.P., Mauz, B., 2008. On the dose-rate estimate of carbonate-rich sediments for trapped charge dating. Radiation Measurements 43, 14-25. \doi{10.1016/j.radmeas.2007.12.012} \cr \strong{Further reading} Nathan, R.P., 2010. Numerical modelling of environmental dose rate and its application to trapped-charge dating. DPhil thesis, St Hugh's College, Oxford. \url{https://ora.ox.ac.uk/objects/ora:6421} Zimmerman, D.W., 1971. Thermoluminescent dating using fine grains from pottery. Archaeometry 13, 29–52.\doi{10.1111/j.1475-4754.1971.tb00028.x} } \author{ Sebastian Kreutzer, IRAMAT-CRP2A, UMR 5060, Université Bordeaux Montagine (France); based on 'MATLAB' code given in file Carb_2007a.m of \emph{Carb} } \keyword{dplot} \keyword{manip} RCarb/man/Example_Data.Rd0000644000176200001440000000254413475061747014654 0ustar liggesusers% Generated by roxygen2: do not edit by hand % Please edit documentation in R/RCarb-package.R \docType{data} \name{Example_Data} \alias{Example_Data} \title{Example data} \format{\code{Example_Data}: \link{data.frame} (28 x 29) Each column has two attributes: \itemize{ \item \code{UNIT}: the unit, so far applicable, e.g. "ppm" \item \code{DESCRIPTION}: the column description }} \description{ Example data as shipped with \emph{Carb} by Mauz & Hoffmann (2014). In contrast to the original data, \code{NA} values have been replaced by 0 and columns and rows have been transposed. Samples are now organised in rows and parameters in columns. The data can be used to test 'RCarb' and play with the secondary carbonatisation process. Sample HD107 was remnamed to LV107 for the sake of consistency with Fig. 4 in Mauz & Hoffmann (2014). } \section{Version}{ 0.1.0 } \examples{ ## show first elements of the example data data(Example_Data, envir = environment()) head(Example_Data) ##show only column U230 Example_Data$U238 } \references{ Mauz, B., Hoffmann, D., 2014. What to do when carbonate replaced water: Carb, the model for estimating the dose rate of carbonate-rich samples. Ancient TL 32, 24-32. } \author{ Mauz & Hoffmann (2014), with minor modifcations by Sebastian Kreutzer, IRAMAT-CRP2A, UMR 5060, CNRS-Université Bordeaux Montaigne (France) } \keyword{datasets} RCarb/man/RCarb-package.Rd0000644000176200001440000000265713475061747014717 0ustar liggesusers% Generated by roxygen2: do not edit by hand % Please edit documentation in R/RCarb-package.R \docType{package} \name{RCarb-package} \alias{RCarb-package} \alias{RCarb} \title{RCarb - Dose Rate Modelling of Carbonate-Rich Samples} \description{ The package provides a dose rate modelling for carbonate-rich samples in the context of trapped charged dating (e.g., luminescence dating) applications. \if{html}{ \figure{Logo_RCarb.svg}{options: width="50px" alt="https://github.com/R-Lum/RCarb"}\cr } } \details{ \strong{Funding} Between 2018-2019, the work of Sebastian Kreutzer as maintainer of the package was supported by LabEx LaScArBxSK (ANR - n. ANR-10-LABX-52). } \references{ This package bases on a 'MATLAB' programme with name 'Carb', details can be found the following references:\cr Mauz, B., Hoffmann, D., 2014. What to do when carbonate replaced water: Carb, the model for estimating the dose rate of carbonate-rich samples. Ancient TL 32, 24-32. \url{http://ancienttl.org/ATL_32-2_2014/ATL_32-2_Mauz_p24-32.pdf} Nathan, R.P., Mauz, B., 2008. On the dose-rate estimate of carbonate-rich sediments for trapped charge dating. Radiation Measurements 43, 14-25. \doi{10.1016/j.radmeas.2007.12.012} \strong{Further reading} Nathan, R.P., 2010. Numerical modelling of environmental dose rate and its application to trapped-charge dating. DPhil thesis, St Hugh's College, Oxford. \url{https://ora.ox.ac.uk/objects/ora:6421} } \keyword{package} RCarb/man/Reference_Data.Rd0000644000176200001440000001426113475061747015156 0ustar liggesusers% Generated by roxygen2: do not edit by hand % Please edit documentation in R/RCarb-package.R \docType{data} \name{Reference_Data} \alias{Reference_Data} \title{Reference data} \format{\code{Reference_Data}: \link{list} \cr \tabular{llll}{ \strong{NAME} \tab \strong{TYPE} \tab \strong{DIM} \tab \strong{DESCRIPTION}\cr DATAek \tab \code{matrix} \tab 4 x 4 \tab correction factors for electrons for water and carbonate to sediment mass ratio for K\cr DATAet \tab \code{matrix} \tab 4 x 4 \tab correction factors for electrons for water and carbonate to sediment mass ratio for Th \cr DATAet230 \tab \code{matrix} \tab 4 x 4 \tab correction factors for electrons for water and carbonate to sediment mass ratio for Th-230\cr DATAeu \tab \code{matrix} \tab 4 x 4 \tab correction factors for electrons for water and carbonate to sediment mass ratio for U\cr DATAeu234 \tab \code{matrix} \tab 4 x 4 \tab correction factors for electrons for water and carbonate to sediment mass ratio for U-234\cr DATAeu238 \tab \code{matrix} \tab 4 x 4 \tab correction factors for electrons for water and carbonate to sediment mass ratio for U-238\cr DATApk \tab \code{matrix} \tab 4 x 4 \tab correction factors for photons for water and carbonate to sediment mass ratio for K\cr DATApt \tab \code{matrix} \tab 4 x 4 \tab correction factors for photons for water and carbonate to sediment mass ratio for T\cr DATApt230 \tab \code{matrix} \tab 4 x 4 \tab correction factors for photons for water and carbonate to sediment mass ratio for Th-230\cr DATApu \tab \code{matrix} \tab 4 x 4 \tab correction factors for photons for water and carbonate to sediment mass ratio for U\cr DATApu234 \tab \code{matrix} \tab 4 x 4 \tab correction factors for photons for water and carbonate to sediment mass ratio for U-234\cr DATApu238 \tab \code{matrix} \tab 4 x 4 \tab correction factors for photons for water and carbonate to sediment mass ratio for U-238\cr mejdahl \tab \code{data.frame} \tab 36 x 4 \tab beta-dose attenuation values for quartz grains according to Mejdahl (1979) \cr DR_conv_factors \tab \code{data.frame} \tab 4 x 13 \tab beta and gamma dose rate conversion factors used internally (see details) }} \description{ Reference data and correction factors for beta and gamma radiation used for internal calculations. These values are used instead of the correction factors given in Aitken (1985) for the carbonate model. } \details{ The reference values are used internally to account for: (1) grain size depend beta-attenuation factors (Mejdahl, 1979) and (2) to correct nuclide dependent beta and gamma radiation for water/carbonate proportions. The latter values are given as matrix and precise values are interpolated during the modelling process. Additionally 'RCarb' provides and own set of dose rate conversion factors to convert concentrations of U, Th, and K to dose rate values. Historically \emph{Carb} (and thus 'RCarb') as its own dose rate conversion factors, which differ slightly from other published values. To provide a consistent calculation approach by default the 'old' \emph{Carb} values are used, but the user can further switch (see \link{model_DoseRate}) to values provided by Adamiec & Aitken (1998), Guérin et al. (2011) or Liritzis et al (2013). Different values quoted for U-238 and U-234 accounts for different activity ratios. For further details on the origin of these data we refer to Nathan & Mauz (2008) and Nathan (2010).\cr \strong{Nuclear data origin according to Nathan & Mauz (2008)} The gamma primary energy spectra of uranium, thorium and potassium are drawn from Evaluated Nuclear Structure Data File (ENSDF) database at \url{http://www.nndc.bnl.gov} (2002-01-16) and the beta primary energy spectra was derived from ENSDF end-point energies using a Fermi beta decay model (Evans, 1955) modified by Behrens & Szybisz (1976). For the simulations of the collisional mass stopping powers for quartz the software ESTAR (Berger et al., 2000) was used. The mass energy-absorption coefficients for quartz were tabulated by Hubbell & Seltzer (2004). \emph{For further details and references please read Nathan & Mauz (2008)} } \section{Version}{ 0.2.0 } \examples{ data(Reference_Data, envir = environment()) str(Reference_Data) Reference_Data$DATAek } \references{ Adamiec, G., Aitken, M.J., 1998. Dose-rate conversion factors: update. Ancient TL 16, 37–50. \url{http://ancienttl.org/ATL_16-2_1998/ATL_16-2_Adamiec_p37-50.pdf} Guérin, G., Mercier, N., Adamiec, G., 2011. Dose-rate conversion factors: update. Ancient TL 29, 5–9. \url{http://ancienttl.org/ATL_29-1_2011/ATL_29-1_Guerin_p5-8.pdf} Liritzis, I., Stamoulis, K., Papachristodoulou, C., Ioannides, K., 2013. A Re-Evaluation of Radiation Dose-Rate Conversion Factors. Mediterranean Arhaeology and Archaeometry 12, 1–15. \url{http://maajournal.com/Issues/2012/pdf/FullTextLiritzis.pdf} Mejdahl, V., 1979. Thermoluminescence dating: beta-dose attenuation in quartz grains. Archaeometry 21, 61-72. \url{http://ancienttl.org/ATL_32-2_2014/ATL_32-2_Mauz_p24-32.pdf} Nathan, R.P., Mauz, B., 2008. On the dose-rate estimate of carbonate-rich sediments for trapped charge dating. Radiation Measurements 43, 14-25. \doi{10.1016/j.radmeas.2007.12.012} Nathan, R.P., 2010. Numerical modelling of environmental dose rate and its application to trapped-charge dating. DPhil thesis, St Hugh's College, Oxford. \url{https://ora.ox.ac.uk/objects/ora:6421}\cr \strong{Further reading} Aitken, M.J., 1985. Thermoluminescence dating. Academic Press. Berger, M.J., Coursey, J.S., Zucker, M.A., 2000. ESTAR, PSTAR, and ASTAR: Computer Programs for Calculating Stopping-Power and Range Tables for Electrons, Protons, and Helium Ions (version 1.2.2). http://physics.nist.gov/Star (2005-08-09). National Institute of Standards and Technology, Gaithersburg, MD. Behrens, H., Szybisz, L., 1976. Shapes of beta spectra. Physics Data 6-1, Zentralstelle fuer Atomkernenergie-Dokumentation (ZAED), Germany. Evans, R.D., 1955. The Atomic Nucleus. McGraw-Hill, NY. Hubbell, J.H., Seltzer, S.M., 2004. Tables of X-Ray Mass Attenuation Coefficients and Mass Energy-Absorption Coefficients (version 1.4). http://physics.nist.gov/xaamdi (2005-08-09). National Institute of Standards and Technology, Gaithersburg, MD. } \keyword{datasets} RCarb/man/write_InputTemplate.Rd0000644000176200001440000000263013475061747016331 0ustar liggesusers% Generated by roxygen2: do not edit by hand % Please edit documentation in R/write_InputTemplate.R \name{write_InputTemplate} \alias{write_InputTemplate} \title{Write table input template} \usage{ write_InputTemplate(file = NULL, ...) } \arguments{ \item{file}{\link{character} (optional): output path, if \code{NULL} nothing is written, but a template \link{data.frame} is returned.} \item{...}{additional arguments that can be passed to function \link{write.table} if \code{file != NULL}. Supported arguments are: \code{sep}, \code{dec, }fileEncoding`} } \description{ This function creates a template table that can be used as input for the function \link{model_DoseRate} } \section{Function version}{ 0.1.0 } \examples{ ##create template without file creation write_InputTemplate() \dontrun{ ##Example with file output ## set temporary filename ## (replace by own path if needed) temp_file <- tempfile(pattern = "template", fileext = ".csv") write_InputTemplate(file = temp_file) } } \seealso{ \link{Example_Data}, \link{write.table} } \author{ Sebastian Kreutzer, IRAMAT-CRP2A, UMR 5060, CNRS - Université Bordeaux Montaigne (France) } \section{How to cite}{ Kreutzer, S., 2019. write_InputTemplate(): Write table input template. Function version 0.1.0. In: Kreutzer, S., Nathan, R.P., Mauz, B., 2019. RCarb: Dose Rate Modelling of Carbonate-Rich Samples R package version 0.1.3. https://r-lum.github.io/RCarb/ }