Package {RMTIF}


Type: Package
Title: Restricted Mean Time in Favor of Treatment
Version: 0.3.1
Description: Estimates restricted mean time in favor of treatment from ordered multistate trajectories, with lower states denoting better outcomes. Provides complete-path pairwise estimation, projection standard errors, normal confidence intervals and tests, terminal-aware inverse probability of censoring weighting, stratified bootstrap inference, and pairwise regression with sandwich or refitted-bootstrap inference. Includes parameterized simulation and Monte Carlo summary tools for reversible processes, continuous-time Markov paths, constant-utility regression, and comparisons of longitudinal oncology endpoints. The restricted-time estimand follows Mao (2023) <doi:10.1111/biom.13570>; pairwise regression is motivated by the proportional win-fractions framework of Mao and Wang (2021) <doi:10.1111/biom.13382>.
License: GPL (≥ 3)
Encoding: UTF-8
Depends: R (≥ 4.1.0)
Imports: stats, utils, parallel
Suggests: MASS, survival, Wcompo
NeedsCompilation: no
Packaged: 2026-11-02 17:35:21 UTC; mrezapou
Author: Mohsen Rezapour [aut, cre]
Maintainer: Mohsen Rezapour <mrezapou@amgen.com>
Repository: CRAN
Date/Publication: 2026-11-21 19:10:09 UTC

Restricted Mean Time in Favor of Treatment

Description

Estimation, inference, and parameterized simulation for ordered multistate trajectories. Lower numeric state values mean better outcomes; net time equals treatment win time minus treatment loss time.

Details

Use rmtif_subject to represent observed trajectories, rmtif_complete for complete-path inference, rmtif_ipcw for censoring-adjusted inference with a refitted stratified bootstrap, and rmtif_regression for pairwise regression. Design settings and Monte Carlo sizes are supplied explicitly by the caller.

References

Mao, L. (2023). "On restricted mean time in favor of treatment." Biometrics, 79(1), 61-72. doi:10.1111/biom.13570.

Mao, L. and Wang, T. (2021). "A class of proportional win-fractions regression models for composite outcomes." Biometrics, 77(4), 1265-1275. doi:10.1111/biom.13382.

See Also

rmtif_subject, rmtif_complete, rmtif_ipcw, rmtif_regression


Audit arm-specific censoring support for IPCW

Description

The aim is to check the empirical positivity condition before estimation. Survival is evaluated as the predictable left limit at 'tau'; therefore a Kaplan–Meier curve that first reaches zero exactly at 'tau' still supports integration through that endpoint, whereas a zero before 'tau' does not.

Usage

rmtif_censoring_support(subjects,
    tau)

Arguments

subjects

List of 'rmtif_subject' objects.

tau

Candidate restriction horizon.

Value

One row per arm with the left-limit survival at 'tau', the first zero observed by 'tau', maximum empirically verified horizon, and a support flag. Absence of a zero by 'tau' is not extrapolated beyond 'tau'.


Estimate complete-data rmt-IF with projection inference

Description

Average pairwise treatment-minus-control net times over every control and treatment subject pair. Subject-level row and column projections yield the two-sample U-statistic standard error. The function reports a normal confidence interval and the z statistic and two-sided p-value for a zero contrast; no independent-increment assumption across time is used.

Usage

rmtif_complete(subjects,
    tau,
    conf_level)

Arguments

subjects

List of 'rmtif_subject' objects with complete paths to 'tau'.

tau

Restriction horizon.

conf_level

Confidence level.

Value

An 'rmtif_fit' list containing 'estimate', projection 'se', 'conf_int', zero-contrast 'statistic' and 'p_value', mean pairwise 'win' and 'loss' times, and row and column projections.

Examples

subjects <- list(
  rmtif_subject(0, 0, 5, tau = 3.7),
  rmtif_subject(0, 0, 5, tau = 3.7),
  rmtif_subject(1, 0, 4, tau = 3.7),
  rmtif_subject(1, 0, 4, tau = 3.7)
)
rmtif_complete(subjects, tau = 3.7, conf_level = 0.95)

Estimate a complete-data rmt-IF curve

Description

The function generates pointwise estimates and projection intervals for complete ordered-state paths.

Usage

rmtif_complete_curve(subjects,
    times,
    conf_level)

Arguments

subjects

Complete observed paths.

times

Increasing restriction horizons.

conf_level

Pointwise confidence level.

Value

Data frame with estimate, standard error, interval, and p-value.


Evaluate the exact finite-state projection curve by state counts

Description

This is the fast implementation of the complete-path pairwise estimator. For each interval it obtains row and column projections from strict empirical state counts in the opposite arm, algebraically matching the dense pair matrix without assuming independent increments across time.

Usage

rmtif_complete_state_count_curve(subjects,
    times,
    conf_level)

Arguments

subjects

Complete observed ordered-state paths.

times

Increasing positive restriction horizons.

conf_level

Pointwise normal confidence level.

Value

Data frame with horizon, rmt-IF estimate, projection SE, interval endpoints, and two-sided zero-contrast p-value.


Construct scheduled-visit ordered states from recurrent HF event records

Description

This entry point accepts the event-record schema used by the public HF example: patient identifier, event time, raw event code, treatment arm, and baseline etiology. Hospitalization since the previous scheduled visit defines the nonterminal state; observed death is an absorbing exact event.

Usage

rmtif_construct_scheduled_visit_states(data,
    tau,
    visit_interval,
    raw_status,
    ordered_state,
    quantile_probs)

Arguments

data

Event records with 'id', 'time', 'status', 'Training', and 'HF.etiology' columns.

tau

Restriction horizon.

visit_interval

Scheduled-visit spacing.

raw_status

Named 'censor', 'death', 'hospitalization' code vector.

ordered_state

Named ordered-state code vector.

quantile_probs

Three probabilities for the censor-time arm audit.

Value

List with constructed 'rmtif_subject' paths and subject and arm audit data frames.


Build a continuous-time Markov generator from transition intensities

Description

The caller supplies nonnegative off-diagonal transition intensities in a square matrix. Diagonal values are ignored and replaced by the negative off-diagonal row sums. This permits reversible movement among nonterminal states and an absorbing terminal state when its off-diagonal row is zero.

Usage

rmtif_ctmc_generator(off_diagonal_rates)

Arguments

off_diagonal_rates

Square matrix of transition intensities.

Value

Valid CTMC generator with zero row sums.

Examples

rates <- matrix(c(0, 0.17, 0.29, 0), nrow = 2, byrow = TRUE)
rmtif_ctmc_generator(rates)

Summarize Gumbel regression recovery over simulated trials

Description

The summary contains the mean estimate, empirical SD, mean estimated SE, interval coverage, and convergence counts for every parameter and sample size. Trials with singular or nearly singular sensitivity are excluded from summary estimates and counted as failed fits.

Usage

rmtif_gumbel_recovery_study(n_per_arm_values,
    replications,
    beta_true,
    tau,
    sigma_x,
    conf_level,
    
    seed)

Arguments

n_per_arm_values

Per-arm sample sizes.

replications

Monte Carlo trials per sample size.

beta_true

True treatment and covariate coefficients.

tau

Restriction horizon.

sigma_x

Baseline covariate covariance matrix.

conf_level

Confidence level.

seed

Reproducibility seed.

Value

List containing replicate-level and summary data frames.


Analyze the public 'hfmock' scheduled-visit process

Description

If 'data' is omitted, the function loads 'hfmock' only when the optional 'Wcompo' package is installed. No synthetic replacement is silently used. The analysis reports arm counts and terminal-aware IPCW bootstrap inference.

Usage

rmtif_hfmock_analysis(data = NULL,
    tau,
    visit_interval,
    bootstrap,
    seed,
    raw_status,
    
    ordered_state,
    quantile_probs,
    conf_level,
    bootstrap_success_fraction,
    
    minimum_survival = 0,
    projection_diagnostic = FALSE)

Arguments

data

Optional 'hfmock' data frame.

tau

Restriction horizon.

visit_interval

Scheduled visit spacing.

bootstrap

Stratified bootstrap replicates.

seed

Reproducibility seed.

raw_status

Named raw event-code vector; see 'rmtif_hfmock_subjects'.

ordered_state

Named ordered-state vector; see 'rmtif_hfmock_subjects'.

quantile_probs

Censor-time audit probabilities; see 'rmtif_hfmock_subjects'.

conf_level

Normal confidence level.

bootstrap_success_fraction

Required fraction of successful bootstrap resamples before reporting inference.

minimum_survival

Positivity threshold.

projection_diagnostic

Whether to retain the dense fixed-weight projection diagnostic.

Value

List with construction audit and an 'rmtif_ipcw' fit.


Convert 'Wcompo::hfmock' event records to scheduled-visit state paths

Description

At caller-specified visits, the better nonterminal state means no hospitalization since the prior visit, the worse nonterminal state means at least one hospitalization, and death is an exact absorbing state. An end-of-record observation between visits censors the scheduled-visit process at the most recent completed visit. The raw data do not distinguish every such observation as loss to follow-up versus administrative closure. A record extending to or beyond the requested horizon supports carrying the most recent scheduled state to that horizon, including a horizon between scheduled visits.

Usage

rmtif_hfmock_subjects(data,
    tau,
    visit_interval,
    raw_status,
    ordered_state,
    quantile_probs)

Arguments

data

A data frame with 'id', 'time', 'status', 'Training', and 'HF.etiology', such as 'Wcompo::hfmock'.

tau

Restriction horizon.

visit_interval

Scheduled-visit spacing.

raw_status

Named vector with 'censor', 'death', and 'hospitalization' raw event codes.

ordered_state

Named vector with 'no_hospitalization', 'hospitalization', and 'death' ordered-state codes.

quantile_probs

Three requested probabilities for the arm audit's lower, median, and upper censor-time summaries.

Value

List with 'rmtif_subject' objects and raw-data audit summaries.


Estimate terminal-aware arm-specific IPCW rmt-IF

Description

The aim is unbiased marginal rmt-IF estimation under unconditional independent loss to follow-up within treatment arm. The estimator uses two arm-specific censoring Kaplan-Meier curves, carries observed death forward, and integrates over the union of state, death, and censoring times. Primary inference is a treatment-stratified bootstrap that refits both censoring curves in every replicate. The fixed-weight projection is returned only as a diagnostic because it omits censoring-curve estimation uncertainty.

Usage

rmtif_ipcw(subjects,
    tau,
    bootstrap,
    conf_level,
    bootstrap_success_fraction,
    
    seed = NULL,
    minimum_survival = 0,
    projection_diagnostic = TRUE,
    allow_insufficient_bootstrap = FALSE)

Arguments

subjects

List of observed 'rmtif_subject' objects.

tau

Restriction horizon.

bootstrap

Number of stratified bootstrap replicates.

conf_level

Confidence level.

bootstrap_success_fraction

Minimum fraction of finite bootstrap estimates needed to report bootstrap inference.

seed

Optional reproducibility seed.

minimum_survival

Positivity threshold for each arm-specific curve.

projection_diagnostic

Whether to form the dense original-sample pair matrix for the fixed-weight projection diagnostic. Set to 'FALSE' in a Monte Carlo study when only the IPCW point estimate and refitted-bootstrap inference are required.

allow_insufficient_bootstrap

If 'TRUE', return a diagnostic object when too few bootstrap resamples retain support. Its bootstrap standard error and intervals are left undefined; this option is intended only to audit a boundary horizon, not to report primary inference.

Value

An 'rmtif_fit' list with bootstrap inference when requested.


Check the exact IPCW state-mass implementation against dense pair averaging

Description

This audit helper evaluates one observed data set by both algebraically identical routes. It is useful for regression testing the faster bootstrap calculation; it does not fit a bootstrap or change the estimator.

Usage

rmtif_ipcw_equivalence_check(subjects,
    tau,
    minimum_survival = 0,
    tolerance = 1e-10)

Arguments

subjects

List of observed 'rmtif_subject' objects.

tau

Restriction horizon.

minimum_survival

Positivity threshold for each arm-specific curve.

tolerance

Absolute numerical comparison tolerance.

Value

One-row data frame with dense, direct state-mass, and cached state-mass IPCW means, including a deterministic duplicate-subject bootstrap resample.


Prepare control and treatment CTMC generators for a censoring study

Description

The design supplies every transition intensity and treatment multiplier. Additional trial design fields are passed through for convenience.

Usage

rmtif_ipcw_simulation_parameters(design)

Arguments

design

List containing 'rates_control', 'benefit_multiplier', 'initial_state', 'death_state', 'tau', 'primary_censoring_rates', 'allocations', 'trials', and 'bootstrap'.

Value

Named list of control, null-treatment and benefit-treatment CTMC generators, state labels, and supplied trial settings.


Run the dedicated differential-censoring IPCW study

Description

The returned manuscript-ready summary contains truth, mean, bias, empirical SD, mean bootstrap SE, normal-interval coverage, rejection probability, and fit counts for every requested scenario/allocation combination.

Usage

rmtif_ipcw_simulation_study(allocations,
    scenarios,
    trials,
    bootstrap,
    tau,
    seed,
    minimum_survival,
    
    censoring_rates,
    parameters,
    conf_level,
    bootstrap_success_fraction,
    
    test_level,
    truth_grid_points)

Arguments

allocations

List of named 'c(n0, n1)' vectors.

scenarios

Null and/or treatment-benefit scenarios.

trials

Number of independently simulated trials.

bootstrap

Stratified bootstrap replicates per trial.

tau

Restriction horizon.

seed

Reproducibility seed.

minimum_survival

Positivity threshold.

censoring_rates

Named or ordered arm-specific exponential loss-to-follow-up rates used in every generated trial.

parameters

Markov generators and state labels.

conf_level

Confidence level.

bootstrap_success_fraction

Required successful bootstrap fraction.

test_level

Rejection threshold.

truth_grid_points

Number of numerical integration points for the population CTMC contrast.

Value

List containing replicate-level and summary data frames.


Summarize Monte Carlo estimator and interval performance

Description

For each requested design cell, calculate the mean estimate, bias, empirical standard deviation, mean reported standard error, interval coverage of the supplied truth, two-sided zero-test rejection fraction, and successful-fit count. Additional trial-level columns can be averaged over all generated trials, as with observed loss-to-follow-up fractions.

Usage

rmtif_monte_carlo_summary(replicates,
    group_columns,
    estimate_column,
    se_column,
    truth_column,
    
    lower_column,
    upper_column,
    p_value_column,
    test_level,
    extra_mean_columns = character())

Arguments

replicates

Data frame with one row per simulated trial.

group_columns

Character names of the columns defining design cells.

estimate_column

Name of the numeric estimate column.

se_column

Name of the numeric estimated-standard-error column.

truth_column

Name of the numeric population-truth column.

lower_column

Name of the lower confidence-limit column.

upper_column

Name of the upper confidence-limit column.

p_value_column

Name of the two-sided zero-test p-value column.

test_level

Rejection threshold for the p-value.

extra_mean_columns

Optional trial-level numeric columns to average.

Value

One row per design cell with truth, mean estimate, bias, empirical SD, mean estimated SE, coverage, rejection, successful-fit count, total trial count, and means of requested extra columns.


Apply loss to follow-up and terminal-event observation to a CTMC path

Description

A terminal state reached before censoring is observed exactly and carried forward. Earlier loss to follow-up truncates the observed nonterminal path.

Usage

rmtif_observe_ctmc_path(path,
    arm,
    tau,
    censor_time,
    death_state,
    covariates = numeric(),
    
    id = NULL)

Arguments

path

Complete CTMC path from 'rmtif_simulate_ctmc_path'.

arm

Treatment indicator.

tau

Restriction horizon.

censor_time

Independent loss-to-follow-up time.

death_state

Absorbing terminal-state label.

covariates

Optional numeric baseline covariate vector.

id

Optional subject identifier.

Value

One observed 'rmtif_subject'.


Compare six covariate-adjusted tests in one oncology trial

Description

OS/PFS use Cox Wald tests, OR and CDC use logistic Wald tests, study-specific ordinal BOR uses a proportional-odds Wald test, and RMT-IF tests its pairwise treatment coefficient. Every method uses the same generated subjects.

Usage

rmtif_oncology_compare_trial(simulation,
    rmt_inference,
    regression_bootstrap,
    conf_level,
    
    bootstrap_success_fraction,
    minimum_survival,
    test_level,
    bootstrap_seed = NULL)

Arguments

simulation

Output of 'rmtif_simulate_oncology_trial()'.

rmt_inference

Complete-path projection or censored IPCW bootstrap.

regression_bootstrap

IPCW bootstrap count (ignored for complete data).

conf_level

Confidence level.

bootstrap_success_fraction

Required successful bootstrap fraction.

minimum_survival

IPCW positivity threshold.

test_level

Two-sided rejection threshold.

bootstrap_seed

Separate seed for the stratified bootstrap.

Value

Six-row long-format method result.


Validate an ordered-state oncology simulation design

Description

All baseline intensities, covariate and treatment log-rate effects, state labels, and the initial and terminal states are supplied by the caller. The named clinical states define the response-confirmation endpoints. No manuscript simulation settings are inserted by this constructor.

Usage

rmtif_oncology_design(transition,
    states,
    initial_state,
    death_state,
    scenario)

Arguments

transition

Data frame with 'from', 'to', 'baseline_rate', 'covariate_log_rate', and 'treatment_log_rate' columns, one row per allowed transition. Rates are nonnegative; log-rate effects are finite.

states

Named, increasing, zero-based integer codes with names 'CR', 'PR', 'SD', 'PD', and 'death', in clinical order from better to worse.

initial_state

Initial state code.

death_state

Absorbing terminal state code, equal to 'states["death"]'.

scenario

Nonempty scenario label used only in returned metadata.

Value

A validated list with 'scenario', 'transition', 'states', 'initial_state', and 'death_state'.

Examples

transition <- data.frame(
  from = c(2, 2, 1, 0, 3), to = c(1, 3, 0, 4, 4),
  baseline_rate = c(0.17, 0.23, 0.19, 0.13, 0.27),
  covariate_log_rate = rep(0, 5),
  treatment_log_rate = rep(0, 5))
design <- rmtif_oncology_design(transition,
  states = c(CR = 0L, PR = 1L, SD = 2L, PD = 3L, death = 4L),
  initial_state = 2L, death_state = 4L, scenario = "illustration")
design$transition

Monte Carlo comparison of oncology endpoints on shared trials

Description

Simulate each scenario using a separate seed for every trial and bootstrap. All six methods analyse the same subjects within a replicate. Failed fits remain in the replicate file; rejection proportions and their Monte Carlo standard errors use the number of valid fits as the denominator. Optional scenario checkpoints permit an interrupted run to resume without changing the random streams. Parallel workers are allocated by scenario, not method.

Usage

rmtif_oncology_study(scenarios,
    designs,
    n_per_arm,
    replications,
    tau,
    assessment_interval,
    
    assessment_jitter,
    censoring_rate,
    covariate_mean,
    covariate_sd,
    rmt_inference,
    
    regression_bootstrap,
    seed,
    conf_level,
    bootstrap_success_fraction,
    
    minimum_survival,
    test_level,
    workers = 1L,
    checkpoint_dir = NULL)

Arguments

scenarios

Distinct scenario labels to simulate.

designs

Named list of validated ‘rmtif_oncology_design()' results, with one entry per requested scenario. List names and each design’s 'scenario' label must agree.

n_per_arm

Number of subjects in each arm.

replications

Number of attempted trials per scenario.

tau

Administrative horizon, in months.

assessment_interval

Nominal interval between assessments.

assessment_jitter

Half-width of uniform assessment-time jitter.

censoring_rate

Exponential loss-to-follow-up rate; zero gives complete follow-up through the administrative horizon.

covariate_mean

Mean of the Gaussian baseline covariate.

covariate_sd

Positive standard deviation of the Gaussian covariate.

rmt_inference

Complete-path projection or censored IPCW bootstrap.

regression_bootstrap

Bootstrap resamples for censored RMT-IF inference.

seed

Master seed; replicate seeds are retained in the output.

conf_level

Confidence level for fitted models.

bootstrap_success_fraction

Required successful bootstrap fraction.

minimum_survival

IPCW positivity threshold.

test_level

Two-sided rejection threshold.

workers

Number of scenario-level PSOCK workers.

checkpoint_dir

Optional directory for resumable scenario checkpoints.

Value

List containing summary, replicate, transition-design, and runtime data frames. The example driver saves these outside the package.


Calculate conditional oncology transition intensities and jump probabilities

Description

Apply the supplied Cox-form transition model at a specified treatment arm and baseline covariate value. The next-state probabilities divide each transition intensity by the total exit rate of its origin state. They are undefined ('NA') when all allowed exit rates from that state are zero.

Usage

rmtif_oncology_transition_rates(design,
    arm,
    covariate)

Arguments

design

Validated output of 'rmtif_oncology_design()'.

arm

Treatment-arm code, either control '0' or treatment '1'.

covariate

Finite scalar baseline covariate value.

Value

The design's transition data frame with 'intensity', 'total_exit_rate', and 'next_transition_probability' columns added.

Examples

transition <- data.frame(
  from = c(2, 2, 1, 0, 3), to = c(1, 3, 0, 4, 4),
  baseline_rate = c(0.17, 0.23, 0.19, 0.13, 0.27),
  covariate_log_rate = rep(0, 5),
  treatment_log_rate = rep(0, 5))
design <- rmtif_oncology_design(transition,
  states = c(CR = 0L, PR = 1L, SD = 2L, PD = 3L, death = 4L),
  initial_state = 2L, death_state = 4L, scenario = "illustration")
rmtif_oncology_transition_rates(design, arm = 1, covariate = 0)

Compute pairwise restricted win, loss, and net times

Description

This is the exact interval-by-interval calculation for two piecewise-constant paths. With 'censoring = "none"', both paths must be complete through 'tau'. With 'censoring = "arm_km"', the grid also contains every censoring time from 'reference_subjects', and the integrand uses the terminal-aware, arm-specific inverse censoring weight described in the revised manuscript.

Usage

rmtif_pair_times(control,
    treatment,
    tau,
    censoring = c("none",
    "arm_km"),
    reference_subjects = NULL,
    
    minimum_survival = 0)

Arguments

control

One arm-0 'rmtif_subject'.

treatment

One arm-1 'rmtif_subject'.

tau

Restriction horizon.

censoring

Either '"none"' or '"arm_km"'.

reference_subjects

Full sample used to estimate censoring curves.

minimum_survival

Positivity threshold for each censoring survival.

Value

Named vector with 'win', 'loss', and 'net' in time units.


Convert a Poisson attempted-event update model to a CTMC generator

Description

Attempted updates occur at the state-specific Poisson rates. Each attempt draws a destination from the corresponding row of 'transition'. A diagonal draw leaves the state unchanged; it is not a state transition. The resulting generator has off-diagonal entries 'rates[i] * transition[i, j]' and rows summing to zero. This construction accommodates reversible movement and positive diagonal update probabilities.

Usage

rmtif_poisson_update_generator(transition,
    rates)

Arguments

transition

Row-stochastic attempted-update probability matrix.

rates

Positive attempted-update rates, one per state.

Value

CTMC generator matrix with the same row and column names.

Examples

transition <- matrix(c(0.37, 0.63, 0.44, 0.56),
                     nrow = 2, byrow = TRUE)
rmtif_poisson_update_generator(transition, rates = c(1.3, 2.1))

Calibrate complete-path projection inference under Poisson updates

Description

Repeatedly simulate two arms of a reversible ordered-state process and compute the complete-path rmt-IF curve at each requested horizon. The population truth follows from the corresponding CTMC generators. The returned summary reports bias, empirical SD, projection SE, coverage and a two-sided zero-contrast rejection proportion for every horizon.

Usage

rmtif_poisson_update_study(scenario,
    n_per_arm,
    replications,
    tau,
    increment,
    seed,
    design,
    
    conf_level,
    test_level,
    truth_grid_points)

Arguments

scenario

Either '"Null"' or an alternative design.

n_per_arm

Subjects per arm.

replications

Monte Carlo replications.

tau

Restricted horizon.

increment

Evaluation-grid spacing.

seed

Reproducibility seed.

design

List with 'transition_control', 'transition_treatment', 'rates_control', 'rates_treatment', 'states', 'initial_state', and 'absorbing_states'; all study values are supplied by the caller.

conf_level

Confidence level.

test_level

Rejection threshold.

truth_grid_points

Number of numerical integration points for the population CTMC contrast.

Value

List with replicate-level curves and a pointwise summary containing population truth, bias, empirical SD, mean projection SE, normal-interval coverage, and zero-null rejection proportion.


Compute two-sample projection inference from pairwise net times

Description

The estimate is the mean of a control-by-treatment net-time matrix. Its standard error combines the empirical variance of row means divided by the control sample size with the variance of column means divided by the treatment sample size. A normal confidence interval and two-sided test of zero contrast use the supplied confidence level.

Usage

rmtif_projection_inference(pairwise_net_times,
    conf_level)

Arguments

pairwise_net_times

Finite numeric matrix with control subjects in rows and treatment subjects in columns.

conf_level

Confidence level for the normal interval.

Value

List with 'estimate', 'se', 'conf_int', 'statistic', 'p_value', 'row_projection', and 'column_projection'.

Examples

net <- matrix(c(1, 2, 3, 4), nrow = 2, byrow = TRUE)
rmtif_projection_inference(net, conf_level = 0.95)

Fit covariate-adjusted pairwise rmt-IF regression

Description

The model uses 'treatment + (X_treatment - X_control)' as its pairwise design, so the first coefficient is the treatment effect for equal baseline covariates. The score is exactly the manuscript score '(win - loss * exp(beta^T difference)) * difference'. With arm-specific IPCW, a stratified bootstrap refits both censoring curves and is the primary inference; the fixed-weight sandwich is retained as a diagnostic. A singular or nearly singular score-sensitivity matrix makes coefficients and intervals unidentified: the function raises an error instead of reporting a pseudoinverse-based, spuriously narrow interval. Near singular means the smallest singular value is at most the largest times square-root machine precision; remove redundant covariates and refit.

Usage

rmtif_regression(subjects,
    tau,
    censoring = c("none",
    "arm_km"),
    bootstrap,
    conf_level,
    
    bootstrap_success_fraction,
    seed = NULL,
    minimum_survival = 0,
    beta_initial = NULL)

Arguments

subjects

List of 'rmtif_subject' objects.

tau

Restriction horizon.

censoring

Either '"none"' or terminal-aware '"arm_km"'.

bootstrap

Stratified bootstrap replicates. '0' returns fixed-weight diagnostic inference only.

conf_level

Confidence level.

bootstrap_success_fraction

Minimum fraction of finite bootstrap fits needed to report bootstrap inference.

seed

Optional reproducibility seed.

minimum_survival

Positivity threshold for each censoring curve.

beta_initial

Optional starting coefficient vector.

Value

An 'rmtif_regression' fit with treatment and covariate coefficients.


Simulate a complete continuous-time Markov state path

Description

Wait at each state according to its generator exit intensity, then choose the next state in proportion to the off-diagonal intensities. An absorbing state ends transitions while retaining its state through the horizon.

Usage

rmtif_simulate_ctmc_path(generator,
    initial_state,
    tau)

Arguments

generator

Valid CTMC generator matrix.

initial_state

Initial state index starting at zero.

tau

Follow-up horizon.

Value

List with right-continuous 'times' and 'states' vectors.

Examples

rates <- matrix(c(0, 0.17, 0.29, 0), nrow = 2, byrow = TRUE)
generator <- rmtif_ctmc_generator(rates)
set.seed(397)
rmtif_simulate_ctmc_path(generator, initial_state = 0, tau = 3.7)

Simulate the constant-outcome Gumbel regression DGM

Description

This descriptive entry point generates the same Gaussian-covariate, Gumbel-error pairwise-regression trial as 'rmtif_simulate_gumbel_trial'. All treatment, slope, covariance, horizon, and sample-size inputs come from the caller.

Usage

rmtif_simulate_gumbel_regression(n_per_arm,
    beta_true,
    tau,
    sigma_x,
    seed = NULL)

Arguments

n_per_arm

Subjects per treatment arm.

beta_true

Named treatment-intercept and covariate-slope vector.

tau

Restricted time horizon.

sigma_x

Positive-definite baseline-covariate covariance matrix.

seed

Optional reproducibility seed.

Value

List with complete ordered-state subjects, true parameter vector, and restriction horizon.


Simulate a Gumbel pairwise-regression data-generating mechanism

Description

Generate Gaussian baseline covariates with the supplied covariance matrix, treatment allocation, and independent standard Gumbel errors. The resulting continuous latent utility is constant over follow-up and is represented by its negative as an ordered state, so smaller states mean better outcomes. This is a regression-equation sanity check rather than a multistate DGM.

Usage

rmtif_simulate_gumbel_trial(n_per_arm,
    beta_true,
    tau,
    sigma_x,
    seed = NULL)

Arguments

n_per_arm

Subjects per arm.

beta_true

Named vector: treatment intercept followed by slopes.

tau

Restriction horizon.

sigma_x

Positive-definite covariance matrix for baseline covariates.

seed

Optional seed.

Value

Complete 'rmtif_subject' list and true parameter.

Examples

trial <- rmtif_simulate_gumbel_trial(
  n_per_arm = 12, beta_true = c(0.2, 0.3), tau = 3.7,
  sigma_x = matrix(1), seed = 397)
rmtif_complete(trial$subjects, tau = 3.7, conf_level = 0.95)

Simulate one dedicated IPCW trial

Description

The aim is to evaluate the marginal arm-specific IPCW estimator under a reversible nonterminal process, absorbing death, unequal allocation, and differential but within-arm independent loss to follow-up.

Usage

rmtif_simulate_ipcw_trial(n0,
    n1,
    scenario,
    tau,
    censoring_rates,
    parameters,
    seed = NULL)

Arguments

n0

Control sample size.

n1

Treatment sample size.

scenario

'"Null"' or '"Treatment benefit"'.

tau

Restriction horizon.

censoring_rates

Arm-specific exponential loss-to-follow-up rates.

parameters

Markov generators and state labels.

seed

Optional seed.

Value

List of observed subjects and the two population generators.


Simulate one shared Appendix C oncology trial

Description

All six methods are derived from this same patient-level realization. Nominal visits are generated far enough to cover the jitter window and then visits outside '(0,tau]', after loss to follow-up, or at/after death are dropped. The RMT-IF representation is compressed to actual observed state changes; the complete visit history is retained for OR and BOR confirmation.

Usage

rmtif_simulate_oncology_trial(n_per_arm,
    design,
    tau,
    assessment_interval,
    assessment_jitter,
    
    censoring_rate,
    covariate_mean,
    covariate_sd,
    seed = NULL)

Arguments

n_per_arm

Exact subjects in each randomized arm.

design

Validated output of 'rmtif_oncology_design()'.

tau

Administrative restriction horizon.

assessment_interval

Nominal imaging interval.

assessment_jitter

Half-width of independent uniform visit jitter.

censoring_rate

Exponential LTFU rate; zero specifies complete follow-up.

covariate_mean

Mean of the Gaussian baseline covariate.

covariate_sd

Positive standard deviation of the Gaussian covariate.

seed

Reproducibility seed.

Value

Shared endpoint data, RMT-IF subjects, visits, and latent paths.

Examples

transition <- data.frame(
  from = c(2, 2, 1, 0, 3), to = c(1, 3, 0, 4, 4),
  baseline_rate = c(0.17, 0.23, 0.19, 0.13, 0.27),
  covariate_log_rate = rep(0, 5),
  treatment_log_rate = rep(0, 5))
design <- rmtif_oncology_design(transition,
  states = c(CR = 0L, PR = 1L, SD = 2L, PD = 3L, death = 4L),
  initial_state = 2L, death_state = 4L, scenario = "illustration")
trial <- rmtif_simulate_oncology_trial(
  n_per_arm = 8, design = design, tau = 3.7,
  assessment_interval = 0.8, assessment_jitter = 0.07,
  censoring_rate = 0, covariate_mean = 0, covariate_sd = 1,
  seed = 397)
names(trial)

Simulate finite-state Poisson attempted-event update trajectories

Description

At each state an exponential waiting time with the specified attempted-event rate precedes a destination draw from 'transition'. A self-update advances time while retaining the same state. The output is one complete observed ordered-state trajectory per subject; the supplied state order determines favorable versus unfavorable states in later rmt-IF calculations.

Usage

rmtif_simulate_poisson_updates(n,
    transition,
    rates,
    tau,
    states,
    initial_state,
    arm,
    absorbing_states,
    
    seed = NULL)

Arguments

n

Number of subjects.

transition

Row-stochastic attempted-update probability matrix.

rates

Positive attempted-update rates, one per state.

tau

Follow-up horizon.

states

Ordered numeric state labels.

initial_state

Initial state label.

arm

Treatment arm, 0 or 1.

absorbing_states

Optional explicit absorbing state labels.

seed

Optional seed.

Value

List of complete 'rmtif_subject' trajectories.

Examples

transition <- matrix(c(0.37, 0.63, 0.44, 0.56),
                     nrow = 2, byrow = TRUE)
paths <- rmtif_simulate_poisson_updates(
  n = 4, transition = transition, rates = c(1.3, 2.1),
  tau = 3.7, states = c(0, 1), initial_state = 0,
  arm = 0, absorbing_states = numeric(), seed = 397)
length(paths)

Evaluate a subject's right-continuous state

Description

This helper is intended for transparent checking of the path construction. It returns 'NA' after unobserved loss to follow-up, but continues to return the absorbing terminal state after an observed death.

Usage

rmtif_state_at(subject,
    time)

Arguments

subject

An 'rmtif_subject'.

time

One or more nonnegative evaluation times.

Value

A numeric vector of states, with 'NA' where the path is unavailable.


Construct one observed ordered-state trajectory

Description

The function creates the common subject representation used by every rmt-IF estimator in this file. 'times' and 'states' define a right-continuous, piecewise-constant observed path. An observed terminal event is inserted at 'death_time' and carried forward; it never truncates the outcome path. 'censor_time' is loss to follow-up or administrative end, and 'censor_event' distinguishes loss to follow-up from administrative end.

Usage

rmtif_subject(arm,
    times,
    states,
    tau,
    covariates = numeric(),
    censor_time = tau,
    
    censor_event = FALSE,
    death_time = Inf,
    death_state = NULL,
    id = NULL)

Arguments

arm

Treatment indicator, 0 for control or 1 for treatment.

times

Numeric state-observation/change times and must include baseline.

states

Ordered states corresponding to 'times'; smaller is better.

tau

Planned restriction horizon.

covariates

Optional numeric baseline covariate vector.

censor_time

Loss-to-follow-up or administrative time.

censor_event

Whether 'censor_time' is a loss-to-follow-up event.

death_time

Observed terminal-event time, or 'Inf' if unobserved/absent.

death_state

Ordered absorbing terminal state, or 'NULL' if not used.

id

Optional subject identifier.

Value

An object of class 'rmtif_subject'.

Examples

path <- rmtif_subject(arm = 1, times = c(0, 1.5),
                      states = c(2, 1), tau = 3.7)
rmtif_state_at(path, c(0, 1.5, 3))

Compute a population CTMC rmt-IF contrast

Description

The aim is to obtain simulation truth without Monte Carlo error. Transition probabilities are computed by uniformization and the pairwise state contrast is integrated numerically.

Usage

rmtif_true_ctmc_contrast(generator_control,
    generator_treatment,
    initial_state,
    tau,
    grid_points)

Arguments

generator_control

Control CTMC generator.

generator_treatment

Treatment CTMC generator.

initial_state

Common initial state, numbered from zero.

tau

Restriction horizon.

grid_points

Number of equally spaced integration points, supplied by the caller to control numerical accuracy.

Value

Population treatment-minus-control rmt-IF in time units.

Examples

rates <- matrix(c(0, 0.17, 0.29, 0), nrow = 2, byrow = TRUE)
generator <- rmtif_ctmc_generator(rates)
rmtif_true_ctmc_contrast(generator, generator, initial_state = 0,
                         tau = 3.7, grid_points = 51)