EstimationTools (version 4.0.0)

TTTE_Analytical: Empirical Total Time on Test (TTT), analytic version.

Description

This function allows to compute the TTT curve from a formula containing a factor type variable (classification variable).

Usage

TTTE_Analytical(
  formula,
  response = NULL,
  scaled = TRUE,
  data = NULL,
  method = c("Barlow", "censored"),
  partition_method = NULL,
  silent = FALSE,
  ...
)

Value

A list with class object Empirical.TTT containing a list with the following information:

i/n`

A matrix containing the empirical quantiles. This matrix has the number of columns equals to the number of levels of the factor considered (number of strata).

phi_n

A matrix containing the values of empirical TTT. his matrix has the number of columns equals to the number of levels of the factor considered (number of strata).

strata

A numeric named vector storing the number of observations per strata, and the name of each strata (names of the levels of the factor).

Arguments

formula

an object of class formula with the response on the left of an operator ~. The right side can be a factor variable as term or an 1 if a classification by factor levels is not desired.

response

an optional numeric vector with data of the response variable. Using this argument is equivalent to define a formula with the right side such as ~ 1. See the fourth example below.

scaled

logical. If TRUE (default value), scaled TTT is computed.

data

an optional data frame containing the variables (response and the factor, if it is desired). If data is not specified, the variables are taken from the environment from which TTT_analytical is called.

method

a character specifying the method of computation. There are two options available: 'Barlow' and 'censored'. Further information can be found in the Details section.

partition_method

a list specifying cluster formation when the covariate in formula is numeric, or when the data has several covariates. 'quantile-based' method is the only one currently available (See the last example).

silent

logical. If TRUE, warnings of TTTE_Analytical are suppressed.

...

further arguments passing to survfit.

Author

Jaime Mosquera Gutiérrez,

Details

When method argument is set as 'Barlow', this function uses the original expression of empirical TTT presented by Barlow1979;textualEstimationTools and used by Aarset1987;textualEstimationTools:

$$\phi_n\left( \frac{r}{n}\right) = \frac{\left( \sum_{i=1}^{r} T_{(i)} \right) + (n-r)T_{(r)}}{\sum_{i=1}^{n} T_i}$$

where \(T_{(r)}\) is the \(r^{th}\) order statistic, with \(r=1,2,\dots, n\), and \(n\) is the sample size. On the other hand, the option 'censored' is an implementation based on integrals presented in Westberg1994;textualEstimationTools, and using survfit to compute the Kaplan-Meier estimator:

$$\phi_n\left( \frac{r}{n}\right) = \sum_{j=1}^{r} \left[ \prod_{i=1}^{j} \left( 1 - \frac{d_i}{n_i}\right) \right] \left(T_{(j)} - T_{(j-1)} \right)$$

References

Barlow1979EstimationTools

Aarset1987EstimationTools

Klefsjo1991EstimationTools

Westberg1994EstimationTools

See Also

plot.EmpiricalTTT

Examples

library(EstimationTools)

#--------------------------------------------------------------------------------
# Example 1: Scaled empirical TTT from 'mgus1' data from 'survival' package.

TTT_1 <- TTTE_Analytical(Surv(stop, event == 'pcm') ~1, method = 'cens',
                         data = mgus1, subset=(start == 0))
head(TTT_1$`i/n`)
head(TTT_1$phi_n)
print(TTT_1$strata)


#--------------------------------------------------------------------------------
# Example 2: Scaled empirical TTT using a factor variable with 'aml' data
# from 'survival' package.

TTT_2 <- TTTE_Analytical(Surv(time, status) ~ x, method = "cens", data = aml)
head(TTT_2$`i/n`)
head(TTT_2$phi_n)
print(TTT_2$strata)

#--------------------------------------------------------------------------------
# Example 3: Non-scaled empirical TTT without a factor (arbitrarily simulated
# data).

set.seed(911211)
y <- rweibull(n=20, shape=1, scale=pi)
TTT_3 <- TTTE_Analytical(y ~ 1, scaled = FALSE)
head(TTT_3$`i/n`)
head(TTT_3$phi_n)
print(TTT_3$strata)


#--------------------------------------------------------------------------------
# Example 4: non-scaled empirical TTT without a factor (arbitrarily simulated
# data) using the 'response' argument (this is equivalent to Third example).

set.seed(911211)
y <- rweibull(n=20, shape=1, scale=pi)
TTT_4 <- TTTE_Analytical(response = y, scaled = FALSE)
head(TTT_4$`i/n`)
head(TTT_4$phi_n)
print(TTT_4$strata)

#--------------------------------------------------------------------------------
# Eample 5: empirical TTT with a continuously variant term for the shape
# parameter in Weibull distribution.

x <- runif(50, 0, 10)
shape <- 0.1 + 0.1*x
y <- rweibull(n = 50, shape = shape, scale = pi)

partitions <- list(method='quantile-based',
                   folds=5)
TTT_5 <- TTTE_Analytical(y ~ x, partition_method = partitions)
head(TTT_5$`i/n`)
head(TTT_5$phi_n)
print(TTT_5$strata)
plot(TTT_5) # Observe changes in Empirical TTT

#--------------------------------------------------------------------------------