Function to apply a given calendar time as effective censoring time.

Description

Applies administrative censoring at a specified calendar time by truncating each subject's observed event history. For subjects who are still under observation at the calendar cutoff, a censoring record is added at the specified calendar time.

Usage

Apply.calendar.censoring(data, calendar)

Arguments

Value

A data frame in long format containing the censored composite endpoint data. Each subject contributes all events occurring on or before the specified calendar time, with an additional censoring record added for subjects who have not experienced a terminal event by that time.

Examples

df <- Onesample.generate.sequential(size = 200, recruitment = 3,
calendar = 5, random.censor.rate = 0.05, seed = 1123)
df2 <- Apply.calendar.censoring(data = df, calendar = 4)

Function to apply a given calendar time as effective censoring time for two-sample composite endpoint data.

Description

Applies administrative censoring at a specified calendar time by truncating each subject’s observed event history; for subjects still under observation at the calendar cutoff, a censoring record is added at the cutoff time.

Usage

Apply.calendar.censoring.2(data, calendar)

Arguments

Value

A data frame in long format containing the censored composite endpoint data. Each subject contributes all events occurring on or before the specified calendar time, with an additional censoring record added for subjects who have not experienced a terminal event by that time.

Examples

df <- TwoSample.generate.sequential(sizevec = c(100, 100), beta.trt = 0.8,
calendar = 5, recruitment = 3,
random.censor.rate = 0.05, seed = 2026)
df2 <- Apply.calendar.censoring.2(data= df, calendar = 3.9)

O'Brien-Flemming error spending function.

Description

Computes the cumulative Type I error spending function corresponding to the two-sided O'Brien-Flemming group sequential design.

Usage

OBF(t, alpha = 0.05)

Arguments

Value

A numeric vector giving the cumulative type I error spent at each information fraction t under the O'Brien-Flemming spending function.

References

Jennison, C. and Turnbull, B. W. (2000). Group Sequential Methods with Applications to Clinical Trials. Chapman and Hall/CRC.

Examples

# Two-interim analyses at 50% and 75% maximum information and a final analysis
OBF(t = c(0.5, 0.7, 1))

Function to estimate the one-sample mean frequency under a group sequential design.

Description

Computes the nonparametric one-sample estimator of the mean frequency function for composite endpoints consisting of recurrent events and terminal event (death), using data observed up to a given calendar time. The estimator is constructed on the event-time scale (time since subject enrollment).

Usage

OneSample.Estimator.sequential(data, t = NULL)

Arguments

Value

If t is provided, returns a list containing:

• muhat: Estimated mean frequency function evaluated at t.

• varhat: Estimated variance of muhat at t.

• n: Sample size of the input dataset.

If t is NULL, returns a numeric vector xihat giving the estimated cumulative variance component evaluated at all ordered observed event time. This quantity is not the mean frequency estimator itself. @importFrom dplyr group_by filter mutate count select slice ungroup @importFrom tibble as_tibble @importFrom bdsmatrix bdsBlock @importFrom rlang .data

Examples

df <- Onesample.generate.sequential(size = 400, recruitment = 3,
calendar = 5, random.censor.rate = 0.05, seed = 1123)
OneSample.Estimator.sequential(data= df, t = c(1.5, 2.9, 4.6))

Function to simulate one-sample composite endpoint data under staggered entry.

Description

Simulate one-sample composite endpoints data with recurrent events and a terminal event under two time scales: event time t and calendar time s. A uniform recruitment period is assumed, and the function returns all observed data available at a specified calendar time. Recurrent event occurrences are generated from an underlying Poisson process with subject-specific Gamma frailty.

Usage

Onesample.generate.sequential(
  beta = c(0, 0),
  lambda_0 = 1.15,
  size,
  recruitment = 3,
  calendar = 5,
  random.censor.rate,
  seed
)

Arguments

Value

A data frame in long format containing simulated composite endpoint data. Each subject may contributing multiple rows corresponding to recurrent events, a terminal event (death), or censoring. The data include:

• id: Subject identifier.

• e: Enrollment time on the calendar scale.

• event_time_cal: Cumulative event time on the calendar scale.

• status: Event indicator with values 2=recurrent event, 1=death, and 0=censoring.

• Z1, Z2: Simulated covariates used in the proportional mean model.

• tau_star: Subject-specific stopping time, the last event observed in [0, tau_star] is classified as death.

• death: Binary indicator for death.

• recurrent: Binary indicator for recurrent events.

• event: Binary event indicator, event = death + recurrent.

• calendar: Calendar time cutoff used to generate the returned data.

• lambda_0: Baseline Poisson process rate parameter.

• lambda_star: Rate parameter of an exponential distribution in generating tau_star.

• gamma_scale, gamma_shape: Parameters of the Gamma distribution used to generate subject-specific frailty terms.

References

Mao L, Lin DY. Semiparametric regression for the weighted composite endpoint of recurrent and terminal events. Biostatistics. 2016 Apr; 17(2) :390-403.

Examples

# Generate one-sample composite endpoint data
df <- Onesample.generate.sequential(size = 200,
recruitment = 3, calendar = 5,
random.censor.rate = 0.05, seed = 1123)

Function to solve for the treatment effect parameter to achieve target power by Monte Carlo simulation.

Description

For each design scenario in params, this function solves for the treatment effect coefficient beta.trt that achieves the desired power using an iterative Monte Carlo calibration procedure. For scenarios labeled TypeI, the function sets beta.trt = 0. For scenarios labeled Power, it repeatedly simulates two-sample composites data, estimates calibration quantities (a power constant and variance) using either the generalized log-rank ("LR") or generalized-t ("GT") approach, updtaes beta.trt using find.beta.trt(), and iterates until convergence within tol.

Usage

Solve.beta.given.power(
  nsim = 1000,
  params,
  estimator,
  tol = 0.001,
  seed = NULL
)

Arguments

Value

A data.frame with the same rows as params and an additional column beta.trt containing the solved treatment effect coefficient. For Type == "TypeI", beta.trt is set to 0. For Type == "Power", beta.trt is the converged solution from the Monte Carlo calibration procedure.

Function to calculate the true value of the mean frequency function.

Description

Computes the theoretical mean frequency function for the composite endpoint under the assumed data-generating mechanisim. The calculation uses the parameters stored in the simulated data.

Usage

True.mu(data, t)

Arguments

Value

A numeric vector giving the true mean frequency evaluated at t.

References

Mao L, Lin DY. Semiparametric regression for the weighted composite endpoint of recurrent and terminal events. Biostatistics. 2016 Apr; 17(2) :390-403.

Examples

df <- Onesample.generate.sequential(size = 200, recruitment = 3, calendar = 5,
random.censor.rate = 0.05, seed = 1123)
True.mu(data = df, t = c(1.5, 2.9, 4.6))

Function to calculate the sequential rejection boundaries for the time-to-first-event (TTFE) method.

Description

Constructs two-sided group sequential critical boundaries for the two-sample TTFE log-rank Z-statistics at prespecified calendar times. The function converts stage-wise variance estimates into information fractions, allocates incremental Type I error using a spending function, and solves for the corresponding multivariate normal critical values under the canonical joint distribution assumption. It also returns stage-wise rejection indicators (with early stopping enforced).

Usage

TwoSample.Boundary.TTFE(result, spend, calendars, alpha, planned.n, Iunit)

Arguments

Value

A list containing:

• Z.stats: Stage-wise TTFE Z-statistics.

• vars: Stage-wise variance estimates.

• raw.information: Stage-wise information fractions.

• TTFE.bdry: Two-sided critical boundaries at each analysis stage.

• TTFE.reject: Stage-wise rejection indicators (1 = reject at that stage, 0 otherwise), with later stages set to 0 after the first rejection.

• nu: Stage-wise information fractions after handling edge cases (e.g., reaching 100% information early).

• pi: Incremental Type I error allocated to each stage.

• total.ns: Total sample size contributing at each analysis stage (copied from result).

Function to compute calibration constants for the two-sample generalized-t statistics.

Description

Computes two quantities used for power/effect-size calibration of the two-sample generalized-t statistics. The function evaluates the generalized-t statistics up to a fixed event-time horizon tau = 3, then returns (i) an integral \int_0^{\tau} K_{LR}(t)\, d\mu_1(t) based on the control group mean-frequency increment and (ii) the asymptotic variance of the integrated statistic.

Usage

TwoSample.Constant.GT(data)

Arguments

Value

• The calibration constant power.const. Defined as the integral of the generalized-t's weight function times the control group's mean frequency increment over [0,3].

• The estimated asymptotic variance of the integrated two-sample generalized-t statistics over [0,3].

Function to compute calibration constants for the two-sample generalized log-rank statistics.

Description

Computes two quantities used for power/effect-size calibration of the two-sample generalized log-rank statistics. The function evaluates the generalized log-rank statistics up to a fixed event-time horizon tau = 3, then returns (i) an integral \int_0^{\tau} K_{LR}(t)\, d\mu_1(t) based on the control group mean-frequency increment and (ii) the asymptotic variance of the integrated statistic.

Usage

TwoSample.Constant.LR(data)

Arguments

Value

A numeric vector of length 2:

• The calibration constant power.const. Defined as the integral of the generalized log-rank statistics' weight function times the control group's mean frequency increment over [0,3].

• The estimated asymptotic variance of the integrated two-sample generalized log-rank statistics over [0,3].

Function to calculate the two-sample generalized-t statistic for composite endpoint under sequential monitoring.

Description

Computes a two-sample generalized t-test statistic for composite endpoints consisting of recurrent events and a terminal event, using data observed up to a given calendar time. Event times are converted from the calendar-time scale to the event-time scale (time since enrollment).

Usage

TwoSample.Estimator.GT.sequential(data, tau = 3)

Arguments

Value

A list with components:

• Q: Value of the generalized t-test statistics integrated over [0, tau].

• var: Estimated asymptotic variance of Q.

• const: Scaling constant used in the variance estimation.

Examples

# Two-sample generalized-t statistic: null hypothesis
df <- TwoSample.generate.sequential(sizevec = c(200, 200),
beta.trt = 0, calendar = 5, recruitment = 3,
random.censor.rate = 0.05, seed = 2026)
TwoSample.Estimator.GT.sequential(data = df, tau = 3)
# Two-sample generalized-t statistic: alternative hypothesis
df2 <- TwoSample.generate.sequential(sizevec = c(200, 200),
beta.trt = 0.8, calendar = 5, recruitment = 3,
random.censor.rate = 0.05, seed = 2026)
TwoSample.Estimator.GT.sequential(data = df2, tau = 3)

Function to calculate the two-sample generalized log-rank statistic for composite endpoint under sequential monitoring.

Description

Computes a two-sample generalized log-rank test statistic for composite endpoints consisting of recurrent events and a terminal event, using data observed up to a given calendar time. Event times are converted from the calendar-time scale to the event-time scale (time since enrollment). The statistics integrates the difference between estimated mean frequency increments across groups with a risk-set based weight function.

Usage

TwoSample.Estimator.LR.sequential(data, tau = 3)

Arguments

Value

A list with components:

• Q: Value of the generalized log-rank statistics integrated over [0, tau].

• var: Estimated asymptotic variance of Q.

• const: Scaling constant used in the variance estimation.

Examples

# Two-sample generalized log-rank test: null hypothesis
df <- TwoSample.generate.sequential(sizevec = c(200, 200),
beta.trt = 0, calendar = 5, recruitment = 3,
random.censor.rate = 0.05, seed = 2026)
TwoSample.Estimator.LR.sequential(data = df, tau = 3)
# Two-sample generalized log-rank test: alternative hypothesis
df2 <- TwoSample.generate.sequential(sizevec = c(200, 200),
beta.trt = 0.8, calendar = 5, recruitment = 3,
random.censor.rate = 0.05, seed = 2026)
TwoSample.Estimator.LR.sequential(data = df2, tau = 3)

Function to calculate the Z statistics and variance for the time-to-first-event (TTFE) method.

Description

Computes a two-sample TTFE test statistics by retaining only the first observed event for each subject and applying a standard log-rank test. This function is intended as a comparator or benchmark to the mean-frequency based estimator implemented elsewhere in the package.

Usage

TwoSample.Estimator.TTFE.sequential(data)

Arguments

Value

A list with:

• Z.stat: The ordinary log-rank statistics on the Z-scale, defined as the square root of the chi-square statistic from survdiff().

• var: The estimated variance of the test statistic. extracted from the log-rank test variance matrix.

Function to calculate stage-wise test statistics, variances, and correlation for two-sample generalized-t statistics.

Description

Computes the stage-wise generalized-t statistics and their variance estimates at a set of interim analysis calendar times. At each analysis, administrative censoring is applied at the specified calendar time, event times are converted from the calendar-time scale to the event-time scale (time since enrollment), and the generalized-t statistics is evaluated over [0, tau]. When multiple analysis are requested, the function also estimates the correlation matrix of the stage-wise statistics.

Usage

TwoSample.Q.Cov.Estimator.Sequential.GT(data, tau = 3, calendars)

Arguments

Value

A list containing stage-wise estimates. If length(calendars) > 1, the returned list includes:

• Qs: Numeric vector of stage-wise generalized-t statistics evaluated at each calendar time in calendars.

• vars: Numeric vector of estimated variances corresponding to Qs.

• total.ns: Numeric vector giving the total enrolled sample size contributing data at each calendar time.

• corr.matrix: Estimated correlation matrix of the stage-wise statistics.

• nss: List of length length(calendars) giving the group-specific sample sizes at each analysis.

If length(calendars) == 1, the list contains Qs, vars, and total.ns.

Examples

df <- TwoSample.generate.sequential(sizevec = c(200, 200), beta.trt = 0,
calendar = 5, recruitment = 3, random.censor.rate = 0.05, seed = 2026)
TwoSample.Q.Cov.Estimator.Sequential.GT(data = df, calendars = c(2.5, 3.5, 4.5))

Function to calculate stage-wise test statistics, variances, and correlation for two-sample generalized log-rank statistics.

Description

Computes the stage-wise generalized log-rank statistics and their variance estimates at a set of interim analysis calendar times. At each analysis, administrative censoring is applied at the specified calendar time, event times are converted from the calendar-time scale to the event-time scale (time since enrollment), and the generalized log-rank statistics is evaluated over [0, tau]. When multiple analysis are requested, the function also estimates the correlation matrix of the stage-wise statistics.

Usage

TwoSample.Q.Cov.Estimator.Sequential.LR(data, tau = 3, calendars)

Arguments

Value

A list containing stage-wise estimates. If length(calendars) > 1, the returned list includes:

• Qs: Numeric vector of stage-wise generalized log-rank statistics evaluated at each calendar time in calendars.

• vars: Numeric vector of estimated variances corresponding to Qs.

• total.ns: Numeric vector giving the total enrolled sample size contributing data at each calendar time.

• corr.matrix: Estimated correlation matrix of the stage-wise statistics.

• nss: List of length length(calendars) giving the group-specific sample sizes at each analysis.

If length(calendars) == 1, the list contains Qs, vars, and total.ns.

Examples

df <- TwoSample.generate.sequential(sizevec = c(200, 200), beta.trt = 0,
calendar = 5, recruitment = 3, random.censor.rate = 0.05, seed = 2026)
TwoSample.Q.Cov.Estimator.Sequential.LR(data = df, calendars = c(2.5, 3.5, 4.5))

Function to calculate the Wald statistics and group sequential boundaries for two-sample monitoring.

Description

Computes stage-wise Wald statistics from estimated two-sample statistics and their variances, determines information fractions, allocates Type I error using a user specified spending function, and constructs corresponding two-sided rejection boundaries. The function supports both a consistent correlation approach (supplied in Q.cov.est) and a canonical correlation approach based on information fractions.

Usage

TwoSample.Wald.and.Boundary(
  Q.cov.est,
  spend,
  calendars,
  alpha,
  planned.n,
  Iunit
)

Arguments

Value

A list with components:

• Qs: Stage-wise test statistics.

• vars: Stage-wise variance estimates for Qs.

• raw.information: Information fractions prior to any adjustments for early completion or skipped analysis.

• Wald: Stage-wise Wald statistics Qs/sqrt(vars).

• consistent.bdry: Two-sided rejection boundaries computed using the consistent correlation matrix.

• canonical.bdry: Two-sided rejection boundaries computed using the canonical correlation matrix.

• consistent.reject: Indicator vector for boundary crossing under the consistent approach (only the the first crossing is retained).

• canonical.reject: Indicator vector for boundary crossing under the canonical approach (only the the first crossing is retained).

• nu: Final information fractions used for boundary construction.

• pi: Incremental Type I error allocated to each analysis.

• total.ns: Total accrued sample size at each analysis.

Function to calculate the two-sample time-to-first-event (TTFE) statistics and variances across multiple calendar times.

Description

Computes sequential Z-statistics and their corresponding variance estimates for a two-sample time-to-first-event (TTFE) analysis at a set of prespecified calendar analysis times. At each calendar time, administrative censoring is applied, event times are converted from the calendar scale to the event-time scale, and a standard log-rank test is performed using only the first observed event per subject.

Usage

TwoSample.Z.Var.Estimator.Sequential.TTFE(data, tau = NULL, calendars)

Arguments

Value

A list with components:

• Z.stats: A numeric vector of log-rank Z-statistics evaluated at each calendar analysis time.

• vars: A numeric vector of estimated variances of the Z-statistics at each analysis time.

• total.ns: A numeric vector giving the total number of subjects contributing data at each calendar analysis time.

Function to simulate two-sample composite endpoint data under staggered entry.

Description

Simulate two-sample composite endpoints data with recurrent events and a terminal event under two time scales: event time t and calendar time s. A uniform recruitment period is assumed, and the function returns all observed data available at a specified calendar time. Recurrent event occurrences are generated from an underlying Poisson process with subject-specific Gamma frailty.

Usage

TwoSample.generate.sequential(
  lambda_0vec = c(1.15, 1.15),
  sizevec,
  beta.trt,
  calendar = 5,
  recruitment = 3,
  random.censor.rate,
  seed
)

Arguments

Value

A data frame in long format containing simulated composite endpoint data. Each subject may contributing multiple rows corresponding to recurrent events, a terminal event (death), or censoring. The data include:

• group: Arm indicator (1 = control, 2= treatment).

• id: Subject identifier (unique across both arms).

• e: Enrollment time on the calendar scale.

• event_time_cal: Cumulative event time on the calendar scale.

• status: Event indicator with values 2=recurrent event, 1=death, and 0=censoring.

• Z1, Z2: Simulated covariates, where Z1 is the treatment indicator (0 for arm 1, 1 for arm 2).

• tau_star: Subject-specific stopping time, the last event observed in [0, tau_star] is classified as death.

• death: Binary indicator for death.

• recurrent: Binary indicator for recurrent events.

• event: Binary event indicator, event = death + recurrent.

• calendar: Calendar time cutoff used to generate the returned data.

• lambda_0: Baseline Poisson process rate parameter.

• lambda_star: Rate parameter of an exponential distribution in generating tau_star.

• gamma_scale, gamma_shape: Parameters of the Gamma distribution used to generate subject-specific frailty terms.

References

Mao L, Lin DY. Semiparametric regression for the weighted composite endpoint of recurrent and terminal events. Biostatistics. 2016 Apr; 17(2) :390-403.

Examples

# Generate two-sample composite endpoint data
df <- TwoSample.generate.sequential(sizevec = c(200, 200),
beta.trt = 0.8, calendar = 5, recruitment = 3,
random.censor.rate = 0.05, seed = 2026)

Function to solve for the mean frequency effect size given target power for one-sample simulations.

Description

Computes the mean frequency difference parameter \Delta that achieves a specified power for a two-sided group sequential test.

Usage

find.Delta.given.power(K, timing, alpha, power, Imax)

Arguments

Value

A numeric value giving the mean frequency effect size \Delta that achieves the specified power.

Examples

# Toy Example: n = 800, two interim analysi planned at 50% and
# 75% if maximum information, along with a final analysis
# at 100% maximum information. Assuming the maximum
# information is 100, overall Type I error at 0.05 and power at 0.8.
find.Delta.given.power(K = 3, timing = c(0.5, 0.75, 1),
 alpha = 0.05, power = 0.8, Imax = 100)

Function to solve for treatment effect size given target power for two-sample tests.

Description

Computes the treatment effect parameter beta.trt that achieves a specified power for a two-sided Wald-type test under a normal approximation. The calculation assumes that the test statistic Q is asymptotically normal with mean proportional to the treatment effect and variance var.

Usage

find.beta.trt(power = 0.8, power.c, var)

Arguments

Value

A numeric value giving the treatment effect parameter.

Function to solve for a group sequential critical value at a given stage

Description

Computes the critical boundary value at the current analysis stage by solving a probability equation under a multivariate normal distribution. The boundary is chosen so that the incremental Type I error spent at the current stage equals a specified target value, conditional on previously determined boundaries.

Usage

find.c(previous.c, pi, corr)

Arguments

Value

A numeric value giving the critical boundary c at the current analysis stage that satisfies the specified Type I spending constraint.

Function to solve for the baseline recurrent event rate given a mean frequency difference for one-sample simulations.

Description

Computes the value of the baseline recurrent event rate parameter \lambda_0 hat yields a specified difference in mean frequency function at a given event time, relative to a null value.

Usage

find.lambda_0.given.Delta(
  lambda_star,
  null.lambda_0,
  gamma_shape,
  gamma_scale,
  Delta,
  t
)

Arguments

Value

A numeric value giving the baseline recurrent event rate \lambda_0 that satisfies the specified mean frequency difference at time t.

Examples

# Toy Example: n = 800, two interim analysi planned
# at 50% and 75% if maximum information, along with
# a final analysis at 100% maximum information.
# Assuming the maximum information is 100,
# overall Type I error at 0.05 and power at 0.8.
find.Delta.given.power(K = 3, timing = c(0.5, 0.75, 1),
alpha = 0.05, power = 0.8, Imax = 100)
# Use the computed value from the
# "find.Delta.given.power()" function
find.lambda_0.given.Delta(lambda_star = 0.1, null.lambda_0 = 1.15,
gamma_shape = 2, gamma_scale = 0.5, Delta = 0.2834591, t = 2)

Function to solve for the baseline recurrent event rate given a target mean frequency for one-sample simulations.

Description

Computes the value of the baseline recurrent event rate parameter.

Usage

find.lambda_0.given.mu0(lambda_star, gamma_shape, gamma_scale, t, mu0)

Arguments

Value

A numeric value giving the baseline recurrent event rate \lambda_0 that satisfies \mu(t) = \mu(0).

Examples

find.lambda_0.given.mu0(lambda_star = 0.1, gamma_shape = 2, gamma_scale = 0.5, t = 1, mu0 = 2)