# Code Guide

The scripts use paths relative to the package root and write new files to `generated/`. They do not overwrite the archived data or results.

## Recommended order

1. `01_validate_package.py` — lightweight structural and numerical checks.
2. `02_impute_panel_data.py` — reproduces the supplied two-stage imputation from the pre-imputation panel.
3. `03_tune_xgboost.py` — optional randomized hyperparameter search.
4. `04_compare_models.py` — reproduces the multi-model five-fold cross-validation comparison.
5. `05_xgboost_shap_pdp.py` — fits the main XGBoost model and generates SHAP and PDP outputs.

## Environment

Create an isolated environment with a supported Python version, then install:

```bash
python -m pip install -r code/requirements.txt
```

The exact versions used to generate the archived results were not included in the supplied materials. `requirements.txt` records a compatible reference environment; it is not original-environment provenance.

## Data files used

- `data/processed/panel_pre_imputation.csv`
- `data/processed/panel_analysis_ready.csv`

Both use English snake-case column names. Exact copies with the original Chinese column names are retained under `data/original_format/`.

## Methodological note

The main script preserves the supplied analysis design: an 80/20 random row-wise split for the main XGBoost model, SHAP/PDP evaluation over the full feature matrix, and shuffled row-wise five-fold cross-validation for model comparison. These choices do not provide group-held-out validation by city or time-aware forecasting validation.

