Help for package survAH

Type:

Package

Title:

Survival Data Analysis using Average Hazard

Version:

1.2.0

Date:

2025-12-01

Description:

Performs two-sample comparisons based on average hazard with survival weight (AHSW) or general censoring-free incidence rate (CFIR) proposed by Uno and Horiguchi (2023) <doi:10.1002/sim.9651>.

License:

GPL-2

Depends:

survival, R (≥ 2.10)

Encoding:

UTF-8

LazyData:

true

RoxygenNote:

7.3.3

Suggests:

knitr, rmarkdown

VignetteBuilder:

knitr

NeedsCompilation:

Packaged:

2025-12-04 12:34:53 UTC; miki

Author:

Hajime Uno

[aut], Miki Horiguchi

[aut, cre], Zihan Qian

[aut]

Maintainer:

Miki Horiguchi <horiguchimiki@gmail.com>

Repository:

CRAN

Date/Publication:

2025-12-04 12:50:02 UTC

Survival Data Analysis using Average Hazard

Description

The survAH package performs two-sample comparisons based on average hazard with survival weight (AHSW) or general censoring-free incidence rate (CFIR) proposed by Uno and Horiguchi (2023) <doi:10.1002/sim.9651>.

Author(s)

Hajime Uno, Miki Horiguchi, Zihan Qian

References

Uno H and Horiguchi M. Ratio and difference of average hazard with survival weight: new measures to quantify survival benefit of new therapy. Statistics in Medicine. 2023; 42(7):936-952. <doi:10.1002/sim.9651> Uno H, Tian L, Horiguchi M, Hattori S, Kehl KL. Regression models for average hazard. Biometrics. 2024; 80(2):ujae037. <doi: 10.1093/biomtc/ujae037> Horiguchi M, Tian L, Kehl KL, Uno H. Assessing delayed treatment benefits of immunotherapy using long-term average hazard: a novel test/estimation approach. Lifetime Data Anal. 2025; 31(4):784-809. <doi:10.1007/s10985-025-09671-0> Qian Z, Tian L, Horiguchi M, Uno H. A novel stratified analysis method for testing and estimating overall treatment effects on time-to-event outcomes using average hazard with survival weight. Stat Med. 2025; 44(7):e70056. <doi:10.1002/sim.70056>

Average Hazard (one sample)

Description

Calculates the average hazard with survival weight and the corresponding asymptotic confidence interval for a single sample.

Usage

ah1(time, status, tau, conf.int=0.95)

Arguments

time

A numeric vector of follow-up times for right-censored data.

status

A numeric vector indicating the event status; 1 = event occurred, 0 = right censored.

tau

A scalar specifying the end time point (tau) for calculating the average hazard. If tau = NULL, the default is the maximum time point at which the risk set size in both groups is at least 10.

conf.int

A numeric value specifying the confidence level for confidence intervals. The default is 0.95.

Details

It also provides the log-transformed t-year event rate and restricted mean survival time (RMST) along with their variances as intermediate products. Note that the confidence intervals for the t-year event rate and RMST are based on log-scale values. As a result, the confidence intervals may differ slightly from those generated by the surv2sampleComp or survRM2 packages.

Value

An object of class ah1, which contains the following components:

need_stop

Logical indicator. If TRUE, specify another tau. The survival probability at the specified tau needs to be > 0.

tau

The truncation time point used in the analysis.

result1

Estimated average hazard.

Author(s)

Hajime Uno, Miki Horiguchi

References

Uno H and Horiguchi M. Ratio and difference of average hazard with survival weight: new measures to quantify survival benefit of new therapy. Statistics in Medicine. 2023;1-17. <doi:10.1002/sim.9651>

Examples

#====================================================================
# cm214_pfs: The sample reconstructed data of the CheckMate214 study.
# The code below reproduces the results reported by
# Uno and Horiguchi (StatMed; 2023) in Table 6.
#====================================================================
D      = cm214_pfs
time   = D$time
status = D$status
tau    = 21

b = ah1(time=time, status=status, tau=tau, conf.int=0.95)
print(b)

Two-Sample Comparison of Average Hazard

Description

The ah2 function performs two-sample comparisons using the average hazard (AH) as a summary measure of the survival time distribution. Two kinds of between-group contrast metrics, the ratio of AH (RAH) and the difference in AH (DAH), are calculated.

Usage

ah2(time, status, arm, tau=NULL, conf.int=0.95, eta=0, strata=NULL)

Arguments

time

A numeric vector of follow-up times for right-censored data.

status

A numeric vector indicating the event status; 1 = event occurred, 0 = right censored.

arm

A binary vector indicating group assignment; elements should be either 0 or 1. Typically, 0 = control group and 1 = treatment group.

tau

A scalar specifying the end time point (tau) for calculating the average hazard. If tau = NULL, the default is the maximum time point at which the risk set size in both groups is at least 10.

conf.int

A numeric value specifying the confidence level for confidence intervals. The default is 0.95.

eta

A scalar specifying the start time point (eta) for calculating the average hazard over the time window [eta, tau]. The default is 0.

strata

An optional numeric vector specifying a stratification factor for stratified analysis. If strata = NULL (default), an unstratified analysis is performed.

Details

The function provides the AH for each of the two groups, the absolute difference and the absolute ratio of AH (DAH and RAH) between the two groups, and the corresponding confidence intervals. It also calculates p-values for the two-sided tests based on the RAH and DAH.

Value

An object of class ah2, which contains the following components:

note

A note indicating the time window used in the analysis, specified as [eta, tau].

n.obs

A summary of the number of observations, including the total number, number of events by tau, number of censored observations by tau, and the size of the risk set at tau.

ah

Estimated average hazard in each arm.

rah

Ratio of average hazards (RAH), calculated as treatment over control.

dah

Difference of average hazards (DAH), calculated as treatment minus control.

conventional_rah

Ratio of average hazards based on the conventional stratified analysis method.

conventional_dah

Difference of average hazards based on the conventional stratified analysis method.

stratified_ah

Estimated average hazard by arm based on the proposed stratified analysis method.

stratified_rah

Ratio of average hazards based on the proposed stratified analysis method.

stratified_dah

Difference of average hazards based on the proposed stratified analysis method.

Author(s)

Hajime Uno, Miki Horiguchi, Zihan Qian

References

Uno H and Horiguchi M. Ratio and difference of average hazard with survival weight: new measures to quantify survival benefit of new therapy. Statistics in Medicine. 2023; 42(7):936-952. <doi:10.1002/sim.9651> Horiguchi M, Tian L, Kehl KL, Uno H. Assessing delayed treatment benefits of immunotherapy using long-term average hazard: a novel test/estimation approach. Lifetime Data Anal. 2025; 31(4):784-809. <doi:10.1007/s10985-025-09671-0> Qian Z, Tian L, Horiguchi M, Uno H. A novel stratified analysis method for testing and estimating overall treatment effects on time-to-event outcomes using average hazard with survival weight. Stat Med. 2025; 44(7):e70056. <doi:10.1002/sim.70056>

Examples

#====================================================================
# cm214_pfs: The sample reconstructed data of the CheckMate214 study.
#====================================================================
# The code below reproduces the results reported by
# Uno H and Horiguchi M (StatMed; 2023) in Table 6.
D      = cm214_pfs
time   = D$time
status = D$status
arm    = D$arm
tau    = 21

a = ah2(time=time, status=status, arm=arm, tau=tau, conf.int=0.95, eta=0)
print(a, digits=3)


# The code below reproduces the results reported by
# Horiguchi M, Tian L, Kehl K.L, Uno H (arXiv; 2024) in Table 3.
b = ah2(time=time, status=status, arm=arm, tau=21, conf.int=0.95, eta=7)
print(b, digits=3)


#====================================================================
# Stratified analysis example
#====================================================================
D      = myeloid
time   = D$futime/365.25
status = D$death
arm    = as.numeric(D$trt=="A")
tau    = 3
strata = as.numeric(D$flt3)

b = ah2(time=time, status=status, arm=arm, strata=strata, tau=tau)
print(b, digits=3)

Regression Analysis with Average Hazard

Description

The ahreg function performs a regression analysis for the average hazard (AH).

Usage

ahreg(formula, tau, data, link="log", conf.int=0.95, 
             cens_strata=NULL, cens_covs=NULL)

Arguments

formula

A formula object, with the response on the left of a ~ operator, and the terms on the right. The response must be a survival object as returned by the Surv function. For a multi-state model the formula may be a list of formulas.

tau

A scalar value to specify a time point for calculating the average hazard.

data

A data.frame in which to interpret the variables named in the formula.

link

A link function to be used, either "log" (default) or "identity".

conf.int

A confidence coefficient for calculating confidence intervals. The default is conf.int=0.95.

cens_strata

A variable name for specifying group-specific censoring. Only one of cens_strata or cens_cov can be specified. The default is NULL.

cens_covs

A set of variable names used for modeling censoring time distribution. Only one of cens_strata or cens_covs can be specified. The default is NULL.

Details

The function implements the average hazard regression.

Value

an object of class ahreg.

result

A table containing the coefficient estimates, standard errors, confidence intervals, z-values, and two-sided p-values for each predicotor.

Author(s)

Hajime Uno, Miki Horiguchi

References

#' Uno H, Tian L, Horiguchi M, Hattori S, Kehl KL. Regression models for average hazard. Biometrics. 2024; 80(2):ujae037. <doi: 10.1093/biomtc/ujae037>

Examples

#================================================================================
# ahreg.sample.data: Sample data from the pbc data in the survival package
#================================================================================
D = ahreg.sample.data()


#-- Independent censoring
a1 = ahreg(Surv(time,status) ~ arm + edema + bili, tau=7, data=D)
print(a1)

#-- Group specific censoring
a2 = ahreg(Surv(time,status) ~ arm + edema + bili, tau=7, data=D, cens_strata="arm")
print(a2)

#-- Covariate dependent censoring via Cox 
a3 = ahreg(Surv(time,status) ~ arm + edema + bili, tau=7, data=D, cens_covs=c("arm","edema"))
print(a3)

#-- Covariate dependent censoring via Cox (identity link)
a4 = ahreg(Surv(time,status) ~ arm + edema + bili, tau=7, data=D, cens_covs=c("arm","edema"), 
           link="identity")
print(a4)

Generate a sample data from the pbc data

Description

This is a function to retrieve 312 randomized patients from the pbc data.

Usage

ahreg.sample.data(t.unit="year")

Arguments

t.unit

Specify the time unit. It supports "year" (default), "month", and "day".

Details

The function creates a sample dataset to illustrate the usage of the function ahreg() in this package. The original pbc data in survival package consists of 418 patients data. This function loads the pbc data, select the 312 patients who were randomized. The status variable is edited, so that 1 indicates death and 0 indicates alive.

Value

returns a data frame

Examples

D=ahreg.sample.data()
head(D)

Sample Reconstructed Data of CheckMate214 Study

Description

The progression-free survival data reconstructed from the publication of the CheckMate214 study.

Usage

data(cm214_pfs)

Format

A dataset containing 3 columns:

time: the time-to-event variable (the time unit is month)
status: the event indicator (1=event, 0=censor)
arm: the treatment indicator (1=treatment, 0=control)

Details

This is a reconstructed patient-level data from the results reported by Motzer et al.(2018) <doi:10.1056/NEJMoa1712126>. The data consists of 847 patients with previously untreated clear-cell advanced renal-cell carcinoma; 425 for the nivolumab plus ipilimumab group (treatment) and 422 for the sunitinib group (control).

Source

Motzer RJ, Tannir NM, McDermott DF, et al. Nivolumab plus ipilimumab versus sunitinib in advanced renal-cell carcinoma. New England Journal of Medicine. 2018;378(14):1277–1290. <doi:10.1056/NEJMoa1712126> Guyot P, Ades AE, Ouwens MJ, Welton NJ. Enhanced secondary analysis of survival data: reconstructing the data from published Kaplan-Meier survival curves. BMC Med Res Methodol. 2012;12(1):9. <doi:10.1186/1471-2288-12-9>

print.ah2

Description

S3 method for class 'ah2'

Usage

## S3 method for class 'ah2'
print(x, digits=3, ...)

Arguments

x

Object to be printed.

digits

Integer indicating the number of decimal places.

...

Further arguments ignored in this function.

Value

returns summary output for class 'ah2'

print.ahreg

Description

S3 method for class 'ahreg'

Usage

## S3 method for class 'ahreg'
print(x, digits=5, ...)

Arguments

x

Object to be printed.

digits

Integer indicating the number of decimal places.

...

Further arguments ignored in this function.

Value

returns summary output for class 'ahreg'

Survival Data Analysis using Average Hazard

Description

Author(s)

References

See Also

Average Hazard (one sample)

Description

Usage

Arguments

Details

Value

Author(s)

References

Examples

Two-Sample Comparison of Average Hazard

Description

Usage

Arguments

Details

Value

Author(s)

References

Examples

Regression Analysis with Average Hazard

Description

Usage

Arguments

Details

Value

Author(s)

References

Examples

Generate a sample data from the pbc data

Description

Usage

Arguments

Details

Value

See Also

Examples

Sample Reconstructed Data of CheckMate214 Study

Description

Usage

Format

Details

Source

print.ah2

Description

Usage

Arguments

Value

print.ahreg

Description

Usage

Arguments

Value