# Simulations

This folder contains the Monte Carlo and SHAP-style decomposition exercises used to study the finite-sample behaviour of the density regression and decomposition methods (Online Appendix, Sections D.1–D.4).

---

## Main Scripts

| Script | Paper Reference | Description |
|---|---|---|
| `SIM1_DGPs.m` | Online Appendix Section 4.1 | Model performance across 8 DGPs (Normal, skew-*t*, Gaussian mixtures) at *T* ∈ {50, 100, 200, 500}. Compares DR vs. QR via KL divergence, MSE of moments. |
| `SIM2_H_select.m` | Online Appendix Section 4.2 | Mixture-component selection: hit rates and median selected *H* across DGPs and sample sizes. |
| `SIM3_density_decomposition.m` | Online Appendix Section 4.3 | Density decomposition simulation: compares SHAP (exact, sampling, kernel, KNN) vs. gradient and integrated-gradient attributions. |
| `SIM3_loss_decomposition.m` | Online Appendix Section 4.3 | Loss decomposition simulation: same comparison framework applied to a weighted loss function. |
| `SIM4_models_density_decomposition.m` | Online Appendix Section 4.4 | Model-based density decomposition: DR vs. QR on a simulated AR(1) with exogenous regressors. |
| `SIM4_models_loss_decomposition.m` | Online Appendix Section 4.4 | Model-based loss decomposition: DR vs. QR with parametric loss. |

---

## Data Flow

### Inputs
- **No external data required.** All simulations use synthetically generated data (DGP parameters are set inside each script).

### Intermediate Outputs (saved to `results/`)

| Script | Output file | Contents |
|---|---|---|
| `SIM1_DGPs.m` | `SIM1_DGPs_5_priorM_2_priorK_0_sampler_1_.mat` | KL divergences, moment divergences per DGP × *T* |
| `SIM2_H_select.m` | `SIM2_H_select_5_priorM_2_priorK_0_sampler_2_.mat` | Cluster assignment matrices, hit rates, median *H* |
| `SIM3_density_decomposition.m` | `SIM3_shap_dens_indep_1_.mat` | Efficiency errors, infidelity scores, Pearson correlations, hit rates |
| `SIM3_loss_decomposition.m` | `SIM3_shap_loss_indep_1_.mat` | Same metrics for loss decomposition |
| `SIM4_models_density_decomposition.m` | `SIM4_shaps_model_dens.mat` | Model-level density decomposition metrics |
| `SIM4_models_loss_decomposition.m` | `SIM4_shaps_model_loss.mat` | Model-level loss decomposition metrics |

### Figures (saved to `figures/`)

| Script | Figure files | Description |
|---|---|---|
| `SIM1_DGPs.m` | `OS_Figure1_DGP1_hist.{pdf,eps}` … `OS_Figure1_DGP8_hist.{pdf,eps}` | Histograms of the 8 DGPs (Online Appendix Figure D1) |

### LaTeX Tables
`SIM1_DGPs.m` and `SIM2_H_select.m` print LaTeX-formatted table rows to the MATLAB console for direct inclusion in the manuscript.

---

## Key Estimation Settings (shared across scripts)

| Parameter | Value | Meaning |
|---|---|---|
| `H_max` | 5 | Maximum number of mixture components |
| `init_method` | `'cluster'` | K-means cluster initialisation |
| `prior_mixing` | 2 | Horseshoe prior on mixing coefficients |
| `prior_kernel` | 0 | Normal prior on kernel coefficients |
| `max_iter` | 10 000 | Maximum VB iterations |
| `tol` | 1e-6 | Convergence tolerance |
| `MCs` | 500  | Number of Monte Carlo replications |

---

## Active Local Dependencies (`functions/`)

Core estimators: `VB_BDR_pipe`, `VB_BDR_priors`, `VBTVPQR`, `VB_DVS`
Sampling & prediction: `f_sample`, `f_sample_sel`, `f_simul_VB`, `f_predict`, `f_predict2`
Evaluation: `f_CRPS_nrg`, `f_CRPS_pwm`

**Decomposition functions:** The folder contains several numbered variants of the SHAP decomposition routines (`shap_dens_comp`, `shap_dens_comp2`, `shap_dens_comp3`, `shap_dens_comp4`; and `shap_loss_comp`, `shap_loss_comp3`). The core permutation-based Shapley algorithm is identical in all versions. The numbered variants add incremental robustness improvements:
- `comp2`: adds a feasibility warning when `d ≥ 10` for the exact method
- `comp3`: adds feature-group support (`groups` argument) and group-aware kernel/KNN methods
- `comp4`: adds a user-specified iteration count (`iterations` argument) on top of `comp3`

The loss variants follow the same pattern (`shap_loss_comp` → `shap_loss_comp3`), additionally dropping the `bin_edges` argument since the loss output is always 3 columns.

Other decomposition utilities: `eval_decomp`, `eval_decomp2`, `eval_loss_decomp`
Distribution helpers: `rskt`, `QR1_adjusted`
Plotting: `export_uniform_plot`
