trialist-quick-start.RmdFor a randomized trial with one binary treatment, EffectXshift(rct = TRUE) asks:
Which baseline covariate-defined subgroup has the largest treatment-effect difference compared with its complement?
In rct_type = "ate" mode, the subject-level contrast is the expected outcome under treatment minus the expected outcome under control: Q(1, W) - Q(0, W). The package uses training folds to discover a subgroup rule and held-out folds to estimate the treatment effect in the discovered region V, its complement V^c, and the contrast V - V^c.
This is most useful as an exploratory or adaptive-prespecification tool for baseline subgroup discovery. For a confirmatory trial analysis, the eligible baseline variables, tuning parameters, endpoint, intercurrent-event strategy, and interpretation plan should be prespecified.
| Object | Meaning | Trialist note |
|---|---|---|
w |
Baseline covariates eligible for subgroup discovery | Include variables measured before randomization. Do not include post-randomization variables. |
a |
One binary treatment column | Code control as 0 and active treatment as 1. |
y |
Fully observed scalar endpoint | For fixed-time event endpoints, handle censoring before creating y. |
alpha |
Known treatment allocation probability | Pass the design value, especially for unequal randomization. |
n_folds |
Cross-fitting folds | Use enough folds for stable held-out estimation; inspect fold-level rules. |
min_obs, max_depth, pval_thresh
|
Subgroup search controls | Keep the search simple enough to be interpretable. |
The treatment mode currently targets one binary treatment and a marginal allocation probability. Cluster-randomized, adaptive, crossover, platform, or strongly stratified designs may need design-specific handling before confirmatory use.
Before running the package, write down:
A = 1) versus control (A = 0)For a fixed-time event estimand such as the risk difference by time tau, do not code subjects censored before tau as event-free unless that composite endpoint is the estimand. If censoring is informative, first use a censoring-adjusted estimator, such as an IPCW/AIPW/TMLE approach for right-censored outcomes, to construct an endpoint or pseudo-outcome aligned with the estimand (Moore and van der Laan 2009; Brooks et al. 2013).
| Result object | How to use it |
|---|---|
Effect Modification K-Fold Results |
Check whether folds select similar variables, thresholds, and region orientation. |
Pooled Region Effects |
Primary held-out estimates for V, V^c, and V - V^c. |
Trial Region Diagnostics |
Descriptive arm counts and observed outcome summaries in each selected region. |
Region V Data, Region V^c Data
|
Validation rows with the selected-region indicator and pseudo-outcome columns. |
diagnose_selection(results) |
Compact summary of fold-level selection stability. |
diagnose_trial_regions(results) |
Recompute or extract the trial region diagnostics table. |
A concise report should include:
alpha
n_folds, min_obs, max_depth, and pval_thresh
V, V^c, and V - V^c estimates with confidence intervalsFor example:
EffectXshift was used as an exploratory held-out subgroup discovery analysis among randomized participants. Treatment was coded as 1 for active treatment and 0 for control, with allocation probability alpha = 0.5. Candidate subgroup variables were restricted to baseline covariates. The selected region
Vwas compared with its complementV^c; fold-level rules, pooled region effects, and selected-region arm counts were reviewed before interpretation.
See the simulated randomized-trial walkthrough for a complete example.