Title:	Parametric Time to Event Analysis
Version:	0.3.0.1
Description:	Performs maximum likelihood based estimation and inference on time to event data, possibly subject to non-informative right censoring. FitParaSurv() provides maximum likelihood estimates of model parameters and distributional characteristics, including the mean, median, variance, and restricted mean. CompParaSurv() compares the mean, median, and restricted mean survival experiences of two treatment groups. Candidate distributions include the exponential, gamma, generalized gamma, log-normal, and Weibull.
Depends:	R (≥ 3.5.0)
License:	GPL-3
Encoding:	UTF-8
Imports:	dplyr, expint, methods, numDeriv, stats, tidyr
RoxygenNote:	7.2.3
Suggests:	testthat (≥ 3.0.0), knitr, rmarkdown, withr
VignetteBuilder:	knitr
Config/testthat/edition:	3
NeedsCompilation:	no
Packaged:	2023-09-23 16:34:28 UTC; zmccaw
Author:	Zachary McCaw [aut, cre]
Maintainer:	Zachary McCaw <zmccaw@alumni.harvard.edu>
Repository:	CRAN
Date/Publication:	2023-09-23 17:40:02 UTC

Temporal: Parametric Time to Event Analysis

Description

Performs maximum likelihood based estimation and inference on time to event data, possibly subject to non-informative right censoring. FitParaSurv() provides maximum likelihood estimates of model parameters and distributional characteristics, including the mean, median, variance, and restricted mean. CompParaSurv() compares the mean, median, and restricted mean survival experiences of two treatment groups. Candidate distributions include the exponential, gamma, generalized gamma, log-normal, and Weibull.

Author(s)

Maintainer: Zachary McCaw zmccaw@alumni.harvard.edu (ORCID)

Check Arm

Description

Check whether treatment arm is properly formatted.

Usage

CheckArm(arm)

Arguments

Value

None.

Check Distribution

Description

Check whether the distribution selected is available.

Usage

CheckDist(dist)

Arguments

Value

None.

Check Initialization

Description

Check whether the initialization is valid.

Usage

CheckInit(dist, init)

Arguments

Value

None.

Status Check

Description

Function to ensure the status indicator is properly formatted

Usage

CheckStatus(status)

Arguments

Value

None.

Check Theta

Description

Function to check the appropriate number of parameters are supplied for the selected distribution. Used by GenData.

Usage

CheckTheta(dist, theta)

Arguments

Value

None.

Compare Parametric Survival Distribution

Description

Compares the means and medians of parametric survival distributions fit to two treatment arms. Available distributions include: exponential, gamma, generalized gamma, log-normal, and Weibull.

Usage

CompParaSurv(
  data,
  arm_name = "arm",
  dist1 = "weibull",
  dist0 = NULL,
  eps = 1e-06,
  init1 = NULL,
  init0 = NULL,
  maxit = 10,
  report = FALSE,
  reps = NULL,
  sig = 0.05,
  status_name = "status",
  tau = NULL,
  time_name = "time"
)

Arguments

Details

Status should be coded as 0 for censored and 1 for observed. Arm is coded as 0 for reference, 1 for target. Tau is an optional numeric vector of truncation times for calculating restricted mean survival time, which is the area under the survival curve up to the specified truncation point.

Value

An object of class contrast containing the following:

Model1

The fitted model for the target group.

Model0

The fitted model for the reference group.

Contrast

Contrasts of means and medians.

RMST

Contrasts of the RMSTs, if 'tau' was specified.

Examples

set.seed(100)
# Weibull and Weibull, different means and medians.
n <- 1e3

# Generate data.
df1 <- GenData(n = n, dist = "weibull", theta = c(1, 1), p = 0.2)
df1$arm <- 1
df0 <- GenData(n = n, dist = "weibull", theta = c(1, 2), p = 0.2)
df0$arm <- 0
data <- rbind(df1, df0)

# Comparison.
comp <- CompParaSurv(data, dist1 = "weibull")

# Add RMST at time 1.
comp <- CompParaSurv(data, dist1 = "weibull", tau = 1)

# Calculate permutation p-values (slow).
comp <-  CompParaSurv(data, dist1 = "weibull", tau = 1, reps = 100)

Contrast Locations

Description

Compare the means and medians of the fitted distributions for two treatment arms.

Usage

ContrastLocs(fit1, fit0, sig = 0.05)

Arguments

Value

Data.frame contrasting the difference and ratio of the mean and median at each time point.

Contrast RMSTs

Description

Compare the restricted mean survival times of the fitted distributions for two treatment arms.

Usage

ContrastRMSTs(fit1, fit0, sig = 0.05)

Arguments

Value

Data.frame contrasting the difference and ratio of RMSTs at each time point.

Set Default Parameters

Description

Function to select default parameter values for each distribution.

Usage

DefaultParam(dist)

Arguments

Value

Numeric parameter ist.

Distributions

Description

Distributions

Usage

DistProperName(dist)

Arguments

Value

String.

Difference of Estimates

Description

Calculate CIs and p-value for the difference of estimates.

Usage

EstDiff(est1, se1, est0, se0, sig = 0.05)

Arguments

Value

Data.frame containing estimated difference, its standard error, lower and upper confidence bounds, and a p-value assessing the null hypothesis of no difference.

Ratio of Estimates

Description

Calculate CIs and p-value for the ratio of estimates.

Usage

EstRatio(est1, se1, est0, se0, sig = 0.05)

Arguments

Value

Data.frame containing estimated ratio, its standard error, lower and upper confidence bounds, and a p-value assessing the null hypothesis that the ratio is unity.

Extract Observed Estimates

Description

Helper function for permutation inference.

Usage

ExtractObsEst(fit1, fit0)

Arguments

Value

Numeric vector.

Exponential Distribution Parameter Estimation

Description

Estimates parameters for exponential event times subject to non-informative right censoring. The exponential distribution is parameterized in terms of the rate \lambda:

f(t) = \lambda e^{-\lambda t}, t>0

Usage

FitExp(
  data,
  sig = 0.05,
  status_name = "status",
  tau = NULL,
  time_name = "time"
)

Arguments

Value

An object of class fit containing the following:

Parameters

The estimated model parameters.

Information

The observed information matrix.

Outcome

The fitted mean, median, and variance of the time to event distribution.

RMST

The estimated RMSTs, if tau was specified.

Examples

# Generate exponential event time data with 20% censoring.
data <- GenData(n = 1e3, dist = "exp", theta = c(2), p = 0.2)

# Estimate parameters.
fit <- FitParaSurv(data, dist = "exp")

Gamma Distribution Parameter Estimation

Description

Estimates parameters for gamma event times subject to non-informative right censoring. The gamma distribution is parameterized in terms of the shape \alpha and rate \lambda:

f(t) = \frac{\lambda}{\Gamma(\alpha)}(\lambda t)^{\alpha-1}e^{-\lambda t}, t>0

Usage

FitGamma(
  data,
  eps = 1e-06,
  init = list(),
  maxit = 10,
  report = FALSE,
  sig = 0.05,
  status_name = "status",
  tau = NULL,
  time_name = "time"
)

Arguments

Value

An object of class fit containing the following:

Parameters

The estimated shape \alpha and rate \lambda.

Information

The observed information matrix.

Outcome

The fitted mean, median, and variance.

RMST

The estimated RMSTs, if tau was specified.

Examples

# Generate Gamma data with 20% censoring.
data <- GenData(n = 1e3, dist = "gamma", theta = c(2, 2), p = 0.2)

# Estimate parameters.
fit <- FitParaSurv(data, dist = "gamma")

Gamma Parameter Estimation without Censoring

Description

Paramter estimation for gamma event times without censoring.

Usage

FitGammaComplete(data, eps = 1e-06)

Arguments

Value

Numeric vector containing the estimated shape and rate parameters.

Generalized Gamma Distribution Parameter Estimation

Description

Estimates parameters for generalized gamma event times subject to non-informative right censoring. The gamma distribution is parameterized in terms of the shape parameters (\alpha,\beta), and the rate \lambda:

f(t) = \frac{\beta\lambda}{\Gamma(\alpha)} (\lambda t)^{\alpha\beta-1}e^{-(\lambda t)^{\beta}}, t>0

Usage

FitGenGamma(
  data,
  beta_lower = 0.1,
  beta_upper = 10,
  eps = 1e-06,
  init = list(),
  maxit = 10,
  report = FALSE,
  sig = 0.05,
  status_name = "status",
  tau = NULL,
  time_name = "time"
)

Arguments

Value

An object of class fit containing the following:

Parameters

The estimated shape (\alpha,\beta) and rate \lambda parameters.

Information

The observed information matrix.

Outcome

The fitted mean, median, and variance.

RMST

The estimated RMSTs, if tau was specified.

Examples

set.seed(103)
# Generate generalized gamma data with 20% censoring.
data <- GenData(n = 1e4, dist = "gen-gamma", theta = c(2, 2, 2), p = 0.2)

# Estimate parameters.
fit <- FitParaSurv(data, dist = "gen-gamma", report = TRUE)

Generalized Gamma Parameter Estimation without Censoring

Description

Paramter estimation for generalized gamma event times without censoring.

Usage

FitGenGammaComplete(data, beta_lower = 0.1, beta_upper = 10)

Arguments

Value

Numeric vector containing the estimated shape and rate parameters.

Log-Normal Parameter Estimation without Censoring

Description

Log-Normal Parameter Estimation without Censoring

Usage

FitLogNormComplete(data)

Arguments

Value

Numeric vector containing the estimate location and scale parameters.

Log-Normal Distribution Parameter Estimation

Description

Estimates parameters for log-normal event times subject to non-informative right censoring. The log-normal distribution is parameterized in terms of the location \mu and scale \sigma:

f(t) = \phi\left(\frac{\ln t-\mu}{\sigma}\right)\frac{1}{t\sigma}, t>0

Usage

FitLogNormal(
  data,
  eps = 1e-06,
  init = list(),
  maxit = 10,
  report = FALSE,
  sig = 0.05,
  status_name = "status",
  tau = NULL,
  time_name = "time"
)

Arguments

Value

An object of class fit containing the following:

Parameters

The estimated location \mu and scale \sigma.

Information

The observed information matrix.

Outcome

The fitted mean, median, and variance.

RMST

The estimated RMSTs, if tau was specified.

Examples

# Generate log-normal data with 20% censoring.
data <- GenData(n = 1e3, dist = "log-normal", theta = c(0, 2), p = 0.2)

# Estimate parameters.
fit <- FitParaSurv(data, dist = "log-normal")

Fit Parametric Survival Distribution

Description

Estimates parametric survival distributions using event times subject to non-informative right censoring. Available distributions include: exponential, gamma, generalized gamma, log-normal, and Weibull.

Usage

FitParaSurv(
  data,
  beta_lower = 0.1,
  beta_upper = 10,
  dist = "weibull",
  eps = 1e-06,
  init = NULL,
  maxit = 10,
  report = FALSE,
  sig = 0.05,
  status_name = "status",
  tau = NULL,
  time_name = "time"
)

Arguments

Value

An object of class fit containing the following:

Parameters

The estimated shape and rate parameters.

Information

The observed information matrix.

Outcome

The fitted mean, median, and variance.

RMST

The estimated RMSTs, if tau was specified.

See Also

• Between group comparison of survival experience CompParaSurv

• Exponential distribution FitExp

• Gamma distribution FitGamma

• Generalized gamma distribution FitGenGamma

• Log-normal distribution FitLogNormal

• Weibull distribution FitWeibull

Examples

# Generate Gamma data with 20% censoring.
data <- GenData(n = 1e3, dist = "gamma", theta = c(2, 2), p = 0.2)
# Fit gamma distribution.
fit <- FitParaSurv(data, dist = "gamma")

# Generate Weibull data with 10% censoring.
data <- GenData(n = 1e3, dist = "weibull", theta = c(2, 2), p = 0.1)
# Fit weibull distribution, calculate RMST at tau=0.5.
fit <- FitParaSurv(data, dist = "weibull", tau = 0.5)

Weibull Distribution Parameter Estimation

Description

Estimates parameters for Weibull event times subject to non-informative right censoring. The Weibull distribution is parameterized in terms of the shape \alpha and rate \lambda:

f(t) = \alpha\lambda^{\alpha}t^{\alpha-1}e^{-(\lambda t)^{\alpha}}, t>0

Usage

FitWeibull(
  data,
  init = list(),
  sig = 0.05,
  status_name = "status",
  tau = NULL,
  time_name = "time"
)

Arguments

Value

An object of class fit containing the following:

Parameters

The estimated shape \alpha and rate \lambda.

Information

The observed information matrix.

Outcome

The fitted mean, median, and variance.

RMST

The estimated RMSTs, if tau was specified.

Examples

# Generate Weibull data with 20% censoring.
data <- GenData(n = 1e3, dist = "weibull", theta = c(2, 2), p = 0.2)

# Estimate parameters.
fit <- FitParaSurv(data, dist = "weibull")

Gamma Observed Information

Description

Observed information for gamme event times without censoring.

Usage

GammaInfo(data, shape, rate)

Arguments

Value

Numeric information matrix.

Gamma Profile Score for Shape

Description

Profile score equation for gamma event times without censoring.

Usage

GammaScore(data, shape)

Arguments

Value

Numeric score.

Data Generation with Censoring

Description

Generates data from survival distributions as parameterized in this package, with optional non-informative random right censoring.

Usage

GenData(n, dist = "exp", theta = NULL, p = 0)

Arguments

Details

The parameter vector theta should contain the following elements, in order, depending on the distribution:

Exponential

Rate \lambda.

Gamma

Shape \alpha, rate \lambda.

Generalized Gamma

Shape 1 \alpha, shape 2 \beta, rate \lambda.

Log-Normal

Locaion \mu, scale \sigma.

Weibull

Shape \alpha, rate \lambda.

Value

Data.frame including the observation times and status.

Examples

# Gamma event times with shape 2 and rate 2.
# Expected censoring proportion of 20%.
data <- GenData(n = 1e3, dist = "gamma", theta = c(2, 2), p = 0.20)

# Generalized gamma event times with shapes (2,3) and rate 1.
# Expected censoring proportion of 15%.
data <- GenData(n = 1e3, dist = "gen-gamma", theta = c(2, 3, 1), p = 0.15)

# Log-normal event times with location 0 and rate 1.
# Expected censoring proportion of 10%.
data <- GenData(n = 1e3, dist = "log-normal", theta = c(0, 1), p = 0.10)

# Weibull event times with shape 2 and rate 2.
# Expected censoring proportion of 5%.
data <- GenData(n = 1e3, dist = "weibull", theta = c(2, 2), p = 0.05)

Generalized Gamma Observed Information

Description

Observed information for the generalized gamma log likelihood in the absence of censoring.

Usage

GenGammaObsInfo(data, alpha, beta, lambda)

Arguments

Value

Numeric observed information matrix.

Generalized Gamma Profile Log Likelihood

Description

Profile log likelihood of the generalized gamma distribution as a function of the second shape parameter \beta.

Usage

GenGammaProfileLogLik(data, beta)

Arguments

Value

Numeric profile log likelihood.

Generalized Gamma Rate MLE

Description

Profile MLE of the generalized gamma rate given the shape parameters.

Usage

GenGammaRate(data, alpha, beta)

Arguments

Value

Numeric MLE of the rate \lambda.

Generalized Gamma Score Equation

Description

Score equation for the generalized gamma log likelihood in the absence of censoring.

Usage

GenGammaScore(data, alpha, beta, lambda)

Arguments

Value

Numeric score vector.

Generalized Gamma Shape MLE

Description

Profile MLE of the first shape parameter \alpha of the generalized gamma given the second shape parameter \beta.

Usage

GenGammaShape(data, beta)

Arguments

Value

Numeric MLE of the rate \alpha.

Log-Normal Observed Information

Description

Observed information for log-normal event times without censoring.

Usage

LogNormInfo(data, loc, scale, log_scale = FALSE)

Arguments

Value

Numeric score.

Log-Normal Score Equation

Description

Score equation for log-normal event times without censoring.

Usage

LogNormScore(data, loc, scale)

Arguments

Value

Numeric score.

Newton Raphson Update Iteration

Description

Newton Raphson Update Iteration

Usage

NRUpdate(obj, state)

Arguments

Value

List containing the updated parameter vector 'theta' and the objective increment 'delta'.

Newton Raphson Estimation

Description

Newton Raphson Estimation

Usage

NewtonRaphson(init, obj, eps = 1e-06, maxit = 10, report = FALSE)

Arguments

Value

Numeric parameter estimate.

Restricted Mean Survival Time

Description

Calculates the RMST as the area under a fitted parametric survival distribution.

Usage

ParaRMST(fit, tau, sig = 0.05)

Arguments

Value

Data.frame containing the estimated RMST at each truncation time.

Examples

# Generate Weibull data with 20% censoring.
data <- GenData(n = 1e3, dist = "weibull", theta = c(2, 0.5), p = 0.2)

# Fit Weibull distribution.
fit <- FitParaSurv(data, dist = "weibull")

# Calculate RMSTs.
rmst <- ParaRMST(fit = fit, tau = c(0.5, 1.0, 1.5, 2.0))

# Generate gamma data with 10% censoring.
data <- GenData(n = 1e3, dist = "gamma", theta = c(2, 2), p = 0.10)

# Fit gamma distribution.
fit <- FitParaSurv(data, dist = "gamma")

# Calculate RMSTs.
rmst <- ParaRMST(fit = fit, tau = c(0.5, 1.0, 1.5, 2.0))

Permutation P Value

Description

Calculates permutation p-values for location and RMST estimates.

Usage

PermP(df1, df0, fit0, fit1, eps, init1, init0, maxit, reps, tau)

Arguments

Value

Numeric vector of permutation p-values.

Quadratic Form

Description

Quadratic Form

Usage

QF(x, A)

Arguments

Value

Numeric scalar.

Round Data Frames

Description

Round Data Frames

Usage

RoundDF(df, digits = 3)

Arguments

Value

Data.frame.

Survival Functions

Description

Constructs the survival function for a parameter distribution.

Usage

SurvFunc(dist, theta)

Arguments

Details

The parameter vector theta should contain the following elements, in order, according to the distribution:

Exponential

Rate \lambda.

Gamma

Shape \alpha, rate \lambda.

Generalized Gamma

Shape 1 \alpha, shape 2 \beta, rate \lambda.

Log-Normal

Locaion \mu, scale \sigma.

Weibull

Shape \alpha, rate \lambda.

Value

Survival function.

Examples

# Survival function for the generalized gamma.
surv <- SurvFunc(dist = "gen-gamma", theta = c(2, 2, 2))

# Evaluation.
surv(1.0)

Log Likelihood

Description

Evaluates the log-likelihood for a parametric survival distribution.

Usage

SurvLogLik(
  data,
  dist,
  theta,
  log_scale = FALSE,
  status_name = "status",
  time_name = "time"
)

Arguments

Details

The parameter vector theta should contain the following elements, in order, depending on the distribution:

Exponential

Rate \lambda.

Gamma

Shape \alpha, rate \lambda.

Generalized Gamma

Shape 1 \alpha, shape 2 \beta, rate \lambda.

Log-Normal

Location \mu, scale \sigma.

Weibull

Shape \alpha, rate \lambda.

Value

Scalar value of the log likelihood.

Examples

# Generate gamma event time data with 10% censoring.
data <- GenData(n = 1e3, dist = "gamma", theta = c(2, 2), p = 0.1)

# Evaluate log likelihood.
ll <- SurvLogLik(data, dist = "gamma", theta = c(2, 2))

# Generate Weibull event time data with 20% censoring.
data <- GenData(n = 1e3, dist = "weibull", theta = c(2, 2), p = 0.2)

# Evaluate log likelihood.
ll <- SurvLogLik(data, dist = "weibull", theta = c(2, 2))

Weibull Information Matrix.

Description

Information matrix for the Weibull shape and rate parameters.

Usage

WeiInfo(data, shape, rate)

Arguments

Value

Numeric information matrix.

Weibull Initialization.

Description

Weibull Initialization.

Usage

WeiInit(data, init)

Arguments

Value

Numeric initial value for shape.

Weibull Rate MLE

Description

Profile MLE of the Weibull rate as a function of the shape.

Usage

WeiRate(data, shape)

Arguments

Value

Numeric rate.

Weibull Profile Score for Shape

Description

Profile score equation for the Weibull shape parameter.

Usage

WeiScore(data, shape)

Arguments

Value

Numeric score.

Contrast of Survival Distributions.

Description

Defines the object class returned by the comparison function.

Slots

Dist1

Distribution fit to the target group, string.

Dist0

Distribution fit to the reference group, string.

Model1

Fitted model for the target group, fit.

Model0

Fitted model for the reference group, fit.

Location

Contrasts of means and medians, data.frame.

RMST

Contrasts of RMSTs, data.frame.

Fitted Survival Distribution

Description

Defines the object class returned by fitting functions.

Slots

Distribution

Fitted distribution, string.

Parameters

Parameters, data.frame.

Information

Information components, matrix.

Outcome

Properties of the fitted distribution, data.frame.

RMST

Estimated restricted mean survival times, data.frame

S

Fitted survival function, function.

Print Method for a Contrast of Survival Distributions.

Description

Print method for an object of class contrast.

Usage

## S3 method for class 'contrast'
print(x, ...)

Arguments

Print Method for Fitted Survival Distributions

Description

Print method for objects of class fit.

Usage

## S3 method for class 'fit'
print(x, ...)

Arguments

Quantile Function for the Weibull Distribution

Description

Quantile function for the Weibull distribution. See FitWeibull for the parameterization.

Usage

qWeibull(p, a = 1, l = 1)

Arguments

Value

Scalar quantile.

Simulation from the Gamma Distribution

Description

Generates gamma event times with shape parameter \alpha and rate parameter \lambda. See FitGamma for the parameterization. If a censoring proportion p is provided, the event times are subject to non-informative random right censoring.

Usage

rGamma(n, a = 1, l = 1, p = 0)

Arguments

Value

Data.frame including the observation times and status.

Simulation from the Generalized Gamma Distribution

Description

Generates generalized gamma event times with shape parameters (\alpha,\beta), and rate parameter \lambda. See FitGenGamma for the parameterization. If a censoring proportion p is provided, the event times are subject to non-informative random right censoring.

Usage

rGenGamma(n, a = 1, b = 1, l = 1, p = 0)

Arguments

Value

Data.frame including the observation times and status indicators.

Simulation from the Log-Normal Distribution

Description

Generates log-normal event times with location parameter \mu and scale parameter \sigma. See FitLogNormal for the parameterization. If a censoring proportion p is provided, the event times are subject to non-informative random right censoring.

Usage

rLogNormal(n, m = 0, s = 1, p = 0)

Arguments

Value

Data.frame including the observation time and status.

Simulation from the Weibull Distribution

Description

Generates Weibull event times with shape parameter \alpha and rate parameter \lambda. See FitWeibull for the parameterization. If a censoring proportion p is provided, the deviates are subject to non-informative random right censoring.

Usage

rWeibull(n, a = 1, l = 1, p = 0)

Arguments

Value

Data.frame including the observation time and status.

Show Method for a Contrast of Survival Distributions.

Description

Show Method for a Contrast of Survival Distributions.

Usage

## S4 method for signature 'contrast'
show(object)

Arguments

Show Method for Fitted Survival Distributions

Description

Show Method for Fitted Survival Distributions

Usage

## S4 method for signature 'fit'
show(object)

Arguments