hinna0818/ukbanalytica_v2/ukbsci-subgroup-sensitivity

ukbsci-subgroup-sensitivity — Subgroup & sensitivity analyses

0. RAP guardrails

Input: cohort data.table. Output: aggregate subgroup-effect tables and sensitivity flow tables that may be shared with the local agent.

Strict local-agent boundary: this skill is for script generation, workflow planning, package guidance, and interpretation of aggregate outputs. The agent must not read, inspect, summarize, or process real UK Biobank RAP participant-level data, including de-identified row-level tables, raw RAP fields, exact dates, per-row predictions, row-level SHAP matrices, screenshots, tracebacks, or logs containing row-level values. Generate scripts for the user to run inside RAP; only aggregate results or rendered figures may be shared back with the agent. See ../references/agent-privacy-boundary.md.

1. When to load

• Run effect estimates within strata of a categorical modifier.
• Report a formal interaction p-value for the modifier.
• Sweep over multiple potential modifiers in one go.
• Drop events in the first N years (lag analysis for reverse-causation).
• Complete-case re-run, optionally with a participant-flow trace.
• Record sequential inclusion/exclusion counts for a flow diagram.
• Run a compact Cox sensitivity suite with early-event and covariate-adjustment variants.

2. When NOT to load

• Main-effect models without subgroups → ukbsci-regression.
• Mediation analysis → ukbsci-mediation.
• Propensity-score weighting → ukbsci-propensity.

3. Prerequisites

library(UKBAnalytica); library(survival); library(data.table)
stopifnot(all(c("outcome_status", "outcome_surv_time") %in% colnames(cohort)))

4. Pipeline

Phase 0 — Participant flow table

Use ukb_participant_flow() when the user needs a transparent attrition table before modeling. The output is aggregate and can be shared with the local agent.

flow <- ukb_participant_flow(
  data = cohort,
  steps = list(
    "Complete primary covariates" = c("age", "sex", "bmi", "smoking_status"),
    "Positive follow-up time"     = ~ outcome_surv_time > 0
  ),
  id_col      = "eid",
  outcome_col = "outcome_status"
)
 
plot_participant_flow(flow)

Phase 1 — Single-modifier subgroup analysis

run_subgroup_analysis() estimates stratum-specific effects and an interaction p-value for any of five model families: "cox", "logistic", "linear", "glm", "negbin".

# Cox subgroup (default use-case)
sub_cox <- run_subgroup_analysis(
  data         = cohort,
  exposure     = "sbp",
  subgroup_var = "sex",
  covariates   = c("age", "bmi", "smoking_status"),
  model_type   = "cox",
  endpoint     = c("outcome_surv_time", "outcome_status"),
  ref_level    = "Male"
)
# data.frame: one row per subgroup level
#   subgroup_var, subgroup, n, n_event, estimate (HR / OR / β / IRR),
#   lower95, upper95, pvalue, p_interaction
 
# GLM subgroup — Poisson (incidence rate ratio)
sub_glm <- run_subgroup_analysis(
  data         = cohort,
  exposure     = "sbp",
  outcome      = "hospitalisation_count",
  subgroup_var = "sex",
  covariates   = c("age", "bmi", "smoking_status"),
  model_type   = "glm",
  family       = "poisson"
)
# family accepts character, function, or family object
# quasi-Poisson → Wald CI; log/logit link → estimate column is exponentiated
 
# Negative-binomial subgroup (IRR = exp(beta))
sub_nb <- run_subgroup_analysis(
  data         = cohort,
  exposure     = "sbp",
  outcome      = "hospitalisation_count",
  subgroup_var = "sex",
  covariates   = c("age", "bmi", "smoking_status"),
  model_type   = "negbin"
)

Interaction p-value method:

• Binary subgroup or continuous exposure × binary factor → Wald p on single interaction term.
• Multi-level factor → likelihood-ratio test (LRT) via anova(); quasi-likelihood falls back

to an F-test.

Phase 2 — Multiple modifiers

multi_sub <- run_multi_subgroup(
  data           = cohort,
  exposure       = "sbp",
  subgroup_vars  = c("sex", "age_band", "smoking_status", "Diabetes_history"),
  covariates     = c("age", "bmi"),
  model_type     = "cox",           # or "glm", "negbin", "logistic", "linear"
  endpoint       = c("outcome_surv_time", "outcome_status")
)
fwrite(multi_sub, "/mnt/project/<area>/04-results/03-cox_subgroup.csv")

The output is long; p_interaction is repeated for each level of a given subgroup variable. model_type and family are forwarded to run_subgroup_analysis() — all five families apply.

Phase 3 — Sensitivity analysis: drop early events

trim <- sensitivity_exclude_early_events(
  data     = cohort,
  endpoint = c("outcome_surv_time", "outcome_status"),
  n_years  = 2,
  copy     = TRUE,
  verbose  = TRUE
)
attr(trim, "sensitivity_info")
# list: method, endpoint, n_years, n_input, n_removed, n_output
 
# Then re-fit:
cox_lag2 <- runmulti_cox(
  data = trim,
  main_var = "sbp",
  covariates = c("age", "sex", "bmi", "smoking_status"),
  endpoint = c("outcome_surv_time", "outcome_status")
)

Use runmulti_cox_lag() instead when you want the same regression fit at multiple lag values in one call (see ukbsci-regression).

Phase 4 — Sensitivity analysis: complete-case

cc <- sensitivity_exclude_missing_covariates(
  data       = cohort,
  covariates = c("age", "sex", "bmi", "smoking_status",
                 "ldl_cholesterol", "hba1c"),
  copy       = TRUE,
  stepwise   = TRUE,                         # records per-variable drop
  verbose    = TRUE
)
attr(cc, "sensitivity_info")
attr(cc, "complete_case_flow")  # only when stepwise = TRUE
 
cox_cc <- runmulti_cox(
  data = cc,
  main_var = "sbp",
  covariates = c("age", "sex", "bmi", "smoking_status",
                 "ldl_cholesterol", "hba1c"),
  endpoint = c("outcome_surv_time", "outcome_status")
)
fwrite(cox_cc, "/mnt/project/<area>/04-results/04-cox_sensitivity.csv")

When the user has multiply-imputed data, prefer pooled MI analysis (ukbsci-imputation) over complete-case. Complete-case is a sensitivity check, not the main analysis.

Phase 5 — Compact Cox sensitivity suite

Use ukb_sensitivity_suite() when the user wants the standard Cox sensitivity bundle with one exposure and shared covariates.

sens <- ukb_sensitivity_suite(
  data = cohort,
  exposure = "exposure",
  covariates = c("age", "sex", "bmi", "smoking_status"),
  endpoint = c("outcome_surv_time", "outcome_status"),
  early_event_years = c(2, 4, 6),
  complete_case_covariates = c("age", "sex", "bmi", "smoking_status"),
  additional_covariate_sets = list(extra = c("education", "TDI")),
  verbose = FALSE
)
 
sens$summary

5. Common pitfalls

1. Subgroup variable with NA. Rows with NA on subgroup_var are

dropped silently by run_subgroup_analysis(). The reported n reflects the post-drop sample.

1. No within-stratum variation. A subgroup level may have zero events

for a binary exposure — the function warns and returns NA for that row. Filter / merge upstream.

1. `p_interaction` interpretation. It is the p-value for the

exposure × subgroup interaction term in the full-cohort model — NOT a pairwise stratum comparison.

1. Multiple-comparisons correction. run_multi_subgroup() does NOT

adjust. With 4+ modifiers, apply BH externally.

1. `sensitivity_exclude_early_events()` does not shift origin. It

simply drops events with surv_time ≤ n_years; the time variable is unchanged. Mention this in the manuscript footnote.

1. `copy = TRUE` is the safe default for data.table inputs —

it preserves the original. Setting FALSE mutates cohort in place.

1. `stepwise = TRUE` is informative but slow for wide cohorts. Use it

only when you need a participant-flow figure for the manuscript.

6. Key functions

`model_type` effect estimate column mapping:

7. Related skills

8. References

• `references/functions.md`
• `references/examples.md`