Type:	Package
Title:	ROBust INference for Covariate Adjustment in Randomized Clinical Trials
Version:	0.2.0
Date:	2025-09-09
Description:	Performs robust estimation and inference when using covariate adjustment and/or covariate-adaptive randomization in randomized controlled trials. This package is trimmed to reduce the dependencies and validated to be used across industry. See "FDA's final guidance on covariate adjustment"https://www.regulations.gov/docket/FDA-2019-D-0934, Tsiatis (2008) <doi:10.1002/sim.3113>, Bugni et al. (2018) <doi:10.1080/01621459.2017.1375934>, Ye, Shao, Yi, and Zhao (2023)<doi:10.1080/01621459.2022.2049278>, Ye, Shao, and Yi (2022)<doi:10.1093/biomet/asab015>, Rosenblum and van der Laan (2010)<doi:10.2202/1557-4679.1138>, Wang et al. (2021)<doi:10.1080/01621459.2021.1981338>, Ye, Bannick, Yi, and Shao (2023)<doi:10.1080/24754269.2023.2205802>, and Bannick, Shao, Liu, Du, Yi, and Ye (2024)<doi:10.48550/arXiv.2306.10213>.
License:	Apache License 2.0
URL:	https://github.com/openpharma/RobinCar2/
BugReports:	https://github.com/openpharma/RobinCar2/issues
Depends:	R (≥ 3.6)
Imports:	checkmate, numDeriv, MASS, sandwich, stats, survival, utils
Suggests:	knitr, rmarkdown, testthat (≥ 3.0)
VignetteBuilder:	knitr
Config/testthat/edition:	3
Encoding:	UTF-8
Language:	en-US
LazyData:	true
RoxygenNote:	7.3.3
NeedsCompilation:	no
Packaged:	2025-09-09 02:08:05 UTC; root
Author:	Liming Li [aut, cre], Marlena Bannick [aut], Daniel Sabanes Bove [aut], Dong Xi [aut], Ting Ye [aut], Yanyao Yi [aut], Gregory Chen [ctb], Gilead Sciences, Inc. [cph, fnd], F. Hoffmann-La Roche AG [cph, fnd], Merck Sharp & Dohme, Inc. [cph, fnd], AstraZeneca plc [cph, fnd], Eli Lilly and Company [cph, fnd], The University of Washington [cph, fnd]
Maintainer:	Liming Li <liming.li1@astrazeneca.com>
Repository:	CRAN
Date/Publication:	2025-09-09 07:20:25 UTC

RobinCar2 Package

Description

RobinCar2 implements unbiased prediction and robust inference of variance of a fit in R.

Author(s)

Maintainer: Liming Li liming.li1@astrazeneca.com (ORCID)

Authors:

• Marlena Bannick mnorwood@uw.edu (ORCID)

• Daniel Sabanes Bove daniel@rconis.com (ORCID)

• Dong Xi Dong.Xi1@gilead.com

• Ting Ye tingye1@uw.edu

• Yanyao Yi yi_yanyao@lilly.com

Other contributors:

• Gregory Chen xiangyi.gregory.chen@msd.com [contributor]

• Gilead Sciences, Inc. [copyright holder, funder]

• F. Hoffmann-La Roche AG [copyright holder, funder]

• Merck Sharp & Dohme, Inc. [copyright holder, funder]

• AstraZeneca plc [copyright holder, funder]

• Eli Lilly and Company [copyright holder, funder]

• The University of Washington [copyright holder, funder]

See Also

Useful links:

• https://github.com/openpharma/RobinCar2/

• Report bugs at https://github.com/openpharma/RobinCar2/issues

Prediction Bias

Description

Obtain prediction bias within each stratum.

Usage

bias(residual, treatment, group_idx)

Arguments

Value

Numeric matrix of bias in each stratum.

Block Sum of a matrix

Description

Block Sum of a matrix

Usage

block_sum(x, n)

Confidence Interval

Description

Obtain the confidence interval for the marginal mean or the contrast.

Usage

## S3 method for class 'prediction_cf'
confint(object, parm, level = 0.95, include_se = FALSE, ...)

## S3 method for class 'surv_effect'
confint(object, parm, level = 0.95, transform, ...)

## S3 method for class 'treatment_effect'
confint(object, parm, level = 0.95, transform, ...)

Arguments

Value

A matrix of the confidence interval.

Examples

robin_res <- robin_glm(
  y_b ~ treatment * s1,
  data = glm_data, treatment = treatment ~ s1, contrast = "log_risk_ratio"
)
confint(robin_res$marginal_mean, level = 0.7)
confint(robin_res$contrast, parm = 1:3, level = 0.9)

Derive Outcome Values Based on Log Hazard Ratio

Description

Compute the derived outcome values based on a given log hazard ratio.

Usage

h_derived_outcome_vals(
  theta,
  df,
  treatment,
  time,
  status,
  covariates,
  n = nrow(df)
)

h_strat_derived_outcome_vals(
  theta,
  df,
  treatment,
  time,
  status,
  strata,
  covariates
)

Arguments

Details

Please note that the covariates must not include index, treatment, time, status to avoid naming conflicts.

Value

A data frame containing the same data as the input df, but restructured with standardized column names index, treatment, time, status, the covariates, and an additional column O_hat containing the derived outcome values. For the stratified version, the list of data frames is returned, one for each stratum.

Functions

• h_derived_outcome_vals(): calculates the derived outcome values for the overall data set.

• h_strat_derived_outcome_vals(): calculates the derived outcome values for each stratum separately.

Find Data in a Fit

Description

Find Data in a Fit

Usage

find_data(fit, ...)

Arguments

Value

A data frame used in the fit.

Calculate Coefficient Estimates from Linear Model Input

Description

Calculate the coefficient estimates for each treatment arm from the linear model input data.

Usage

h_get_beta_estimates(lm_input)

h_get_strat_beta_estimates(strat_lm_input)

Arguments

Value

A list containing the coefficient estimates for each treatment arm.

Functions

• h_get_beta_estimates(): Calculate the coefficient estimates for the overall data set.

• h_get_strat_beta_estimates(): Calculate the coefficient estimates using the stratified input.

Get Linear Model Input Data

Description

Prepare the input data for a linear model based on the provided data frame and model formula.

Usage

h_get_lm_input(df, model)

h_get_strat_lm_input(df_split, model)

Arguments

Value

A list containing for each element of the treatment factor a list with the corresponding model matrix X and the response vector y. For the stratified version, a list of such lists is returned, one for each stratum.

Functions

• h_get_lm_input(): Get the linear model input data for the overall data set.

• h_get_strat_lm_input(): Get the linear model input data for each stratum separately.

Example Trial Data for GLMs with Permute-Block Randomization

Description

This dataset contains the trial example data for GLMs with permute block randomization.

Usage

glm_data

Format

A data frame with 600 rows and 7 columns:

id

The ID of the patients.

treatment

The treatment assignment, "pbo", "trt1" and "trt2"

s1

The first stratification variable, "a" and "b".

s2

The second stratification variable, "c" and "d".

covar

The covariate following normal distribution.

y

The continuous response.

y_b

The binary response.

Source

The data is generated by the create_glm_data.R script.

Obtain Adjustment for Proportion of Treatment Assignment

Description

Obtain Adjustment for Proportion of Treatment Assignment

Usage

h_adjust_pi(pi)

Arguments

Value

Numeric matrix.

Confidence interval calculations which are common across effect results.

Description

Confidence interval calculations which are common across effect results.

Usage

h_confint(x, parm, level = 0.95, transform, include_se = FALSE, ...)

Contrast Functions and Jacobians

Description

Contrast Functions and Jacobians

Create Contrast of Pairs

Usage

h_diff(x, y)

h_jac_diff(x, y)

h_risk_ratio(x, y)

h_jac_risk_ratio(x, y)

h_odds_ratio(x, y)

h_jac_odds_ratio(x, y)

h_log_risk_ratio(x, y)

h_jac_log_risk_ratio(x, y)

h_log_odds_ratio(x, y)

h_jac_log_odds_ratio(x, y)

eff_jacob(f)

pairwise(levels, x = levels)

against_ref(levels, ref = levels[1], x = tail(levels, -1))

custom_contrast(levels, x, y)

Arguments

Value

Vector of contrasts, or matrix of jacobians.

A list of contrast object with following elements:

• Index of the treatment group.

• Index of the reference group. Additional attributes include levels and max_levels indicating the names of the treatment levels and the maximum number of levels.

Examples

h_diff(1:3, 4:6)
h_jac_risk_ratio(1:3, 4:6)

Prepare Events Table

Description

This function creates a data frame summarizing the number of patients and events for each treatment arm and stratification factor.

Usage

h_events_table(data, vars)

Arguments

Value

A data frame with columns for the treatment, strata, number of patients, and number of events.

Obtain Adjustment for Covariance Matrix

Description

Obtain Adjustment for Covariance Matrix

Usage

h_get_erb(resi, group_idx, trt, pi, randomization)

Arguments

Extract Variable Names

Description

Extract Variable Names

Usage

h_get_vars(treatment)

Arguments

Details

Extract the formula elements, including treatment, schema and strata.

Value

A list of three elements, treatment, schema and strata.

Evaluate if Interaction Exists

Description

Evaluate if Interaction Exists

Usage

h_interaction(formula, treatment)

Arguments

Log Hazard Ratio Coefficient Matrix

Description

This function creates a coefficient matrix for the log hazard ratio estimates.

Usage

h_log_hr_coef_mat(x)

Arguments

Value

A matrix with columns for the log hazard ratio estimate, standard error, z-value, and p-value.

Estimate Log Hazard Ratio via Score Function

Description

This function estimates the log hazard ratio by finding the root of the log-rank score function.

Usage

h_log_hr_est_via_score(score_fun, interval = c(-5, 5), ...)

Arguments

Details

This deactivates the ties factor correction in the score function by passing use_ties_factor = FALSE to the score_fun.

Value

A list containing:

• theta: The estimated log hazard ratio.

• se: The standard error of the estimated log hazard ratio.

• sigma_L2: The variance of the log-rank statistic.

• n: The number of observations used in the calculation.

Log-Rank Test via Score Function

Description

This function performs a log-rank test using the score function.

Usage

h_lr_test_via_score(score_fun, ...)

Arguments

Details

This activates the ties factor correction in the score function by passing use_ties_factor = TRUE to the score_fun.

Value

A list containing:

• u_l: The log-rank score statistic.

• sigma_l2: The variance of the log-rank statistic.

• tau_l: The log-rank test statistic.

• pval: The two-sided p-value of the log-rank test.

• n: The number of observations used in the calculation.

Count Number of Events per Unique Event Time

Description

This function counts the number of events at each unique event time point in a survival dataset.

Usage

h_n_events_per_time(df, time, status)

Arguments

Details

If there are no events in the dataset, it returns an empty data.frame.

Value

A data.frame with two columns: time and n_events, where n_events is the number of events at each time point.

Prepare Survival Input

Description

Prepare Survival Input

Usage

h_prep_survival_input(formula, data, treatment)

Arguments

Details

Note that formula can also contain an externally defined survival::Surv object. In this case, the time and status variables are extracted and added to the data input. Note that it is up to the user to ensure that in this case the column binding is correct, i.e., that the rows of the data match with the rows of the Surv object. In addition, the same named variables must not appear in both the data and the Surv object, to avoid ambiguity (this is a difference vs. the behavior of survival::coxph() for better transparency).

Value

A list containing the following elements:

• data: The potentially updated data set.

• time: Name of the time variable.

• status: Name of the status variable.

• treatment: Name of the treatment variable.

• strata: Name of the strata variable.

• schema: Randomization schema.

• covariates: Names of the covariates in the model.

• model: A formula only including the covariates, but not treatment or strata variables.

• n_levels: Number of treatment levels.

• levels: Names of the treatment levels.

Log-Rank Test Results Matrix

Description

This function creates a matrix summarizing the results of the log-rank test.

Usage

h_test_mat(x)

Arguments

Value

A matrix with columns for the test statistic and p-value.

Obtain the Jacobian matrix

Description

Obtain the Jacobian matrix

Usage

jac_mat(jac, pair)

Counterfactual Prediction

Description

Obtain counterfactual prediction of a fit.

Usage

predict_counterfactual(fit, treatment, data, vcov, vcov_args, ...)

Arguments

Value

List of class prediction_cf containing following elements:

• estimate: predicted marginal mean.

• residual: residual of the bias-corrected prediction.

• predictions: all predicted values.

• predictions_liner: linear predictions.

• schema: randomization schema.

• response: response value.

• fit: fitted model.

• model_matrix: model matrix.

• treatment_formula: treatment assignment and randomization formula.

• treatment: treatment value.

• group_idx: group index based on the stratification.

• variance: estimated variance of the marginal mean.

• variance_name: name of the variance.

S3 Methods for prediction_cf

Description

S3 Methods for prediction_cf

Usage

## S3 method for class 'prediction_cf'
print(x, level = 0.95, ...)

Arguments

Value

No return value.

Functions

• print(prediction_cf): prints the prediction_cf object.

Randomization schema

Description

Randomization schema

Usage

randomization_schema

Format

An object of class data.frame with 3 rows and 2 columns.

Covariate adjusted glm model

Description

Covariate adjusted glm model

Usage

robin_glm(
  formula,
  data,
  treatment,
  contrast = c("difference", "risk_ratio", "odds_ratio", "log_risk_ratio",
    "log_odds_ratio"),
  contrast_jac = NULL,
  vcov = "vcovG",
  family = gaussian(),
  vcov_args = list(),
  pair,
  ...
)

Arguments

Details

If family is MASS::negative.binomial(NA), the function will use MASS::glm.nb instead of glm.

Value

A robin_output object, with marginal_mean and contrast components.

Examples

robin_glm(
  y ~ treatment * s1,
  data = glm_data,
  treatment = treatment ~ s1, contrast = "difference"
)

Covariate adjusted lm model

Description

Covariate adjusted lm model

Usage

robin_lm(
  formula,
  data,
  treatment,
  vcov = "vcovG",
  vcov_args = list(),
  pair,
  ...
)

Arguments

Value

A robin_output object, with marginal_mean and contrast components.

Examples

robin_lm(
  y ~ treatment * s1,
  data = glm_data,
  treatment = treatment ~ s1
)

Covariate Adjusted and Stratified Survival Analysis

Description

Calculate log-rank test as well as hazard ratio estimates for survival data, optionally adjusted for covariates and a stratification factor.

Usage

robin_surv(
  formula,
  data,
  treatment,
  comparisons,
  contrast = "hazardratio",
  test = "logrank",
  ...
)

Arguments

Details

The user can optionally specify a list of comparisons between treatment levels to be performed. The list must have two elements:

• Treatment level indices of the treatment group.

• Treatment level indices of the control group.

So for example if you would like to compare level 3 with level 1, and also level 3 with level 2 (but not level 2 with level 1) then you can specify: comparisons = list(c(3, 3), c(1, 2))

Value

A surv_effect object containing the results of the survival analysis.

See Also

surv_effect_methods for S3 methods.

Examples

# Adjusted for covariates meal.cal and age and adjusted for stratification by sex:
robin_surv(
  formula = Surv(time, status) ~ meal.cal + age,
  data = surv_data,
  treatment = sex ~ strata
)

# Adjusted for stratification by strata but not for covariates:
robin_surv(
  formula = Surv(time, status) ~ 1,
  data = surv_data,
  treatment = sex ~ strata
)

# Unadjusted for covariates and stratification:
robin_surv(
  formula = Surv(time, status) ~ 1,
  data = surv_data,
  treatment = sex ~ 1
)

Log Hazard Ratio Estimation and Log-Rank Test via Score Function

Description

This function combines the estimation of the log hazard ratio and the log-rank test using a score function. Only two treatment arms are being compared and the data is subset accordingly.

Usage

robin_surv_comparison(
  score_fun,
  vars,
  data,
  exp_level,
  control_level,
  unadj_score_fun = NULL,
  ...
)

Arguments

Details

If an unadjusted score function is provided in unadj_score_fun, then it is used to estimate the log hazard ratio first. This unadjusted log hazard ratio estimate is then passed on to the adjusted score function score_fun as theta_hat. This is required when the score function is adjusted for covariates.

Value

A list containing:

• estimate: The estimated log hazard ratio.

• se: The standard error of the estimated log hazard ratio.

• hr_n: The number of observations used in the estimation.

• hr_sigma_l2: The variance of the log-rank statistic used in the estimation.

• test_stat: The log-rank test statistic.

• p_value: The two-sided p-value of the log-rank test.

• test_score: The log-rank score statistic.

• test_n: The number of observations used in the log-rank test.

• test_sigma_l2: The variance of the log-rank statistic used in the log-rank test.

Sum vectors in a list

Description

Sum vectors in a list

Usage

sum_vectors_in_list(lst)

Survival Example Data

Description

This dataset contains survival data from the survival package's survival::lung dataset, modified to include factors for sex and strata, as well as a binary status variable which is 1 for death and 0 for censored.

Usage

surv_data

Format

An object of class data.frame with 228 rows and 12 columns.

Source

The data is generated by the create_surv_data.R script.

S3 Methods for surv_effect

Description

S3 Methods for surv_effect

Usage

## S3 method for class 'surv_effect'
print(x, ...)

table(x, ...)

## Default S3 method:
table(x, ...)

## S3 method for class 'surv_effect'
table(x, ...)

Arguments

Functions

• print(surv_effect): prints the surv_effect object.

• table(surv_effect): prints and returns invisibly the events table of the surv_effect object.

Examples

x <- robin_surv(
  formula = Surv(time, status) ~ meal.cal + age,
  data = surv_data,
  treatment = sex ~ strata
)
print(x)
table(x)

Survival Comparison Functions

Description

These are simple wrappers around robin_surv_comparison() called with the corresponding log-rank score functions.

Usage

robin_surv_no_strata_no_cov(vars, data, exp_level, control_level)

robin_surv_strata(vars, data, exp_level, control_level)

robin_surv_cov(vars, data, exp_level, control_level, ...)

robin_surv_strata_cov(vars, data, exp_level, control_level, ...)

Arguments

Value

See robin_surv_comparison().

Functions

• robin_surv_no_strata_no_cov(): without strata and without covariates, based on h_lr_score_no_strata_no_cov().

• robin_surv_strata(): without strata and without covariates, based on h_lr_score_strat().

• robin_surv_cov(): without strata and without covariates, based on h_lr_score_cov() and h_lr_score_no_strata_no_cov() (which is used to find the unadjusted log hazard ratio estimate).

• robin_surv_strata_cov(): with strata and covariates, based on h_lr_score_strat_cov() and h_lr_score_strat() (which is used to find the unadjusted log hazard ratio estimate).

Log-Rank Score Functions for Survival Analysis

Description

These functions compute the log-rank score statistics for a survival analysis. Depending on the function, these are stratified and/or adjusted for covariates.

Usage

h_lr_score_no_strata_no_cov(
  theta,
  df,
  treatment,
  time,
  status,
  n = nrow(df),
  use_ties_factor = TRUE
)

h_lr_score_strat(
  theta,
  df,
  treatment,
  time,
  status,
  strata,
  use_ties_factor = TRUE
)

h_lr_score_cov(
  theta,
  df,
  treatment,
  time,
  status,
  model,
  theta_hat = theta,
  use_ties_factor = TRUE,
  hr_se_plugin_adjusted = TRUE
)

h_lr_score_strat_cov(
  theta,
  df,
  treatment,
  time,
  status,
  strata,
  model,
  theta_hat = theta,
  use_ties_factor = TRUE,
  hr_se_plugin_adjusted = TRUE
)

Arguments

Details

• The hr_se_plugin_adjusted flag is relevant only for the standard error of the covariate adjusted log hazard ratio estimate: When TRUE, the adjusted hazard ratio estimate is plugged in into the variance formula, as per the original publication. On the other hand, when FALSE, the unadjusted estimate is used instead. This is explained in more detail in the vignette "Survival Analysis with RobinCar2" in Section "Covariate adjusted analysis without strata".

• Note that for the not covariate adjusted score functions, these also work with a numeric theta vector of length > 1.

Value

The score function value(s), with the following attributes:

• sigma_l2: The variance of the log-rank statistic.

• se_theta_l: The corresponding standard error term for the log hazard ratio.

• n: The number of observations used in the calculation.

Functions

• h_lr_score_no_strata_no_cov(): without strata or covariates.

• h_lr_score_strat(): with strata but without covariates.

• h_lr_score_cov(): with covariates but without strata.

• h_lr_score_strat_cov(): with strata and covariates.

Treatment Effect

Description

Obtain treatment effect and variance from counter-factual prediction

Usage

treatment_effect(
  object,
  pair = pairwise(names(object$estimate)),
  eff_measure,
  eff_jacobian = eff_jacob(eff_measure),
  contrast_name,
  ...
)

difference(object, ...)

risk_ratio(object, ...)

odds_ratio(object, ...)

log_risk_ratio(object, ...)

log_odds_ratio(object, ...)

Arguments

Value

A list of treatment_effect object with following elements:

• estimate: estimate of the treatment effect.

• pair: contrast object indicating the pairwise treatment effect.

• contrast: name of the contrast function.

• euqal_val: the value for no treatment effect given the contrast.

• variance: the variance of the treatment effect.

• jacobian: the Jacobian matrix.

• contrast_mat: contrast summary matrix.

Update levels in a contrast pair

Description

Update levels in a contrast pair

Usage

update_levels(pair, levels)

Generalized Covariance (ANHECOVA)

Description

Generalized Covariance (ANHECOVA)

Usage

vcovG(x, decompose = TRUE, ...)

Arguments

Value

Named covariance matrix.

Heteroskedasticity-consistent covariance matrix for predictions

Description

The heteroskedasticity-consistent covariance matrix for predictions is obtained with sandwich::vocvHC using sandwich method.

Usage

vcovHC(x, type = "HC3", ...)

Arguments

Value

Matrix of the heteroskedasticity-consistent covariance for the predictions.