wlr: Weighted logrank test

View source: R/wlr.R

wlrR Documentation

Weighted logrank test

Description

Weighted logrank test

Usage

wlr(data, weight, return_variance = FALSE, ratio = NULL, formula = NULL)

## Default S3 method:
wlr(data, weight, return_variance = FALSE, ratio = NULL, formula = NULL)

## S3 method for class 'tte_data'
wlr(data, weight, return_variance = FALSE, ratio = NULL, formula = NULL)

## S3 method for class 'counting_process'
wlr(data, weight, return_variance = FALSE, ratio = NULL, formula = NULL)

Arguments

data

Dataset (generated by sim_pw_surv()) that has been cut by counting_process(), cut_data_by_date(), or cut_data_by_event().

weight

Weighting functions, such as fh(), mb(), and early_zero().

return_variance

A logical flag that, if TRUE, adds columns estimated variance for weighted sum of observed minus expected; see details; Default: FALSE.

ratio

randomization ratio (experimental:control).

  • If the data is generated by simtrial, such as

    • data = sim_pw_surv(...) |> cut_data_by_date(...)

    • data = sim_pw_surv(...) |> cut_data_by_event(...)

    • data = sim_pw_surv(...) |> cut_data_by_date(...) |> counting_process(...)

    • data = sim_pw_surv(...) |> cut_data_by_event(...) |> counting_process(...) there is no need to input the ratio, as simtrial gets the ratio via the block arguments in sim_pw_surv().

  • If the data is a custom dataset (see Example 2) below,

    • Users are suggested to input the planned randomization ratio to ratio;

    • If not, simtrial takes the empirical randomization ratio.

formula

A formula to specify the columns that contain the time-to-event, event, treatment, and stratum variables. Only used by the default S3 method because the other classes aleady have the required column names. For stratified designs, the formula should have the form Surv(tte, event) ~ treatment + strata(stratum), where tte, event, treatment, and stratum are the column names from data with the time-to-event measurement, event status, treatment group, and stratum, respectively. For unstratified designs, the formula can omit the stratum column: Surv(tte, event) ~ treatment.

Details

  • z - Standardized normal Fleming-Harrington weighted logrank test.

  • i - Stratum index.

  • d_i - Number of distinct times at which events occurred in stratum i.

  • t_{ij} - Ordered times at which events in stratum i, j = 1, 2, \ldots, d_i were observed; for each observation, t_{ij} represents the time post study entry.

  • O_{ij.} - Total number of events in stratum i that occurred at time t_{ij}.

  • O_{ije} - Total number of events in stratum i in the experimental treatment group that occurred at time t_{ij}.

  • N_{ij.} - Total number of study subjects in stratum i who were followed for at least duration.

  • E_{ije} - Expected observations in experimental treatment group given random selection of O_{ij.} from those in stratum i at risk at time t_{ij}.

  • V_{ije} - Hypergeometric variance for E_{ije} as produced in Var from counting_process().

  • N_{ije} - Total number of study subjects in stratum i in the experimental treatment group who were followed for at least duration t_{ij}.

  • E_{ije} - Expected observations in experimental group in stratum i at time t_{ij} conditioning on the overall number of events and at risk populations at that time and sampling at risk observations without replacement:

    E_{ije} = O_{ij.} N_{ije}/N_{ij.}

  • S_{ij} - Kaplan-Meier estimate of survival in combined treatment groups immediately prior to time t_{ij}.

  • \rho, \gamma - Real parameters for Fleming-Harrington test.

  • X_i - Numerator for signed logrank test in stratum i

    X_i = \sum_{j=1}^{d_{i}} S_{ij}^\rho(1-S_{ij}^\gamma)(O_{ije}-E_{ije})

  • V_{ij} - Variance used in denominator for Fleming-Harrington weighted logrank tests

    V_i = \sum_{j=1}^{d_{i}} (S_{ij}^\rho(1-S_{ij}^\gamma))^2V_{ij})

    The stratified Fleming-Harrington weighted logrank test is then computed as:

    z = \sum_i X_i/\sqrt{\sum_i V_i}.

Value

A list containing the test method (method), parameters of this test method (parameter), point estimate of the treatment effect (estimate), standardized error of the treatment effect (se), Z-score (z), p-values (p_value).

Examples

# ---------------------- #
#      Example 1         #
#  Use dataset generated #
#     by simtrial        #
# ---------------------- #
x <- sim_pw_surv(n = 200) |> cut_data_by_event(100)

# Example 1A: WLR test with FH wights
x |> wlr(weight = fh(rho = 0, gamma = 0.5))
x |> wlr(weight = fh(rho = 0, gamma = 0.5), return_variance = TRUE)

# Example 1B: WLR test with MB wights
x |> wlr(weight = mb(delay = 4, w_max = 2))

# Example 1C: WLR test with early zero wights
x |> wlr(weight = early_zero(early_period = 4))

# Example 1D
# For increased computational speed when running many WLR tests, you can
# pre-compute the counting_process() step first, and then pass the result of
# counting_process() directly to wlr()
x <- x |> counting_process(arm = "experimental")
x |> wlr(weight = fh(rho = 0, gamma = 1))
x |> wlr(weight = mb(delay = 4, w_max = 2))
x |> wlr(weight = early_zero(early_period = 4))

# ---------------------- #
#      Example 2         #
#  Use cumsum dataset    #
# ---------------------- #
x <- data.frame(treatment = ifelse(ex1_delayed_effect$trt == 1, "experimental", "control"),
                stratum = rep("All", nrow(ex1_delayed_effect)),
                tte = ex1_delayed_effect$month,
                event = ex1_delayed_effect$evntd)

# Users can specify the randomization ratio to calculate the statistical information under H0
x |> wlr(weight = fh(rho = 0, gamma = 0.5), ratio = 2)

x |>
  counting_process(arm = "experimental") |>
  wlr(weight = fh(rho = 0, gamma = 0.5), ratio = 2)

# If users don't provide the randomization ratio, we will calculate the emperical ratio
x |> wlr(weight = fh(rho = 0, gamma = 0.5))

x |>
  counting_process(arm = "experimental") |>
  wlr(weight = fh(rho = 0, gamma = 0.5))

# ---------------------- #
#      Example 3         #
#  Use formula           #
# ---------------------- #
library("survival")

# Unstratified design
x <- sim_pw_surv(n = 200) |> cut_data_by_event(100) |> as.data.frame()
colnames(x) <- c("tte", "evnt", "strtm", "trtmnt")
wlr(x, weight = fh(0, 0.5), formula = Surv(tte, evnt) ~ trtmnt)

# Stratified design
x$strtm <- sample(c("s1", "s2"), size = nrow(x), replace = TRUE)
wlr(x, weight = fh(0, 0.5), formula = Surv(tte, evnt) ~ trtmnt + strata(strtm))

simtrial documentation built on June 12, 2025, 1:07 a.m.