Add feldspar IRSL global Standardized Growth Curves (Li et al.,2015) to calc_gSGC()

Hi all,

I was hoping to request that calc_gSGC() include functionality for IRSL of feldspar per:

Li, B., Roberts, R. G., Jacobs, Z., Li, S. H., & Guo, Y. J. (2015). Construction of a ‘global standardised growth curve’(gSGC) for infrared stimulated luminescence dating of K-feldspar. Quaternary Geochronology, 27, 119-130.

There is currently functionality for quartz OSL, but I was wondering if feldspar IRSL functionality could be added for a future update. I feel that it largely involves adding in an equation and the parameters from the above citation to the current code, but I am unsure of the inner workings of calc_gSGC().

Cheers and thanks!

Harrison

@hjgray10 Is the integration ok? Means, can I close this issue?

I think so. I was not able to obtain new data to test the function any further. It doesn't look like there is data in Li et al. 2015 that we could use to test against either.

@hjgray10 No problem. Would you mind double-checking the documentation? If this is also ok, we can ship the function with the upcoming release.

Sorry to be an idiot – Where is the documentation?

@hjgray10 Don't worry, it is indeed not obvious because there are two files:

The R file: https://github.com/R-Lum/Luminescence/blob/dev_0.9.x/R/calc_gSGC_feldspar.R
This is the R code file with, what we call, inline documentation. Everything after #' is part of the documentation.

Luminescence/R/calc_gSGC_feldspar.R

Lines 1 to 67 in e9cccd0

    
           #'@title Calculate Global Standardised Growth Curve (gSGC) for Feldspar 
        
           #' 
        
           #'@description Implementation of the gSGC approach by Li et al. (2015) 
        
           #' 
        
           #'@details ##TODO 
        
           #' 
        
           #'@param data [data.frame] (**required**): data frame with five columns per sample 
        
           #'`c("LnTn", "LnTn.error", "Lr1Tr1", "Lr1Tr1.error","Dr1")` 
        
           #' 
        
           #'@param gSGC.type [character] (*with default*): growth curve type to be selected 
        
           #'according to Table 3 in Li et al. (2015). Allowed options are 
        
           #'`"50LxTx"`, `"50Lx"`, `"50Tx"`, `"100LxTx"`, `"100Lx"`, `"100Tx"`, `"150LxTx"`, 
        
           #' `"150Lx"`, `"150Tx"`, `"200LxTx"`, `"200Lx"`, `"200Tx"`, `"250LxTx"`, `"250Lx"`, 
        
           #' `"250Tx"` 
        
           #' 
        
           #'@param gSGC.parameters [data.frame] (*optional*): an own parameter set for the 
        
           #'gSGC with the following columns `y1`, `y1_err`, `D1` 
        
           #'`D1_err`, `y2`, `y2_err`, `y0`, `y0_err`. 
        
           #' 
        
           #'@param n.MC [numeric] (*with default*): number of Monte-Carlo runs for the 
        
           #'error calculation 
        
           #' 
        
           #'@param plot [logical] (*with default*): enables/disables the control plot output 
        
           #' 
        
           #'@return Returns an S4 object of type [RLum.Results-class]. 
        
           #' 
        
           #' **`@data`**\cr 
        
           #' `$ df` ([data.frame]) \cr 
        
           #'  `.. $DE` the calculated equivalent dose\cr 
        
           #'  `.. $DE.ERROR` terror on the equivalent dose, which is the standard deviation of the MC runs\cr 
        
           #'  `.. $HPD95_LOWER` lower boundary of the highest probability density (95%)\cr 
        
           #'  `.. $HPD95_UPPER` upper boundary of the highest probability density (95%)\cr 
        
           #' `$ m.MC` ([list]) numeric vector with results from the MC runs.\cr 
        
           #' 
        
           #' **`@info`**\cr 
        
           #' `$ call`` ([call]) the original function call 
        
           #' 
        
           #' @section Function version: 0.1.0 
        
           #' 
        
           #' @author Harrison Gray, USGS (United States), 
        
           #' Sebastian Kreutzer, Geography & Earth Sciences, Aberystwyth University (United Kingdom) 
        
           #' 
        
           #' @seealso [RLum.Results-class], [get_RLum], [uniroot], [calc_gSGC] 
        
           #' 
        
           #' @references Li, B., Roberts, R.G., Jacobs, Z., Li, S.-H., Guo, Y.-J., 2015. 
        
           #' Construction of a “global standardised growth curve” (gSGC) for infrared 
        
           #' stimulated luminescence dating of K-feldspar 27, 119–130. \doi{10.1016/j.quageo.2015.02.010} 
        
           #' 
        
           #' @keywords datagen 
        
           #' 
        
           #' @examples 
        
           #' 
        
           #' ##test on a generated random sample 
        
           #' n_samples <- 10 
        
           #' data <- data.frame( 
        
           #'   LnTn = rnorm(n=n_samples, mean=1.0, sd=0.02), 
        
           #'   LnTn.error = rnorm(n=n_samples, mean=0.05, sd=0.002), 
        
           #'   Lr1Tr1 = rnorm(n=n_samples, mean=1.0, sd=0.02), 
        
           #'   Lr1Tr1.error = rnorm(n=n_samples, mean=0.05, sd=0.002), 
        
           #'   Dr1 = rep(100,n_samples)) 
        
           #' 
        
           #' results <- calc_gSGC_feldspar( 
        
           #'   data = data, gSGC.type = "50LxTx", 
        
           #'   plot = FALSE) 
        
           #' 
        
           #' plot_AbanicoPlot(results) 
        
           #'

The Rd-file: From the R-file the documentation is created in https://github.com/R-Lum/Luminescence/blob/dev_0.9.x/man/calc_gSGC_feldspar.Rd
This is what the user sees when calling the manual page of the function, however, in our case, the rule is: never touch this file because it will be overwritten automatically every time I rebuild the package.

In other words, in order to check and modify the documentation, you have to modify the lines in https://github.com/R-Lum/Luminescence/blob/dev_0.9.x/R/calc_gSGC_feldspar.R

If you need further assistance, please just write again, no problem!

I guess we have it. I'll close this issue, please feel free to reopen it in case the work was not done.

	#'@title Calculate Global Standardised Growth Curve (gSGC) for Feldspar
	#'
	#'@description Implementation of the gSGC approach by Li et al. (2015)
	#'
	#'@details ##TODO
	#'
	#'@param data [data.frame] (required): data frame with five columns per sample
	#'`c("LnTn", "LnTn.error", "Lr1Tr1", "Lr1Tr1.error","Dr1")`
	#'
	#'@param gSGC.type [character] (with default): growth curve type to be selected
	#'according to Table 3 in Li et al. (2015). Allowed options are
	#'`"50LxTx"`, `"50Lx"`, `"50Tx"`, `"100LxTx"`, `"100Lx"`, `"100Tx"`, `"150LxTx"`,
	#' `"150Lx"`, `"150Tx"`, `"200LxTx"`, `"200Lx"`, `"200Tx"`, `"250LxTx"`, `"250Lx"`,
	#' `"250Tx"`
	#'
	#'@param gSGC.parameters [data.frame] (optional): an own parameter set for the
	#'gSGC with the following columns `y1`, `y1_err`, `D1`
	#'`D1_err`, `y2`, `y2_err`, `y0`, `y0_err`.
	#'
	#'@param n.MC [numeric] (with default): number of Monte-Carlo runs for the
	#'error calculation
	#'
	#'@param plot [logical] (with default): enables/disables the control plot output
	#'
	#'@return Returns an S4 object of type [RLum.Results-class].
	#'
	#' `@data`\cr
	#' `$ df` ([data.frame]) \cr
	#' `.. $DE` the calculated equivalent dose\cr
	#' `.. $DE.ERROR` terror on the equivalent dose, which is the standard deviation of the MC runs\cr
	#' `.. $HPD95_LOWER` lower boundary of the highest probability density (95%)\cr
	#' `.. $HPD95_UPPER` upper boundary of the highest probability density (95%)\cr
	#' `$ m.MC` ([list]) numeric vector with results from the MC runs.\cr
	#'
	#' `@info`\cr
	#' `$ call`` ([call]) the original function call
	#'
	#' @section Function version: 0.1.0
	#'
	#' @author Harrison Gray, USGS (United States),
	#' Sebastian Kreutzer, Geography & Earth Sciences, Aberystwyth University (United Kingdom)
	#'
	#' @seealso [RLum.Results-class], [get_RLum], [uniroot], [calc_gSGC]
	#'
	#' @references Li, B., Roberts, R.G., Jacobs, Z., Li, S.-H., Guo, Y.-J., 2015.
	#' Construction of a “global standardised growth curve” (gSGC) for infrared
	#' stimulated luminescence dating of K-feldspar 27, 119–130. \doi{10.1016/j.quageo.2015.02.010}
	#'
	#' @keywords datagen
	#'
	#' @examples
	#'
	#' ##test on a generated random sample
	#' n_samples <- 10
	#' data <- data.frame(
	#' LnTn = rnorm(n=n_samples, mean=1.0, sd=0.02),
	#' LnTn.error = rnorm(n=n_samples, mean=0.05, sd=0.002),
	#' Lr1Tr1 = rnorm(n=n_samples, mean=1.0, sd=0.02),
	#' Lr1Tr1.error = rnorm(n=n_samples, mean=0.05, sd=0.002),
	#' Dr1 = rep(100,n_samples))
	#'
	#' results <- calc_gSGC_feldspar(
	#' data = data, gSGC.type = "50LxTx",
	#' plot = FALSE)
	#'
	#' plot_AbanicoPlot(results)
	#'