, Sebastian Kreutzer
[aut] | Title: | Probabilistic Numerical Modelling of Sediment Properties |
|---|---|
| Description: | A flexible framework for definition and application of time/depth- based rules for sets of parameters for single grains that can be used to create artificial sediment profiles. Such profiles can be used for virtual sample preparation and synthetic, for instance, luminescence measurements. |
| Authors: | Michael Dietze [aut, cre]
, Sebastian Kreutzer
[aut] |
| Maintainer: | Michael Dietze <[email protected]> |
| License: | GPL-3 |
| Version: | 0.2.1 |
| Built: | 2025-03-09 04:11:30 UTC |
| Source: | https://github.com/coffeemuggler/sandbox |
Flexible framework for definition and application of time/depth-based rules for sets of parameters for single grains that can be used to create synthetic samples, used for synthetic preparation and synthetic measurements.
Michael Dietze (GFZ Potsdam, Germany), Sebastian Kreutzer (Geography & Earth Sciences, Aberystwyth University, United Kingdom)
Useful links:
Report bugs at https://github.com/coffeemuggler/sandbox/issues
The function adds a further population element to all rules or a rule book.
add_Population(book, populations = 1)add_Population(book, populations = 1)
book |
character value, name of the rule book to be modified. |
populations |
numeric value, number of additional populations to create. |
A list object with all rules for a model run.
Michael Dietze, GFZ Potsdam (Germany)
## create simple true age-depth-relationship book_1 <- get_RuleBook() book_2 <- add_Population( book = book_1, populations = 1)## create simple true age-depth-relationship book_1 <- get_RuleBook() book_2 <- add_Population( book = book_1, populations = 1)
The function adds a new rule to an existing rule book. The specified rule will be appended to the rule book.
add_Rule(book, name, group, type, populations = 1)add_Rule(book, name, group, type, populations = 1)
book |
character value, name of the rule book to be modified. |
name |
character value, name of the rule to be added. |
group |
character value, group to which the rule belongs. One
out of |
type |
character value, generic type of the rule. One out of
|
populations |
numeric value, number of populations to create. The number of populations to add should match the existing number of populations. |
A list object with all rules for a model run.
Michael Dietze, GFZ Potsdam (Germany), Sebastian Kreutzer, Geography & Earth Sciences, Aberystwyth University (United Kingdom)
## create simple true age-depth-relationship book_1 <- get_RuleBook() book_2 <- add_Rule( book = book_1, name = "extrarule", group = "general", type = "normal", populations = 1)## create simple true age-depth-relationship book_1 <- get_RuleBook() book_2 <- add_Rule( book = book_1, name = "extrarule", group = "general", type = "normal", populations = 1)
The function converts values from the phi-scale (Krumbein 1934, 1938) to the micrometer-scale and vice versa.
convert_units(phi, mu)convert_units(phi, mu)
phi |
numeric vector, grain-size class values in phi to be converted |
mu |
numeric vector, grain-size class values in micrometres to be converted |
with the diameter in µm and the reference diameter.
Herer 1000 µm.
numeric vector, converted grain-size class values
Michael Dietze, GFZ Potsdam (Germany)
Krumbein, W.C., 1938. Size frequency distributions of sediments and the normal phi curve. Journal of Sedimentary Research 8, 84–90. doi:10.1306/D4269008-2B26-11D7-8648000102C1865D
Krumbein, W.C., 1934. Size frequency distributions of sediments. Journal of Sedimentary Research 4, 65–77. doi:10.1306/D4268EB9-2B26-11D7-8648000102C1865D
## load example data set ## generate phi-values phi <- -2:5 ## convert and show phi to mu mu <- convert_units(phi = phi) mu ## convert and show mu to phi convert_units(mu = mu)## load example data set ## generate phi-values phi <- -2:5 ## convert and show phi to mu mu <- convert_units(phi = phi) mu ## convert and show mu to phi convert_units(mu = mu)
The function returns a pre-built model rule book, i.e., a combination of model parameters and rules.
get_RuleBook(book = "empty", osl = NULL)get_RuleBook(book = "empty", osl = NULL)
book |
character value, name of the rule book to be generated.
One out of |
osl |
character value, optional keyword for an OSL (optical stimulated luminescence) model of choice. Must be one of the available models from the R package RLumModel::RLumModel-package. See details for full list of available models. |
It is possible to generate OSL-tailored rule books. For this, the
argument osl must be provided with a keyword defining one of the
OSL models from the R package 'RLumModel': "Bailey2001",
"Bailey2004", "Pagonis2008", "Pagonis2007",
"Bailey2002" and "Friedrich2017". The model parameters will
be appended to the rule book entries and defined by mean and standard
deviation.
A list object with all rules for a model run.
Michael Dietze, GFZ Potsdam (Germany), Sebastian Kreutzer, Geography & Earth Sciences, Aberystwyth University (United Kingdom)
## create simple true age-depth-relationship book_flat <- get_RuleBook(book = "empty")## create simple true age-depth-relationship book_flat <- get_RuleBook(book = "empty")
The function generates many virtual sediment grains based on the specified sample geometry and depth, using the information from a rule book.
make_Sample( book, depth, geometry = "cuboid", radius, height, width, length, slice = TRUE, force = FALSE, n_cores = max(1, parallel::detectCores() - 2) )make_Sample( book, depth, geometry = "cuboid", radius, height, width, length, slice = TRUE, force = FALSE, n_cores = max(1, parallel::detectCores() - 2) )
book |
list object, initially produced by get_RuleBook |
depth |
numeric scalar, depth of the sample centre (m). |
geometry |
character scalar, keyword defining the geometry of
the sample. One out of |
radius |
numeric scalar, radius of the cylinder (m). |
height |
numeric scalar, height of the cuboid (m). |
width |
numeric scalar, width of the cuboid (m). |
length |
numeric scalar, length of the cuboid or cylinder (m). |
slice |
logical scalar, option to sample in repeated slices of 10^6 grains until the required sample size is reached. Useful to avoid memory issues for large numbers of grains per sample volume. |
force |
logical scalar, option to override the default maximum number of 10^7 grains per sample, set to avoid memory problems of the computer. |
n_cores |
integer (optional) set the number of cores used for the parallel processing |
A list object.
Michael Dietze, GFZ Potsdam (Germany)
set.seed(12234) sample_01 <- make_Sample( book = get_RuleBook(), depth = 1, geometry = "cuboid", n_cores = 1, height = 0.001, width = 0.001, length = 0.001)set.seed(12234) sample_01 <- make_Sample( book = get_RuleBook(), depth = 1, geometry = "cuboid", n_cores = 1, height = 0.001, width = 0.001, length = 0.001)
The function models the time-dependent photon counts of an aliquot
according to the specified CW SAR OSL (continuous wave, single aliquot
regenerative dose protocol for optically stimulated luminescence) sequence
and parameters. The modelling is done for each component and photon count
curves are summed to return an Luminescence::RLum.Analysis object as equivalent of
importing a real measurement data set to the R-package Luminescence-package.
The function uses the package RLumModel::RLumModel-package to perform the simulation of the photon count curves.
measure_SAR_OSL(aliquot, sequence, dose_rate = 0.1)measure_SAR_OSL(aliquot, sequence, dose_rate = 0.1)
aliquot |
data.frame or a list of it, a set of grains that are assigned to an aliquot (sample subset used for measurement), i.e., the result of prepare_Aliquot. |
sequence |
list, definition of the SAR protocol. |
dose_rate |
numeric value, Dose rate of the luminescence reader, in Gy/s. |
Luminescence::RLum.Analysis object. Equivalent of the import result for
a real world measurement file. This object can be evaluated by functions
of the package Luminescence-package.
Michael Dietze, GFZ Potsdam (Germany), Sebastian Kreutzer, Geography & Earth Sciences, Aberystwyth University (United Kingdom)
## Not run: ## load example data set data(sample_osl_aliquots, envir = environment()) sequence <- list( RegDose = c(0, 1, 2, 5, 10, 0, 1), TestDose = 2, PH = 220, CH = 200, OSL_temp = 125, OSL_duration = 70) ## reduce number of ## grains to two sample_osl_aliquots$aliquot_1 <- sample_osl_aliquots$aliquot_1[1:2,] ## or measure all aliquots in a row sar_all <- measure_SAR_OSL( aliquot = sample_osl_aliquots, sequence = sequence, dose_rate = 0.1) ## End(Not run)## Not run: ## load example data set data(sample_osl_aliquots, envir = environment()) sequence <- list( RegDose = c(0, 1, 2, 5, 10, 0, 1), TestDose = 2, PH = 220, CH = 200, OSL_temp = 125, OSL_duration = 70) ## reduce number of ## grains to two sample_osl_aliquots$aliquot_1 <- sample_osl_aliquots$aliquot_1[1:2,] ## or measure all aliquots in a row sar_all <- measure_SAR_OSL( aliquot = sample_osl_aliquots, sequence = sequence, dose_rate = 0.1) ## End(Not run)
The function consecutively fills aliquots (i.e., subsamples distributed on round carrier discs) with grains from an input sample. Remaining grains that are not enough to fill a further aliquot are discarded.
prepare_Aliquot(sample, diameter, density = 0.65)prepare_Aliquot(sample, diameter, density = 0.65)
sample |
data.frame, sample object to be distributed to aliquots. |
diameter |
numeric value, diameter of the aliquot sample carriers in mm. |
density |
numeric value, packing density of the grains on
the sample carrier. Default is |
list of data.frame objects with grains organised as aliquots, i.e. list elements.
Michael Dietze, GFZ Potsdam (Germany), Sebastian Kreutzer, Geography & Earth Sciences, Aberystwyth University (United Kingdom)
## load example data set data(sample, envir = environment()) A <- prepare_Aliquot( sample = sample, diameter = 0.1) B <- prepare_Aliquot( sample = sample, diameter = 1, density = 0.6)## load example data set data(sample, envir = environment()) A <- prepare_Aliquot( sample = sample, diameter = 0.1) B <- prepare_Aliquot( sample = sample, diameter = 1, density = 0.6)
The function removes grains that are not within the provided sieve interval.
prepare_Sieving(sample, interval)prepare_Sieving(sample, interval)
sample |
data.frame sample object to be sieved. |
interval |
numeric vector, sieve interval, in phi units. |
data.frame with grains that are within the sieve interval.
Michael Dietze, GFZ Potsdam (Germany)
## load example data set data(sample, envir = environment()) ## sieve sample (in phi units) sample_sieved <- prepare_Sieving( sample = sample, interval = c(5, 6)) ## plot results plot(density( x = sample$grainsize, from = -1, to = 11)) lines(density( x = sample_sieved$grainsize, from = -1, to = 11), col = 2)## load example data set data(sample, envir = environment()) ## sieve sample (in phi units) sample_sieved <- prepare_Sieving( sample = sample, interval = c(5, 6)) ## plot results plot(density( x = sample$grainsize, from = -1, to = 11)) lines(density( x = sample_sieved$grainsize, from = -1, to = 11), col = 2)
The function splits the master sample in a set of subsamples. The
step can be done by creating equally large subsamples in terms of
contained grains (parameter number), by volume (parameter
volume) or by weight (parameter weight).
prepare_Subsample(sample, number, volume, weight)prepare_Subsample(sample, number, volume, weight)
sample |
data.frame, sample object to be distributed to aliquots. |
number |
numeric value, number of evenly large subsamples to be created |
volume |
numeric value, volume of subsamples. Remainder of the master sample that is too small for the last subsample is removed. Volume must be given in m^3 and takes packing density of the sample into account. |
weight |
numeric value, weight of the subsamples. Remainder of the master sample that is too small for the last subsample is removed. Weight is calculated based on density of each grain. Weight must be given in kg. |
list object with grains organised as aliquots, i.e. list elements.
Michael Dietze, GFZ Postdam (Germany)
## load example data set data(sample, envir = environment()) ## create 10 subsamples prepare_Subsample(sample, 10)## load example data set data(sample, envir = environment()) ## create 10 subsamples prepare_Subsample(sample, 10)
Example data set of a virtual loess-like sample.
The format is: 'data.frame': 1000 obs. of 12 variables: $ ID : int 33107 33108 33109 33110 33111 33112 ... $ depth : num 5 5 5 5 5 ... $ population : num 3 1 3 2 1 3 1 3 3 3 ... $ age : num 25711 25710 25712 25709 25710 ... $ dose_rate : num 7.163 -1.083 -0.929 3.541 5.732 ... $ water_content : num 13.29 10.99 3.65 8.98 3.29 ... $ population : num 0.3 0.586 0.3 0.114 0.586 ... $ grainsize : num 4.01 6.22 5.16 5.47 5.57 ... $ density : num 1.92 1.91 1.9 1.88 1.9 ... $ packing : num 0.708 0.702 0.698 0.702 0.688 ... $ photon_equivalent: num 1.017 0.993 1.005 1 0.995 ... $ predose : num 2020 3106 1983 191 2387 ...
The sample was created using the rule book book_1, a depth of 5 m and a cuboid sample geometry with 2 mm edge length.
## load example data set data(sample, envir = environment()) ## plot grain-size distribution plot(density(sample$grainsize))## load example data set data(sample, envir = environment()) ## plot grain-size distribution plot(density(sample$grainsize))
Example data of virtually prepared aliquots ready to be measured
The format is: 'data.frame': 2 obs. of 65 variables: ..$ grains : num [1:2] 1 2 ..$ d_sample : num [1:2] 2 2 ..$ population : num [1:2] 1 1 ..$ age : num [1:2] 1574 1578 ..$ population : num [1:2] 2 2 ..$ grainsize : num [1:2] 2.52 2.48 ..$ packing : num [1:2] 1.32 4.82 ..$ density : num [1:2] 3.24 2.13 ..$ osl_doserate: num [1:2] 0.00875 0.0046 ..$ osl_N1 : num [1:2] 1.5e+07 1.5e+07 ..$ osl_N2 : num [1:2] 1e+07 1e+07 ..$ osl_N3 : num [1:2] 1e+09 1e+09 ..$ osl_N4 : num [1:2] 2.5e+08 2.5e+08 ..$ osl_N5 : num [1:2] 5e+10 5e+10 ..$ osl_N6 : num [1:2] 3e+08 3e+08 ..$ osl_N7 : num [1:2] 1e+10 1e+10 ..$ osl_N8 : num [1:2] 5e+09 5e+09 ..$ osl_N9 : num [1:2] 1e+11 1e+11 ..$ osl_E1 : num [1:2] 0.97 0.97 ..$ osl_E2 : num [1:2] 1.55 1.55 ..$ osl_E3 : num [1:2] 1.7 1.7 ..$ osl_E4 : num [1:2] 1.72 1.72 ..$ osl_E5 : num [1:2] 2 2 ..$ osl_E6 : num [1:2] 1.43 1.43 ..$ osl_E7 : num [1:2] 1.75 1.75 ..$ osl_E8 : num [1:2] 5 5 ..$ osl_E9 : num [1:2] 5 5 ..$ osl_s1 : num [1:2] 5e+12 5e+12 ..$ osl_s2 : num [1:2] 5e+14 5e+14 ..$ osl_s3 : num [1:2] 5e+13 5e+13 ..$ osl_s4 : num [1:2] 5e+14 5e+14 ..$ osl_s5 : num [1:2] 1e+10 1e+10 ..$ osl_s6 : num [1:2] 5e+13 5e+13 ..$ osl_s7 : num [1:2] 5e+14 5e+14 ..$ osl_s8 : num [1:2] 1e+13 1e+13 ..$ osl_s9 : num [1:2] 1e+13 1e+13 ..$ osl_A1 : num [1:2] 1e-08 1e-08 ..$ osl_A2 : num [1:2] 1e-08 1e-08 ..$ osl_A3 : num [1:2] 1e-09 1e-09 ..$ osl_A4 : num [1:2] 5e-10 5e-10 ..$ osl_A5 : num [1:2] 1e-10 1e-10 ..$ osl_A6 : num [1:2] 5e-07 5e-07 ..$ osl_A7 : num [1:2] 1e-09 1e-09 ..$ osl_A8 : num [1:2] 1e-10 1e-10 ..$ osl_A9 : num [1:2] 1e-09 1e-09 ..$ osl_B1 : num [1:2] 0 0 ..$ osl_B2 : num [1:2] 0 0 ..$ osl_B3 : num [1:2] 0 0 ..$ osl_B4 : num [1:2] 0 0 ..$ osl_B5 : num [1:2] 0 0 ..$ osl_B6 : num [1:2] 5e-09 5e-09 ..$ osl_B7 : num [1:2] 5e-10 5e-10 ..$ osl_B8 : num [1:2] 1e-10 1e-10 ..$ osl_B9 : num [1:2] 1e-10 1e-10 ..$ osl_Th1 : num [1:2] 0.75 0.75 ..$ osl_Th2 : num [1:2] 0 0 ..$ osl_Th3 : num [1:2] 6 6 ..$ osl_Th4 : num [1:2] 4.5 4.5 ..$ osl_Th5 : num [1:2] 0 0 ..$ osl_E_th1 : num [1:2] 0.1 0.1 ..$ osl_E_th2 : num [1:2] 0 0 ..$ osl_E_th3 : num [1:2] 0.1 0.1 ..$ osl_E_th4 : num [1:2] 0.13 0.13 ..$ osl_E_th5 : num [1:2] 0 0 ..$ osl_R : num [1:2] 5e+07 5e+07
## load example data set data(sample_osl_aliquots, envir = environment()) ## plot grain-size distribution plot(density(sample_osl_aliquots[[1]]$age))## load example data set data(sample_osl_aliquots, envir = environment()) ## plot grain-size distribution plot(density(sample_osl_aliquots[[1]]$age))
The function defines one model parameter used to generate a set of virtual grains. A parameter is defined in a probabilistic way, as parametric distribution function. Each parameter of the distribution function can be changed through time using set_Rule.
set_Parameter(book, parameter, type)set_Parameter(book, parameter, type)
book |
list object, rule book to be edited. |
parameter |
character scalar, keyword defining the parameter to be defined. Some parameters can be described by more than one function, see details. |
type |
character scalar, keyword defining the distribution
function used to describe the parameter. See details for available
keywords, default is |
The following parameter types are available:
exact: parameter does not vary at all. No additional
parameters needed except for vector value, defining the
constant values for corresponding depths.
uniform: parameter varies following a uniform distribution.
The following additional parameter vectors are required: min
(minimum) and max (maximum)
normal: parameter varies following a normal distribution,
which is defined by mean and standard deviation
gamma: parameter varies following a gamma distribution,
defined by shape parameter, scale parameter)
and offset (defining constant offset of values)
A list object.
Michael Dietze, GFZ Potsdam (Germany)
## get empty rule book book_1 <- get_RuleBook(book = "empty") ## set density from default "normal" to "exact" book_2 <- set_Parameter(book = book_1, parameter = "density", type = "exact") book_1$density$density_1$type book_2$density$density_1$type## get empty rule book book_1 <- get_RuleBook(book = "empty") ## set density from default "normal" to "exact" book_2 <- set_Parameter(book = book_1, parameter = "density", type = "exact") book_1$density$density_1$type book_2$density$density_1$type
The function defines how the specified model parameter varies with depth. The transfer function uses different interpolation functions to create a continuous representation of a parameter value with depth.
set_Rule(book, parameter, value, depth, type = "spline")set_Rule(book, parameter, value, depth, type = "spline")
book |
list object, rule book to be edited. |
parameter |
character scalar, parameter name to be edited. Can also be the keyword for an OSL model. See details. |
value |
numeric list, specifying the parameter values at the corresponding depth points. If a parameter is defined by more than one argument (e.g., mean and standard deviation), all the relevant arguments must be defined for each corresponding depth as separate list element. |
depth |
numeric list, specifying the depths used for the
interpolation. All elements must be of the same lengths as the
corresponding data in |
type |
character scalar, interpolation method. One out of
|
To assign standard OSL model parameters, one of the available keywords of
the R package RLumModel::RLumModel-package can be used. The function will then set
all rules of the rule book with the standard values associated with these
models, and setting the standard deviation to zero. The keyword can be
one out of "Bailey2001", "Bailey2004", "Pagonis2008",
"Pagonis2007", "Bailey2002" and "Friedrich2017".
This will fill the rule book with the standard parameters independent of
depth. Note that a dose rate (parameter name osl_doserate) needs to
be set separately!
A list object with all created formula objects.
Michael Dietze, GFZ Potsdam (Germany), Sebastian Kreutzer, Geography & Earth Sciences, Aberystwyth University (United Kingdom)
## create empty rule book book_01 <- get_RuleBook() ## assign rule definitions to lists depth <- list(c(0, 10)) age <- list(c(0, 1000)) ## add age definition book_01 <- set_Rule( book = book_01, parameter = "age", value = age, depth = depth)## create empty rule book book_01 <- get_RuleBook() ## assign rule definitions to lists depth <- list(c(0, 10)) age <- list(c(0, 1000)) ## add age definition book_01 <- set_Rule( book = book_01, parameter = "age", value = age, depth = depth)