| Title: | Restricted Mean Time in Favor of Treatment |
|---|---|
| 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>. |
| Authors: | Mohsen Rezapour [aut, cre] |
| Maintainer: | Mohsen Rezapour <[email protected]> |
| License: | GPL (>= 3) |
| Version: | 0.3.1 |
| Built: | 2026-11-22 01:10:02 UTC |
| Source: | https://github.com/cran/RMTIF |
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.
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.
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.
rmtif_subject, rmtif_complete,
rmtif_ipcw, rmtif_regression
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.
rmtif_censoring_support(subjects, tau)rmtif_censoring_support(subjects, tau)
subjects |
List of 'rmtif_subject' objects. |
tau |
Candidate restriction horizon. |
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'.
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.
rmtif_complete(subjects, tau, conf_level)rmtif_complete(subjects, tau, conf_level)
subjects |
List of 'rmtif_subject' objects with complete paths to 'tau'. |
tau |
Restriction horizon. |
conf_level |
Confidence level. |
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.
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)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)
The function generates pointwise estimates and projection intervals for complete ordered-state paths.
rmtif_complete_curve(subjects, times, conf_level)rmtif_complete_curve(subjects, times, conf_level)
subjects |
Complete observed paths. |
times |
Increasing restriction horizons. |
conf_level |
Pointwise confidence level. |
Data frame with estimate, standard error, interval, and p-value.
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.
rmtif_complete_state_count_curve(subjects, times, conf_level)rmtif_complete_state_count_curve(subjects, times, conf_level)
subjects |
Complete observed ordered-state paths. |
times |
Increasing positive restriction horizons. |
conf_level |
Pointwise normal confidence level. |
Data frame with horizon, rmt-IF estimate, projection SE, interval endpoints, and two-sided zero-contrast p-value.
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.
rmtif_construct_scheduled_visit_states(data, tau, visit_interval, raw_status, ordered_state, quantile_probs)rmtif_construct_scheduled_visit_states(data, tau, visit_interval, raw_status, ordered_state, quantile_probs)
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. |
List with constructed 'rmtif_subject' paths and subject and arm audit data frames.
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.
rmtif_ctmc_generator(off_diagonal_rates)rmtif_ctmc_generator(off_diagonal_rates)
off_diagonal_rates |
Square matrix of transition intensities. |
Valid CTMC generator with zero row sums.
rates <- matrix(c(0, 0.17, 0.29, 0), nrow = 2, byrow = TRUE) rmtif_ctmc_generator(rates)rates <- matrix(c(0, 0.17, 0.29, 0), nrow = 2, byrow = TRUE) rmtif_ctmc_generator(rates)
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.
rmtif_gumbel_recovery_study(n_per_arm_values, replications, beta_true, tau, sigma_x, conf_level, seed)rmtif_gumbel_recovery_study(n_per_arm_values, replications, beta_true, tau, sigma_x, conf_level, seed)
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. |
List containing replicate-level and summary data frames.
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.
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)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)
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. |
List with construction audit and an 'rmtif_ipcw' fit.
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.
rmtif_hfmock_subjects(data, tau, visit_interval, raw_status, ordered_state, quantile_probs)rmtif_hfmock_subjects(data, tau, visit_interval, raw_status, ordered_state, quantile_probs)
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. |
List with 'rmtif_subject' objects and raw-data audit summaries.
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.
rmtif_ipcw(subjects, tau, bootstrap, conf_level, bootstrap_success_fraction, seed = NULL, minimum_survival = 0, projection_diagnostic = TRUE, allow_insufficient_bootstrap = FALSE)rmtif_ipcw(subjects, tau, bootstrap, conf_level, bootstrap_success_fraction, seed = NULL, minimum_survival = 0, projection_diagnostic = TRUE, allow_insufficient_bootstrap = FALSE)
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. |
An 'rmtif_fit' list with bootstrap inference when requested.
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.
rmtif_ipcw_equivalence_check(subjects, tau, minimum_survival = 0, tolerance = 1e-10)rmtif_ipcw_equivalence_check(subjects, tau, minimum_survival = 0, tolerance = 1e-10)
subjects |
List of observed 'rmtif_subject' objects. |
tau |
Restriction horizon. |
minimum_survival |
Positivity threshold for each arm-specific curve. |
tolerance |
Absolute numerical comparison tolerance. |
One-row data frame with dense, direct state-mass, and cached state-mass IPCW means, including a deterministic duplicate-subject bootstrap resample.
The design supplies every transition intensity and treatment multiplier. Additional trial design fields are passed through for convenience.
rmtif_ipcw_simulation_parameters(design)rmtif_ipcw_simulation_parameters(design)
design |
List containing 'rates_control', 'benefit_multiplier', 'initial_state', 'death_state', 'tau', 'primary_censoring_rates', 'allocations', 'trials', and 'bootstrap'. |
Named list of control, null-treatment and benefit-treatment CTMC generators, state labels, and supplied trial settings.
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.
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)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)
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. |
List containing replicate-level and summary data frames.
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.
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())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())
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. |
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.
A terminal state reached before censoring is observed exactly and carried forward. Earlier loss to follow-up truncates the observed nonterminal path.
rmtif_observe_ctmc_path(path, arm, tau, censor_time, death_state, covariates = numeric(), id = NULL)rmtif_observe_ctmc_path(path, arm, tau, censor_time, death_state, covariates = numeric(), id = NULL)
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. |
One observed 'rmtif_subject'.
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.
rmtif_oncology_compare_trial(simulation, rmt_inference, regression_bootstrap, conf_level, bootstrap_success_fraction, minimum_survival, test_level, bootstrap_seed = NULL)rmtif_oncology_compare_trial(simulation, rmt_inference, regression_bootstrap, conf_level, bootstrap_success_fraction, minimum_survival, test_level, bootstrap_seed = NULL)
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. |
Six-row long-format method result.
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.
rmtif_oncology_design(transition, states, initial_state, death_state, scenario)rmtif_oncology_design(transition, states, initial_state, death_state, scenario)
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. |
A validated list with 'scenario', 'transition', 'states', 'initial_state', and 'death_state'.
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$transitiontransition <- 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
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.
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)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)
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. |
List containing summary, replicate, transition-design, and runtime data frames. The example driver saves these outside the package.
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.
rmtif_oncology_transition_rates(design, arm, covariate)rmtif_oncology_transition_rates(design, arm, covariate)
design |
Validated output of 'rmtif_oncology_design()'. |
arm |
Treatment-arm code, either control '0' or treatment '1'. |
covariate |
Finite scalar baseline covariate value. |
The design's transition data frame with 'intensity', 'total_exit_rate', and 'next_transition_probability' columns added.
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)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)
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.
rmtif_pair_times(control, treatment, tau, censoring = c("none", "arm_km"), reference_subjects = NULL, minimum_survival = 0)rmtif_pair_times(control, treatment, tau, censoring = c("none", "arm_km"), reference_subjects = NULL, minimum_survival = 0)
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. |
Named vector with 'win', 'loss', and 'net' in time units.
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.
rmtif_poisson_update_generator(transition, rates)rmtif_poisson_update_generator(transition, rates)
transition |
Row-stochastic attempted-update probability matrix. |
rates |
Positive attempted-update rates, one per state. |
CTMC generator matrix with the same row and column names.
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))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))
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.
rmtif_poisson_update_study(scenario, n_per_arm, replications, tau, increment, seed, design, conf_level, test_level, truth_grid_points)rmtif_poisson_update_study(scenario, n_per_arm, replications, tau, increment, seed, design, conf_level, test_level, truth_grid_points)
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. |
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.
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.
rmtif_projection_inference(pairwise_net_times, conf_level)rmtif_projection_inference(pairwise_net_times, conf_level)
pairwise_net_times |
Finite numeric matrix with control subjects in rows and treatment subjects in columns. |
conf_level |
Confidence level for the normal interval. |
List with 'estimate', 'se', 'conf_int', 'statistic', 'p_value', 'row_projection', and 'column_projection'.
net <- matrix(c(1, 2, 3, 4), nrow = 2, byrow = TRUE) rmtif_projection_inference(net, conf_level = 0.95)net <- matrix(c(1, 2, 3, 4), nrow = 2, byrow = TRUE) rmtif_projection_inference(net, conf_level = 0.95)
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.
rmtif_regression(subjects, tau, censoring = c("none", "arm_km"), bootstrap, conf_level, bootstrap_success_fraction, seed = NULL, minimum_survival = 0, beta_initial = NULL)rmtif_regression(subjects, tau, censoring = c("none", "arm_km"), bootstrap, conf_level, bootstrap_success_fraction, seed = NULL, minimum_survival = 0, beta_initial = NULL)
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. |
An 'rmtif_regression' fit with treatment and covariate coefficients.
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.
rmtif_simulate_ctmc_path(generator, initial_state, tau)rmtif_simulate_ctmc_path(generator, initial_state, tau)
generator |
Valid CTMC generator matrix. |
initial_state |
Initial state index starting at zero. |
tau |
Follow-up horizon. |
List with right-continuous 'times' and 'states' vectors.
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)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)
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.
rmtif_simulate_gumbel_regression(n_per_arm, beta_true, tau, sigma_x, seed = NULL)rmtif_simulate_gumbel_regression(n_per_arm, beta_true, tau, sigma_x, seed = NULL)
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. |
List with complete ordered-state subjects, true parameter vector, and restriction horizon.
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.
rmtif_simulate_gumbel_trial(n_per_arm, beta_true, tau, sigma_x, seed = NULL)rmtif_simulate_gumbel_trial(n_per_arm, beta_true, tau, sigma_x, seed = NULL)
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. |
Complete 'rmtif_subject' list and true parameter.
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)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)
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.
rmtif_simulate_ipcw_trial(n0, n1, scenario, tau, censoring_rates, parameters, seed = NULL)rmtif_simulate_ipcw_trial(n0, n1, scenario, tau, censoring_rates, parameters, seed = NULL)
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. |
List of observed subjects and the two population generators.
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.
rmtif_simulate_oncology_trial(n_per_arm, design, tau, assessment_interval, assessment_jitter, censoring_rate, covariate_mean, covariate_sd, seed = NULL)rmtif_simulate_oncology_trial(n_per_arm, design, tau, assessment_interval, assessment_jitter, censoring_rate, covariate_mean, covariate_sd, seed = NULL)
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. |
Shared endpoint data, RMT-IF subjects, visits, and latent paths.
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)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)
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.
rmtif_simulate_poisson_updates(n, transition, rates, tau, states, initial_state, arm, absorbing_states, seed = NULL)rmtif_simulate_poisson_updates(n, transition, rates, tau, states, initial_state, arm, absorbing_states, seed = NULL)
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. |
List of complete 'rmtif_subject' trajectories.
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)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)
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.
rmtif_state_at(subject, time)rmtif_state_at(subject, time)
subject |
An 'rmtif_subject'. |
time |
One or more nonnegative evaluation times. |
A numeric vector of states, with 'NA' where the path is unavailable.
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.
rmtif_subject(arm, times, states, tau, covariates = numeric(), censor_time = tau, censor_event = FALSE, death_time = Inf, death_state = NULL, id = NULL)rmtif_subject(arm, times, states, tau, covariates = numeric(), censor_time = tau, censor_event = FALSE, death_time = Inf, death_state = NULL, id = NULL)
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. |
An object of class 'rmtif_subject'.
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))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))
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.
rmtif_true_ctmc_contrast(generator_control, generator_treatment, initial_state, tau, grid_points)rmtif_true_ctmc_contrast(generator_control, generator_treatment, initial_state, tau, grid_points)
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. |
Population treatment-minus-control rmt-IF in time units.
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)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)