# Mayo Clinic PBC teaching data

These are real patient data from the Mayo Clinic study of primary biliary
cholangitis (PBC), historically called primary biliary cirrhosis. They support
the independent project in Part 6. The new descriptive Table 1 and figures are
teaching analyses, rather than reproductions of the publication's tables,
survival model, or treatment-effect analyses.

## Source and credit

Dickson ER, Grambsch PM, Fleming TR, Fisher LD, Langworthy A (1989).
*Prognosis in primary biliary cirrhosis: model for decision making.*
Hepatology 10(1):1–7. [Paper](https://doi.org/10.1002/hep.1840100102).

The source snapshot was exported on **2 November 2026** from `survival::pbc`
in the installed R package **survival 3.8-6**. The package's
[official dataset documentation](https://stat.ethz.ch/R-manual/R-devel/library/survival/html/pbc.html)
describes the study, source variables, and treatment coding. This online
development manual can change; the checked-in CSV fixes the version used here.
The documentation also credits Therneau T and Grambsch P (2000),
*Modeling Survival Data: Extending the Cox Model*, Springer.

The `survival` package declares **LGPL (>= 2)** in its package metadata.
This teaching material does not assert a separate CC0 license for the patient
data or the published article. Retain the source and publication credits when
reusing the teaching files.

## Files

- `pbc_source.csv`: all 418 rows and 20 original columns from `survival::pbc`,
  serialized to CSV without selecting patients, renaming columns, or converting
  units. R factor values are written as their text labels. Missing values are
  written as `NA`.
- `pbc_baseline.csv`: 312 randomized participants, with one row per patient
  and eight columns for the project. Treatment and sex codes have readable
  labels; the numeric measurements retain their source units and values.
- [Preparation script](../../../scripts/prepare_pbc.R): base R code. Rebuilding the
  teaching CSV uses the checked-in snapshot and needs no extra package or
  network connection.

SHA-256 checksums:

```text
pbc_source.csv
9826d98cdc3d95c44904663c8f5549df654c3e954799092e93adf5352ea19e12

pbc_baseline.csv
c7c4789a1cd12bb36574289e5b53f6c676166af926f460db102fcf584f24aa30
```

## Preparation and cohort

Run from the website project root:

```sh
Rscript scripts/prepare_pbc.R
```

The script also works from another directory when supplied its absolute path.
Optional arguments are the source CSV path and output directory.

1. Read the 418-row source snapshot and check its columns and unique patient IDs.
2. Retain the 312 patients with non-missing `trt`. The 106 patients with missing
   `trt` were not randomized and are excluded from this treatment-group summary.
3. Map `trt == 1` to `D-penicillamine` and `trt == 2` to `Placebo`.
   Map source sex `f` to `Female` and `m` to `Male`.
4. Select and rename the baseline variables listed below. No imputation,
   outcome-based selection, unit conversion, or whole-row complete-case
   restriction is applied.
5. Check 312 unique patients, 158 assigned D-penicillamine and 154 assigned
   placebo, valid stage codes, and the expected missing-value counts.

The source records reflect a historical Mayo Clinic trial conducted during
1974–1984. The full source contains 312 randomized patients and 106 additional
patients who did not participate in the randomized trial. The source is a
baseline patient dataset; `survival::pbcseq` is a different, longitudinal file
and is not used here.

## Teaching column dictionary

| Column | Source | Meaning |
|---|---|---|
| `patient_id` | `id` | Original case number; unique within this file |
| `treatment` | `trt` | Randomized assignment: D-penicillamine or placebo |
| `age` | `age` | Baseline age in **years**; already in years in this package version |
| `sex` | `sex` | Recorded sex: Female or Male |
| `bilirubin` | `bili` | Baseline serum bilirubin, mg/dL |
| `albumin` | `albumin` | Baseline serum albumin, g/dL |
| `cholesterol` | `chol` | Baseline serum cholesterol, mg/dL |
| `stage` | `stage` | Baseline histologic disease stage, coded 1–4; treat as categorical |

## Missing values and denominators

All 312 patients have age, sex, treatment assignment, bilirubin, albumin, and
stage recorded. **Cholesterol is missing for 28 patients**, leaving 284
available values. Keep these 28 patients in Table 1 and show the missing count;
do not delete their otherwise observed measurements.

For the supplied figures, bilirubin and stage are complete. The bilirubin
histogram therefore uses 312 patients. Stage percentages are calculated
**within each assigned-treatment group**, with denominators 158 and 154.
The stage counts for D-penicillamine/placebo are respectively 12/4 (stage 1),
35/32 (stage 2), 56/64 (stage 3), and 55/54 (stage 4).

These are **baseline** measurements. Differences in baseline summaries or
stage proportions do not measure treatment response. The project does not
estimate survival or efficacy, and it does not reproduce the paper's
prognostic model.
