ITCD

Official minimal implementation of “ITCD: Implicit Trajectory-Constrained Diffusion for Consistent Time Series Imputation.” ITCD addresses the distribution shift introduced by missing-value padding through a two-stage diffusion framework that progressively bridges the padded and real-data distributions. Intermediate and terminal constraints provide distributional and numerical guidance to the reverse process, implicitly constraining its sampling trajectory and producing consistent imputations.

Overview of the intermediate noise constraint and terminal reconstruction constraint used to guide the ITCD denoising trajectory.

Install

Python 3.10–3.12 is supported.

pip install -r requirements.txt

Datasets

The paper evaluates eight datasets. Download them from their original providers and follow their licenses or access conditions:

1. Beijing Multi-Site Air Quality
2. Air Quality (Italy)
3. Caltrans PeMS — registration may be required; third-party mirrors are not official sources
4. Melbourne Pedestrian benchmark (City of Melbourne source)
5. ETTh1 / ETT
6. Electricity Load Diagrams 2011–2014
7. PhysioNet Challenge 2012
8. PhysioNet Challenge 2019

No raw or processed third-party data is distributed here. train.py and evaluate.py accept local .npy, .npz, or numeric .csv arrays shaped [sample, time, feature]; a [time, feature] array is converted to non-overlapping windows. Use NaN for inherent missing values. Data and cache directories are ignored by Git.

Checkpoint

itcd_italy_air_t10_core.pt is the Italy Air, 10-step Core Stage checkpoint used for low-cost inference. It is available from GitHub Release v1.0.0 (SHA-256 08181abbdf58abf8147b1c76c8cfaa36bbe10ac344c50523d6284f7427213561). quick_start.py downloads and verifies it when absent.

Usage

Test the released checkpoint

python quick_start.py

This command downloads and verifies the released checkpoint, then runs one inference example.

To evaluate the same checkpoint on locally prepared Italy Air windows:

python evaluate.py --checkpoint checkpoints/itcd_italy_air_t10_core.pt --data data/italy_air_test.npy

Here, --checkpoint selects the released Core Stage weights and --data supplies local windows shaped [sample, 12, 13]. The command reports MAE, MSE, MRE, and sampling uncertainty on an artificial missing mask; these results depend on local preprocessing and are not the paper's multi-run benchmark results.

Train ITCD

python train.py --preset italy_air --data data/italy_air_train.npy --epochs 1 --output checkpoints/itcd_italy_air.pt

This command completes one training epoch for the Refinement and Core stages with all four paper-level loss terms, then saves a full training checkpoint. The Italy Air preset expects windows shaped [sample, 12, 13]; remove --epochs 1 to use the full epoch count in configs/itcd.yaml.

Key parameters are in configs/itcd.yaml: diffusion_steps, embedding_dim, hidden_dim, heads, layers, learning rate, batch size, missing ratio, and missing pattern (point, subsequence, or block). Inference intentionally loads and runs only the Core Stage; training uses both stages and all four paper-level loss terms.

License and limitations

Code is released under the Apache License 2.0. Dataset rights remain with their providers. The public checkpoint is an inference-only Core Stage asset and contains no training data. Exact benchmark reproduction requires the original provider data, the stated preprocessing/window shape, and the paper’s multi-run protocol.