Luminescence (version 0.9.25)

calc_Statistics: Function to calculate statistic measures

Description

This function calculates a number of descriptive statistics for estimates with a given standard error (SE), most fundamentally using error-weighted approaches.

Usage

calc_Statistics(
  data,
  weight.calc = "square",
  digits = NULL,
  n.MCM = NULL,
  na.rm = TRUE
)

Value

Returns a list with weighted and unweighted statistic measures.

Arguments

data

data.frame or RLum.Results object (required): for data.frame two columns: De (data[,1]) and De error (data[,2]). To plot several data sets in one plot the data sets must be provided as list, e.g. list(data.1, data.2).

weight.calc

character: type of weight calculation. One out of "reciprocal" (weight is 1/error), "square" (weight is 1/error^2). Default is "square".

digits

integer (with default): round numbers to the specified digits. If digits is set to NULL nothing is rounded.

n.MCM

numeric (with default): number of samples drawn for Monte Carlo-based statistics. NULL (the default) disables MC runs.

na.rm

logical (with default): indicating whether NA values should be stripped before the computation proceeds.

Function version

0.1.7

Author

Michael Dietze, GFZ Potsdam (Germany) , RLum Developer Team

How to cite

Dietze, M., 2024. calc_Statistics(): Function to calculate statistic measures. Function version 0.1.7. In: Kreutzer, S., Burow, C., Dietze, M., Fuchs, M.C., Schmidt, C., Fischer, M., Friedrich, J., Mercier, N., Philippe, A., Riedesel, S., Autzen, M., Mittelstrass, D., Gray, H.J., Galharret, J., Colombo, M., 2024. Luminescence: Comprehensive Luminescence Dating Data Analysis. R package version 0.9.25. https://r-lum.github.io/Luminescence/

Details

The option to use Monte Carlo Methods (n.MCM) allows calculating all descriptive statistics based on random values. The distribution of these random values is based on the Normal distribution with De values as means and De_error values as one standard deviation. Increasing the number of MCM-samples linearly increases computation time. On a Lenovo X230 machine evaluation of 25 Aliquots with n.MCM = 1000 takes 0.01 s, with n = 100000, ca. 1.65 s. It might be useful to work with logarithms of these values. See Dietze et al. (2016, Quaternary Geochronology) and the function plot_AbanicoPlot for details.

Examples

## load example data
data(ExampleData.DeValues, envir = environment())

## show a rough plot of the data to illustrate the non-normal distribution
plot_KDE(ExampleData.DeValues$BT998)

## calculate statistics and show output
str(calc_Statistics(ExampleData.DeValues$BT998))

if (FALSE) {
## now the same for 10000 normal distributed random numbers with equal errors
x <- as.data.frame(cbind(rnorm(n = 10^5, mean = 0, sd = 1),
                         rep(0.001, 10^5)))

## note the congruent results for weighted and unweighted measures
str(calc_Statistics(x))
}