mask-ddpm/docs/decisions.md

Design & Decision Log

2026-01-26 — Two-stage temporal backbone (GRU) + residual diffusion

• Decision: Add a stage-1 GRU trend model, then train diffusion on residuals.
• Why: Separate temporal consistency from distribution alignment.
• Files:
  • example/hybrid_diffusion.py (added TemporalGRUGenerator)
  • example/train.py (two-stage training + residual diffusion)
  • example/sample.py, example/export_samples.py (trend + residual synthesis)
  • example/config.json (temporal hyperparameters)
• Expected effect: improve lag-1 consistency; may hurt KS if residual distribution drifts.

2026-01-26 — Residual distribution alignment losses

• Decision: Apply distribution losses to residuals (not raw x0).
• Why: Diffusion models residuals; alignment should match residual distribution.
• Files:
  • example/train.py (quantile loss on residuals)
  • example/config.json (quantile weight)

2026-01-26 — SNR-weighted loss + residual stats

• Decision: Add SNR-weighted loss and residual mean/std regularization.
• Why: Stabilize diffusion training and improve KS.
• Files:
  • example/train.py
  • example/config.json

2026-01-26 — Switchable backbone (GRU vs Transformer)

• Decision: Make the diffusion backbone configurable (backbone_type) with a Transformer encoder option.
• Why: Test whether self‑attention reduces temporal vs distribution competition without altering the two‑stage design.
• Files:
  • example/hybrid_diffusion.py
  • example/train.py
  • example/sample.py
  • example/export_samples.py
  • example/config.json

2026-01-26 — Per-feature KS diagnostics

• Decision: Add a per-feature KS/CDF diagnostic script to pinpoint KS failures (tails, boundary pile-up, shifts).
• Why: Avoid blind reweighting and find the specific features causing KS to stay high.
• Files:
  • example/diagnose_ks.py

2026-01-26 — Quantile transform + sigmoid bounds for continuous features

• Decision: Add optional quantile normalization (TabDDPM-style) and sigmoid-based bounds to reduce KS spikes.
• Why: KS failures are dominated by boundary pile-up and tail mismatch.
• Files:
  • example/data_utils.py
  • example/prepare_data.py
  • example/export_samples.py
  • example/config.json

2026-01-27 — Quantile transform without extra standardization

• Decision: When quantile transform is enabled, skip mean/std normalization (quantile output already ~N(0,1)).
• Why: Prevent scale mismatch that pushed values to max bounds and blew up KS.
• Files:
  • example/data_utils.py
  • example/export_samples.py