HelpersMG (version 6.4)

cutter: Distribution of the fitted distribution without cut.

Description

If observations is a data.frame, it can have 4 columns:
A column for the measurements;
A column for the lower detection limit;
A column for the upper detection limit;
A column for the truncated of censored nature of the data.
The names of the different columns are in the observations.colname, lower_detection_limit.colname, upper_detection_limit.colname and cut_method.colname.
If lower_detection_limit.colname is NULL or if the column does not exist, the data are supposed to not be left-cut and if upper_detection_limit.colname is NULL or if the column does not exist, the data are supposed to not be right-cut.
If observations is a vector, then the parameters lower_detection_limit and/or upper_detection_limit must be given. Then cut_method must be also provided.
In abservations, -Inf must be used to indicate a value below the lower detection limit and +Inf must be used for a value above the upper detection limit.
Be careful: NA is used to represent a missing data and not a value below of above the detection limit.
If lower_detection_limit, upper_detection_limit or cut_method are only one value, they are supposed to be used for all the observations.
Definitions for censored or truncated distribution vary, and the two terms are sometimes used interchangeably. Let the following data set:
1 1.25 2 4 5

Censoring: some observations will be censored, meaning that we only know that they are below (or above) some bound. This can for instance occur if we measure the concentration of a chemical in a water sample. If the concentration is too low, the laboratory equipment cannot detect the presence of the chemical. It may still be present though, so we only know that the concentration is below the laboratory's detection limit.

If the detection limit is 1.5, so that observations that fall below this limit is censored, our example data set would become:
<1.5 <1.5 2 4 5; that is, we don't know the actual values of the first two observations, but only that they are smaller than 1.5.

Truncation: the process generating the data is such that it only is possible to observe outcomes above (or below) the truncation limit. This can for instance occur if measurements are taken using a detector which only is activated if the signals it detects are above a certain limit. There may be lots of weak incoming signals, but we can never tell using this detector.

If the truncation limit is 1.5, our example data set would become: 2 4 5; and we would not know that there in fact were two signals which were not recorded.
If n.iter is NULL, no Bayesian MCMC is performed but credible interval will not be available.

Usage

cutter(
  observations = stop("Observations must be provided"),
  observations.colname = "Observations",
  lower_detection_limit.colname = "LDL",
  upper_detection_limit.colname = "UDL",
  cut_method.colname = "Cut",
  par = NULL,
  lower_detection_limit = NULL,
  upper_detection_limit = NULL,
  cut_method = "censored",
  distribution = "gamma",
  n.mixture = 1,
  n.iter = 5000,
  n.adapt = 100,
  debug = FALSE,
  progress.bar = TRUE,
  session = NULL
)

Value

The parameters of distribution of values below or above the detection limit.

Arguments

observations

The observations; see description

observations.colname

If observations is a data.frame, the name of column with observations

lower_detection_limit.colname

If observations is a data.frame, the name of column with lower detection limit

upper_detection_limit.colname

If observations is a data.frame, the name of column with upper detection limit

cut_method.colname

If observations is a data.frame, the name of column with cut method, being "censored" or "truncated"

par

Initial values for parameters of distribution

lower_detection_limit

Value for lower detection limit

upper_detection_limit

Value for upper detection limit

cut_method

Value for cut method, being "censored" or "truncated"

distribution

Can be gamma, normal, weibull, lognormal, or generalized.gamma

n.mixture

Number of distributions

n.iter

Number of iteration for Bayesian MCMC and to estimate the goodness-of-fit

n.adapt

Number of burn-in iterations Bayesian MCMC

debug

If TRUE, show some information

progress.bar

If TRUE, show a progress bar for MCMC

session

The session of a shiny process

Author

Marc Girondot

Details

cutter returns the fitted distribution without cut

See Also

Other Distributions: dSnbinom(), dbeta_new(), dcutter(), dggamma(), logLik.cutter(), plot.cutter(), print.cutter(), r2norm(), rcutter(), rmnorm(), rnbinom_new()

Examples

if (FALSE) {
library(HelpersMG)
# _______________________________________________________________
# right censored distribution with gamma distribution
# _______________________________________________________________
# Detection limit
DL <- 100
# Generate 100 random data from a gamma distribution
obc <- rgamma(100, scale=20, shape=2)
# remove the data below the detection limit
obc[obc>DL] <- +Inf
# search for the parameters the best fit these censored data
result <- cutter(observations=obc, upper_detection_limit=DL, 
                           cut_method="censored")
result
plot(result, xlim=c(0, 150), breaks=seq(from=0, to=150, by=10), col.mcmc=NULL)
plot(result, xlim=c(0, 150), breaks=seq(from=0, to=150, by=10))
# _______________________________________________________________
# The same data seen as truncated data with gamma distribution
# _______________________________________________________________
obc <- obc[is.finite(obc)]
# search for the parameters the best fit these truncated data
result <- cutter(observations=obc, upper_detection_limit=DL, 
                           cut_method="truncated")
result
plot(result, xlim=c(0, 150), breaks=seq(from=0, to=150, by=10))
# _______________________________________________________________
# left censored distribution with gamma distribution
# _______________________________________________________________
# Detection limit
DL <- 10
# Generate 100 random data from a gamma distribution
obc <- rgamma(100, scale=20, shape=2)
# remove the data below the detection limit
obc[obcUDL] <- +Inf

# search for the parameters the best fit these truncated data
result1_gamma <- cutter(observations=obc, lower_detection_limit=LDL, 
                          upper_detection_limit = UDL, 
                          distribution="gamma", 
                          cut_method="censored", n.iter=5000, debug=0)
result1_normal <- cutter(observations=obc, lower_detection_limit=LDL, 
                          upper_detection_limit = UDL, 
                          distribution="normal", 
                          cut_method="censored", n.iter=5000)
result1_lognormal <- cutter(observations=obc, lower_detection_limit=LDL, 
                          upper_detection_limit = UDL, 
                          distribution="lognormal", 
                          cut_method="censored", n.iter=5000)
result1_Weibull <- cutter(observations=obc, lower_detection_limit=LDL, 
                          upper_detection_limit = UDL,  
                          distribution="Weibull", 
                          cut_method="censored", n.iter=5000)
result1_generalized.gamma <- cutter(observations=obc, lower_detection_limit=LDL, 
                          upper_detection_limit = UDL, 
                          distribution="generalized.gamma", 
                          cut_method="censored", n.iter=5000)
result2_gamma <- cutter(observations=obc, lower_detection_limit=LDL, 
                          upper_detection_limit = UDL, 
                          distribution="gamma", 
                          n.mixture=2, 
                          cut_method="censored", n.iter=5000)
result2_normal <- cutter(observations=obc, lower_detection_limit=LDL, 
                          upper_detection_limit = UDL, 
                          distribution="normal", 
                          n.mixture=2, 
                          cut_method="censored", n.iter=5000)
result2_lognormal <- cutter(observations=obc, lower_detection_limit=LDL, 
                          upper_detection_limit = UDL, 
                          distribution="lognormal", 
                          n.mixture=2, 
                          cut_method="censored", n.iter=5000)
result2_Weibull <- cutter(observations=obc, lower_detection_limit=LDL, 
                          upper_detection_limit = UDL, 
                          distribution="Weibull", 
                          n.mixture=2, 
                          cut_method="censored", n.iter=5000)
result2_generalized.gamma <- cutter(observations=obc, lower_detection_limit=LDL, 
                          upper_detection_limit = UDL, 
                          distribution="generalized.gamma", 
                          n.mixture=2, 
                          cut_method="censored", n.iter=5000)
                          
compare_AIC(nomixture.gamma=result1_gamma, 
             nomixture.normal=result1_normal, 
             nomixture.lognormal=result1_lognormal, 
             nomixture.Weibull=result1_Weibull, 
             nomixture.generalized.gamma=result1_generalized.gamma, 
             mixture.gamma=result2_gamma, 
             mixture.normal=result2_normal, 
             mixture.lognormal=result2_lognormal, 
             mixture.Weibull=result2_Weibull, 
             mixture.generalized.gamma=result2_generalized.gamma)
             
plot(result2_gamma, xlim=c(0, 600), breaks=seq(from=0, to=600, by=10))
plot(result2_generalized.gamma, xlim=c(0, 600), breaks=seq(from=0, to=600, by=10))

# _______________________________________________________________
# left and right censored distribution
# _______________________________________________________________
# Generate 100 random data from a gamma distribution
obc <- rgamma(100, scale=20, shape=2)
# Detection limit
LDL <- 10
# remove the data below the detection limit
obc[obcUDL] <- +Inf
# search for the parameters the best fit these censored data
result <- cutter(observations=obc, lower_detection_limit=LDL, 
                           upper_detection_limit=UDL, 
                          cut_method="censored")
result
plot(result, xlim=c(0, 150), col.DL=c("black", "grey"), 
                             col.unobserved=c("green", "blue"), 
     breaks=seq(from=0, to=150, by=10))
# _______________________________________________________________
# Example with two values for lower detection limits
# corresponding at two different methods of detection for example
# with gamma distribution
# _______________________________________________________________
obc <- rgamma(50, scale=20, shape=2)
# Detection limit for sample 1 to 50
LDL1 <- 10
# remove the data below the detection limit
obc[obc