ESG: A PyTorch Toolkit for Learning Evolutionary and Multi-Scale Graphs in Time Series

What ESG Solves and Who It Is For

ESG addresses a specific gap in multivariate time series forecasting: most graph-based models assume a fixed graph structure, but real-world dependencies change over time and operate at different scales. The paper behind the code, published at KDD 2022, proposes learning an evolutionary graph that adapts, plus a multi-scale decomposition that captures both short-term and long-term patterns. The intended user is a researcher or graduate student who wants to reproduce the paper's results or experiment with graph learning on standard benchmarks like Solar-Energy, Electricity, Exchange-rate, Wind, NYC-Bike, and NYC-Taxi. This is not a general-purpose forecasting library. It is a research artifact with a narrow dataset focus and a specific training pipeline.

The Mechanism: Evolutionary and Multi-Scale Graph Learning

The core idea is visible in the repository structure and the training scripts. ESG does not use a static adjacency matrix. Instead, it learns a graph that evolves over time, which the README calls 'evolutionary'. It also builds multi-scale representations, meaning the model processes the time series at different temporal resolutions. The implementation relies on the MTGNN repository for foundational components, as stated in the acknowledgements. The training scripts, train_single_step.py and train_multi_step.py, take a --dy_embedding_dim argument, which likely controls the dimension of the dynamic embedding used to generate the evolving graph. The model outputs forecasts for a specified horizon, with single-step scripts using a --horizon flag and multi-step scripts not requiring one. The exact architecture, such as the number of graph convolution layers or the attention mechanism, is not described in the README, so you would need to read the source code to understand the full data flow.

Getting It Running: Data Preparation and Commands

The README gives concrete commands. First, install dependencies with 'pip install -r requirements.txt'. Then prepare data. For single-step datasets, you can download .h5 files from a Google Drive or Baidu Yun link, or convert raw data yourself. The raw Solar-Energy, Electricity, and Exchange-rate datasets come from the laiguokun multivariate time series repository. The Wind dataset requires deleting the 'CY' column and summing 24 hourly values per day to get daily estimates. For multi-step datasets, NYC-Bike and NYC-Taxi, you can either download pre-split .npz files or generate them from .h5 files using 'python gen_npz.py --h5_name nyc-bike' and 'python gen_npz.py --h5_name nyc-taxi' inside the data folder. Training commands are explicit. For example, Solar-Energy uses 'python train_single_step.py --data solar-energy --expid <expid> --num_nodes 137 --batch_size 16 --dy_embedding_dim 20 --runs 10 --horizon 3'. Each dataset has its own node count and batch size. Evaluation is separate, with commands like 'python test_single.py --data solar-energy --horizon 24 --expid only_test'.

A Genuine Limitation: Dataset Lock-In and Preprocessing Burden

ESG is not a drop-in tool for arbitrary time series. The README specifies exact node counts for each dataset, and the .h5 format is required. If your data does not match one of the six datasets, you must write your own preprocessing to produce .h5 files and adjust the node count. The Wind dataset preprocessing is particularly manual: you must delete a column and aggregate 24 hours into a day, which is a lossy operation that discards intra-day patterns. The multi-step datasets require an extra step of generating .npz files. This means the code is tightly coupled to the paper's experimental setup. For a practitioner with a new dataset, the effort to adapt ESG may exceed the benefit, especially since the README gives no guidance on how to modify the model for different input lengths or feature dimensions.

Maintenance and Upgrade Cost

The repository has no releases and the last push date is unknown, which is a warning sign for maintenance. The default branch is 'master', and the project is not archived, but that does not mean it is actively updated. The README mentions the paper was published in 2022, and the code relies on MTGNN, which is an older codebase. You should expect to debug compatibility issues with newer PyTorch versions, as the requirements.txt may pin older versions. The lack of a license is a significant issue. Without a license, you technically have no permission to use, modify, or distribute the code beyond reading it. For academic reproduction, this is a barrier. You must contact the authors or find a licensed fork. The upgrade cost is high if you need to adapt the code to new data or frameworks, because the documentation is minimal and the code is research-grade, not production-grade.

The Alternative: MTGNN and Its Differences

The README acknowledges that ESG relies on MTGNN, which is a graph neural network for multivariate time series forecasting. MTGNN learns a graph adjacency matrix from data, but it does not explicitly model evolutionary changes over time. MTGNN uses a mix of graph convolution and temporal convolution to capture spatial and temporal dependencies. ESG extends this by adding an evolutionary component and multi-scale processing. If you need a simpler baseline or a more mature codebase, MTGNN is a direct alternative because it is the foundation of ESG. The difference in approach is that MTGNN learns a static graph, while ESG learns a graph that changes over time. For a quick experiment, MTGNN may be easier to run because it has more documentation and a longer history. For reproducing the KDD 2022 results, you need ESG itself.

What to Verify Before Adopting ESG

Before you commit to ESG, check three things. First, confirm the license status. The repository metadata says 'unknown', which means you cannot legally use the code without permission. Contact the authors or look for a licensed version. Second, verify that your data can be converted to the .h5 format and that you can meet the node count requirements. The README gives no schema for the .h5 files, so you may need to inspect the code to understand the expected structure. Third, test the training on a small run. The commands include a --runs 10 flag, which suggests the code runs multiple trials. You can set --runs 1 to check if the pipeline works on your machine. Also, confirm that the dependencies in requirements.txt are compatible with your PyTorch installation. The code is from 2022, so older CUDA versions may be needed.

Editorial conclusion

Adopt ESG if you are a researcher reproducing the KDD 2022 paper or comparing graph-based forecasting methods on the provided datasets. Do not use it for production forecasting or on datasets outside the six listed, as the code expects preprocessed .h5 files and specific node counts. Before adoption, verify that your data can be converted to the required format and that the missing license does not block your use case. Check the repository's recent commits and issues for maintenance status, since the last push is unknown and no releases exist.

Frequently asked questions

Official sources

1. Official README
2. Project repository
3. README
4. Releases