# Data Dictionary

## `data/pbc_hte_analysis_dataset.csv`

Compact analysis dataset derived from randomized participants in `survival::pbc`, after complete-case selection of the variables used in the case study.

| Variable | Description |
|---|---|
| `id` | Sequential analysis-row identifier created after restricting to randomized trial participants. |
| `time_years` | Follow-up time in years (`time / 365.25`). |
| `event` | Death indicator: 1 if original PBC `status == 2`, otherwise 0. Transplantation is not counted as the event in this demonstration. |
| `treatment` | Generic reproduction label. `Control` corresponds to source `trt = 1`; `Treatment` corresponds to source `trt = 2`. See the historical-coding warning in README. |
| `age` | Baseline age in years. |
| `age_group` | Median-split age category: `Younger` or `Older`. |
| `bili` | Serum bilirubin (mg/dL). |
| `log_bili` | Natural logarithm of bilirubin. |
| `bili_group` | Median-split bilirubin category: `Lower bilirubin` or `Higher bilirubin`. |
| `albumin` | Serum albumin (g/dL). |
| `albumin_group` | Median-split albumin category: `Lower albumin` or `Higher albumin`. |
| `edema` | Baseline edema category from the PBC data. |
| `stage` | Histologic disease stage. |
| `protime` | Standardized blood clotting / prothrombin time variable from PBC. |
| `copper` | Urine copper (ug/day). |
| `ast` | Aspartate aminotransferase measure from PBC. |

## `reference/overall_treatment_effect.csv`

Overall univariable Cox proportional-hazards result for the generic analytical arm contrast.

| Variable | Description |
|---|---|
| `subgroup` | `Overall`. |
| `level` | `All patients`. |
| `N` | Number of observations. |
| `Events` | Number of deaths. |
| `HR` | Estimated hazard ratio for the `Treatment` analysis label versus `Control`. |
| `conf.low` | Lower 95% confidence limit for HR. |
| `conf.high` | Upper 95% confidence limit for HR. |
| `p.value` | Wald-test p-value. |

## `reference/classical_subgroup_results.csv`

Overall and subgroup-specific univariable Cox estimates.

| Variable | Description |
|---|---|
| `subgroup` | Variable defining the subgroup. |
| `level` | Subgroup level. |
| `N` | Subgroup sample size. |
| `Events` | Number of deaths. |
| `HR` | Estimated analytical arm hazard ratio. |
| `conf.low`, `conf.high` | 95% confidence interval. |
| `p.value` | Nominal subgroup-specific Wald p-value. |
| `label` | Display label used in the forest plot. |
| `significant_nominal` | Whether the nominal p-value is below 0.05; no multiplicity adjustment is applied. |

## `reference/bilirubin_effect_curve.csv`

Continuous model-based treatment contrast across the observed bilirubin range.

| Variable | Description |
|---|---|
| `log_bili` | Natural-log bilirubin value used in the interaction model. |
| `bili` | Bilirubin on the original scale. |
| `HR` | Estimated analytical arm hazard ratio at that bilirubin value. |
| `conf.low`, `conf.high` | Model-based 95% confidence interval. |

## `reference/bilirubin_dichotomized_results.csv`

Unadjusted treatment estimates within lower- and higher-bilirubin median-split groups, used to illustrate the information loss caused by dichotomization.

## `reference/patient_specific_benefit_scores.csv`

The compact analysis dataset plus in-sample model-based patient-level contrasts from the multivariable Cox interaction model.

| Variable | Description |
|---|---|
| `log_hr_individual` | Difference between fitted linear predictors under the two generic analytical arm labels. |
| `hr_individual` | `exp(log_hr_individual)`. This is a relative hazard contrast from the fitted model. |
| `benefit_score` | `1 - hr_individual`; an illustrative transformation, not a probability. |
| `benefit_group` | Illustrative categorization: HR < 0.75 = high predicted benefit; 0.75 <= HR < 1 = moderate predicted benefit; HR >= 1 = low or no predicted benefit. |

The `benefit_*` terminology is retained to reproduce the original Insight. These variables are **not validated individualized causal treatment effects**.

## `reference/subgroup_hte_summary.csv`

Compact list of the principal released numerical results.

## `output/dataset_checks.csv`

Automated release-preparation checks for dataset size, arm/event counts, completeness and output dimensions.

## `output/validation_checks.csv`

Automated numerical consistency and independent-validation checks. `PASS` indicates that the observed value satisfied the prespecified exact or numerical tolerance.