From e316fb59670ca64b0c4891683cedc5f0e4797916 Mon Sep 17 00:00:00 2001 From: Niklas Hohmann <67792281+NiklasHohmann@users.noreply.github.com> Date: Fri, 6 Dec 2024 11:01:14 +0100 Subject: [PATCH] clarify vignette, increase connectivity of documentation --- DESCRIPTION | 2 +- R/sedrate_gen_helpers.R | 10 ++++++++-- man/sed_rate_from_matrix.Rd | 8 +++++++- man/sed_rate_gen_from_bounds.Rd | 2 +- vignettes/adm_from_sedrate.Rmd | 4 ++-- 5 files changed, 19 insertions(+), 7 deletions(-) diff --git a/DESCRIPTION b/DESCRIPTION index a270755..6a66411 100644 --- a/DESCRIPTION +++ b/DESCRIPTION @@ -1,6 +1,6 @@ Package: admtools Title: Estimate and Manipulate Age-Depth Models -Version: 0.4.0.9000 +Version: 0.4.0.9001 Authors@R: person("Niklas", "Hohmann", , "N.H.Hohmann@uu.nl", role = c("aut", "cre"), comment = c(ORCID = "0000-0003-1559-1838")) diff --git a/R/sedrate_gen_helpers.R b/R/sedrate_gen_helpers.R index 4749e64..472b9d4 100644 --- a/R/sedrate_gen_helpers.R +++ b/R/sedrate_gen_helpers.R @@ -60,11 +60,17 @@ sed_rate_from_matrix = function(height, sedrate, matrix, mode = "deterministic", #' #' @returns a function factory for usage with `sedrate_to_multiadm` #' - #' @seealso [sedrate_to_multiadm()] for estimating sedimentation rates based on the outputs, [get_data_from_eTimeOpt()] for extracting data from the `eTimeOpt` function of the astrochron package. + #' @seealso [sedrate_to_multiadm()] for estimating sedimentation rates based on the outputs, [get_data_from_eTimeOpt()] for extracting data from the `eTimeOpt` function of the astrochron package. [sed_rate_gen_from_bounds()] for construction sedimentation rate generators from simple bounds. See also the vignettes for details on how arbitrary sedimentation rates can be constructed. #' #' @description #' Construct a sedimentation rate generator (function factory) from a matrix, e.g. one returned from `get_data_from_eTimeOpt`. This generator can be passed on to `sedrate_to_multiadm` to estimate age-depth models from it. #' If mode is "deterministic", the generator evaluates the sedimentation rates at heights specified by `height`, if the mode is "poisson" it is evaluated at heights that are determined based on a poisson point process. At these heights, the value of the sedimentation rate is determined based on the (pseudo) pdf that is determined by the matrix values. + #' + #' @examples + #' # see vignette + #' # vignette("adm_from_sedrate") + #' # for more general examples + #' if (!all(dim(matrix) == c(length(sedrate), length(height)))){ stop("dimension mismatch. \"matrix\" must have length(height) columns and length(sedrate) rows") } @@ -137,7 +143,7 @@ sed_rate_gen_from_bounds = function(h_l, s_l, h_u, s_u, rate = 1){ #' constructs a sedimentation rate generator for usage with `sedrate_to_multiadm` based on the following procedure: (1) determine stratigraphic points based on a Poisson point process with rate `rate` (2) at these points, determine the sedimentation rate based on a uniform distribution between the bounds provided by the input parameters (3) linearly interpolate between those points with sedimentation rate determined in step 2. #' This approach can be used to estimate age-depth models when only rough boundaries on sedimentation rates are available. Here, the uniform distribution is chosen to reflect that no other information other than maximum and minimum sed. rate is available. #' - #' @seealso [sedrate_to_multiadm()] for estimating age-depth models using the outputs, [sed_rate_from_matrix()] for other means of defining sedimentation rates + #' @seealso [sedrate_to_multiadm()] for estimating age-depth models using the outputs, [sed_rate_from_matrix()] for other means of defining sedimentation rates, the vignette on how to construct arbitrary sedimentation rate generators. #' #' @examples #' # see vignette diff --git a/man/sed_rate_from_matrix.Rd b/man/sed_rate_from_matrix.Rd index 96a4764..1340b57 100644 --- a/man/sed_rate_from_matrix.Rd +++ b/man/sed_rate_from_matrix.Rd @@ -35,7 +35,13 @@ a function factory for usage with \code{sedrate_to_multiadm} \description{ Construct a sedimentation rate generator (function factory) from a matrix, e.g. one returned from \code{get_data_from_eTimeOpt}. This generator can be passed on to \code{sedrate_to_multiadm} to estimate age-depth models from it. If mode is "deterministic", the generator evaluates the sedimentation rates at heights specified by \code{height}, if the mode is "poisson" it is evaluated at heights that are determined based on a poisson point process. At these heights, the value of the sedimentation rate is determined based on the (pseudo) pdf that is determined by the matrix values. +} +\examples{ +# see vignette +# vignette("adm_from_sedrate") +# for more general examples + } \seealso{ -\code{\link[=sedrate_to_multiadm]{sedrate_to_multiadm()}} for estimating sedimentation rates based on the outputs, \code{\link[=get_data_from_eTimeOpt]{get_data_from_eTimeOpt()}} for extracting data from the \code{eTimeOpt} function of the astrochron package. +\code{\link[=sedrate_to_multiadm]{sedrate_to_multiadm()}} for estimating sedimentation rates based on the outputs, \code{\link[=get_data_from_eTimeOpt]{get_data_from_eTimeOpt()}} for extracting data from the \code{eTimeOpt} function of the astrochron package. \code{\link[=sed_rate_gen_from_bounds]{sed_rate_gen_from_bounds()}} for construction sedimentation rate generators from simple bounds. See also the vignettes for details on how arbitrary sedimentation rates can be constructed. } diff --git a/man/sed_rate_gen_from_bounds.Rd b/man/sed_rate_gen_from_bounds.Rd index d1ead2a..fa2c242 100644 --- a/man/sed_rate_gen_from_bounds.Rd +++ b/man/sed_rate_gen_from_bounds.Rd @@ -31,5 +31,5 @@ This approach can be used to estimate age-depth models when only rough boundarie } \seealso{ -\code{\link[=sedrate_to_multiadm]{sedrate_to_multiadm()}} for estimating age-depth models using the outputs, \code{\link[=sed_rate_from_matrix]{sed_rate_from_matrix()}} for other means of defining sedimentation rates +\code{\link[=sedrate_to_multiadm]{sedrate_to_multiadm()}} for estimating age-depth models using the outputs, \code{\link[=sed_rate_from_matrix]{sed_rate_from_matrix()}} for other means of defining sedimentation rates, the vignette on how to construct arbitrary sedimentation rate generators. } diff --git a/vignettes/adm_from_sedrate.Rmd b/vignettes/adm_from_sedrate.Rmd index d977f3a..7c81d31 100644 --- a/vignettes/adm_from_sedrate.Rmd +++ b/vignettes/adm_from_sedrate.Rmd @@ -43,7 +43,7 @@ Additional parameters that determine the numeric behavior of the integration met ## Example -We construct an age depth model for a section of 10 m thickness where upper and lower bounds on sedimentation rates are available. +We construct an age depth model for a section of 10 m thickness where upper and lower bounds on sedimentation rates are available. This is a simplified example, details on how arbitrary sedimentation rates can be encoded can be found below. ### Data @@ -160,7 +160,7 @@ plot(mean_adm) ### Background -Times and heights of tie points are coded via the functions `t_tp` (timing) and `h_tp` (height) that take no inputs. They serve as wrappers around user-defined procedures that reflect uncertainties around tie points. Every time `t_tp` and `h_tp` are evaluated, they return possible values for the tie points. Conceptually, both `t_tp`and `h_tp` are user implemented random number generators that draw from the distributions of tie points. Writing these functions requires some effort, but it allows the user to hand over arbitrarily complex uncertainties of the tie points to the `strat_cont_to_multiadm` function. +Times and heights of tie points are coded via the functions `t_tp` (timing) and `h_tp` (height) that take no inputs. They serve as wrappers around user-defined procedures that reflect uncertainties around tie points. Every time `t_tp` and `h_tp` are evaluated, they return possible values for the tie points. Conceptually, both `t_tp`and `h_tp` are user implemented random number generators that draw from the distributions of tie points. Writing these functions requires some effort, but it allows the user to hand over arbitrarily complex uncertainties of the tie points to the `sedrate_to_multiadm` function. ### Wrappers