# Data Dictionary - Legacy Harmonization v1.0.0

## Released specification files

### `data/legacy_study_specification.csv`
Describes the six synthetic legacy-study representations: target sample size, source endpoint, source time unit, treatment coding, tumor-size representation and node representation.

### `data/harmonization_map.csv`
Documents the common data model. The core harmonized variables are `study_id`, `source_endpoint`, `subject_id`, `age`, `treatment`, `tumor_size_mm`, `nodes`, `grade`, `analysis_time_years`, and `analysis_event`.

## Generated files after local execution

`data/generated/legacy_study_A.csv` ... `legacy_study_F.csv` contain deliberately heterogeneous representations of the six generated legacy studies.

`data/generated/integrated_legacy_breast_cancer.csv` contains the harmonized patient-level database.

### Harmonized variables

- `study_id`: generated source-study label.
- `source_endpoint`: endpoint definition used by the synthetic source study.
- `subject_id`: source-study subject identifier retained as character.
- `age`: age in years.
- `treatment`: harmonized `Control` / `Treatment` factor. In this demonstration it is derived from the `hormon` variable of the teaching dataset.
- `tumor_size_mm`: harmonized tumor-size value. Study C begins as categories and is mapped to representative values 15/35/65 mm; this is a deliberate information-loss example, not an imputation recommendation.
- `nodes`: harmonized positive-node count or proxy. Study E categories are mapped to 0/2/5 as a deliberate demonstration.
- `grade`: harmonized tumor-grade factor.
- `analysis_time_years`: source follow-up converted to years.
- `analysis_event`: source-study endpoint event indicator.

## Re-derived variables

- `event_3y`, `time_3y`: common 3-year endpoint/event and administrative follow-up.
- `event_5y`, `time_5y`: common 5-year endpoint/event and administrative follow-up.

## Important methodological caveat

The source transformations deliberately include lossy mappings and a death-proxy endpoint to illustrate typical legacy-data problems. They are educational examples, not preferred real-world harmonization rules. In actual projects, mappings require clinical review, provenance, explicit assumptions and sensitivity analysis.