feat: 🎸 version 0.4.0 (#141)

1. Modify data processing: standardize data formats, add metadata, refactor dataset classes, and remove data normalization operations. 2. Add a Scaler class: manage data normalization and denormalization in an extensible way. 3. Delete the loss folder and merge its contents into metrics. 4. Modify the Runner: streamline training and inference interfaces, add post-training inference functionality, and add the ability to save inference results and evaluation metrics. 5. Add an Examples folder: provide all configuration options with explanations, typical configuration files, and an example model structure (MLP). 6. Modify training and inference scripts. 7. Add detailed tutorials. 8, Refine code details. 9.Update requirements.txt. 10. Update README.md.
GestaltCogTeam · Sep 3, 2024 · 93b343e · 93b343e
1 parent a8d9ff8
commit 93b343e
Show file tree

Hide file tree

Showing 477 changed files with 26,539 additions and 29,642 deletions.
diff --git a/.gitignore b/.gitignore
@@ -2,7 +2,7 @@
 __pycache__/
 .vscode/
 checkpoints/
-datasets/raw_data
+datasets/
 todo.md
 gpu_task.py
 cmd.sh
@@ -14,11 +14,11 @@ cmd.sh
 *.pkl
 *.h5
 *.pt
-core*
 *.p
 *.pickle
 *.pyc
 *.txt
+*.core
 
 *.py[cod]
 *$py.class

diff --git a/.pylintrc b/.pylintrc
@@ -430,6 +430,6 @@ valid-metaclass-classmethod-first-arg=mcs
 
 # Exceptions that will emit a warning when being caught. Defaults to
 # "Exception"
-overgeneral-exceptions=StandardError,
-                       Exception,
-                       BaseException
+overgeneral-exceptions=builtins.StandardError,
+                       builtins.Exception,
+                       builtins.BaseException
diff --git a/README.md b/README.md
@@ -1,7 +1,7 @@
 <div align="center">
   <img src="assets/basicts+_logo_light.png#gh-light-mode-only" height=200>
   <img src="assets/basicts+_logo_dark.png#gh-dark-mode-only" height=200>
-  <h3><b> A Standard and Fair Time Series Forecasting Benchmark and Toolkit. </b></h3>
+  <h3><b> A Fair and Scalable Time Series Forecasting Benchmark and Toolkit. </b></h3>
 </div>
 
 ---
@@ -15,24 +15,40 @@
 
 </div>
 
-$\text{BasicTS}^{+}$ (**Basic** **T**ime **S**eries **P**lus) is an enhanced benchmark and toolbox designed for time series forecasting. $\text{BasicTS}^{+}$ evolved from its predecessor, [BasicTS](https://github.com/zezhishao/BasicTS/blob/v1/README.md), and now has robust support for spatial-temporal forecasting and long time-series forecasting as well as more general tasks, such as M4 competition. For brevity and consistency, we will interchangeably refer to this project as $\text{BasicTS}^{+}$ and $\text{BasicTS}$.
+<div align="center">
+
+🎉 [**Getting Started**](./tutorial/getting_started.md) **|** 
+💡 [**Overall Design**](./tutorial/overall_design.md)
+
+📦 [**Dataset**](./tutorial/dataset_design.md) **|** 
+🛠️ [**Scaler**](./tutorial/scaler_design.md) **|** 
+🧠 [**Model**](./tutorial/model_design.md) **|** 
+📉 [**Metrics**](./tutorial/metrics_design.md) **|** 
+🏃‍♂️ [**Runner**](./tutorial/runner_design.md) **|** 
+📜 [**Config**](./tutorial/config_design.md.md) **|** 
+📜 [**Baselines**](./baselines/)
+
+</div>
+
+
+$\text{BasicTS}^{+}$ (**Basic** **T**ime **S**eries **P**lus) is an enhanced benchmark and toolbox designed for time series forecasting. $\text{BasicTS}^{+}$ evolved from its predecessor, [BasicTS](https://github.com/zezhishao/BasicTS/blob/v1/README.md), and now has robust support for spatial-temporal forecasting and long time-series forecasting as well as more general tasks. For brevity and consistency, we will interchangeably refer to this project as $\text{BasicTS}^{+}$ and $\text{BasicTS}$.
 
 On the one hand, BasicTS utilizes a ***unified and standard pipeline*** to give a ***fair and exhaustive*** reproduction and comparison of popular deep learning-based models. 
 
 On the other hand, BasicTS provides users with ***easy-to-use and extensible interfaces*** to facilitate the quick design and evaluation of new models. At a minimum, users only need to define the model architecture.
 
 We are collecting **TODOs** and **HOWTOs**, if you need more features (*e.g.* more datasets or baselines) or have any questions, please feel free to create an issue or leave a comment [here](https://github.com/zezhishao/BasicTS/issues/95).
 
-If you find this repository useful for your work, please cite it as [such](./citation.bib):
-
-```LaTeX
-@article{shao2023exploring,
-  title={Exploring Progress in Multivariate Time Series Forecasting: Comprehensive Benchmarking and Heterogeneity Analysis},
-  author={Shao, Zezhi and Wang, Fei and Xu, Yongjun and Wei, Wei and Yu, Chengqing and Zhang, Zhao and Yao, Di and Jin, Guangyin and Cao, Xin and Cong, Gao and others},
-  journal={arXiv preprint arXiv:2310.06119},
-  year={2023}
-}
-```
+> [!IMPORTANT]  
+> If you find this repository useful for your work, please cite it as [such](./citation.bib):
+> ```LaTeX
+> @article{shao2023exploring,
+>    title={Exploring Progress in Multivariate Time Series Forecasting: Comprehensive Benchmarking and Heterogeneity Analysis},
+>    author={Shao, Zezhi and Wang, Fei and Xu, Yongjun and Wei, Wei and Yu, Chengqing and Zhang, Zhao and Yao, Di and Jin, Guangyin and Cao, Xin and Cong, Gao and others},
+>    journal={arXiv preprint arXiv:2310.06119},
+>    year={2023}
+>  }
+>  ```
 
 ## ✨ Highlighted Features
 
@@ -81,108 +97,14 @@ BasicTS implements a wealth of models, including classic models, spatial-tempora
 - DCRNN, Graph WaveNet, MTGNN, STID, D2STGNN, STEP, DGCRN, DGCRN, STNorm, AGCRN, GTS, StemGNN, MegaCRN, STGCN, STWave, STAEformer, GMSDR, ...
 - Informer, Autoformer, FEDformer, Pyraformer, DLinear, NLinear, Triformer, Crossformer, ...
 
-## 💿 Dependencies
-
-<details>
-  <summary><b>Preliminaries</b></summary>
-
-
-### OS
-
-We recommend using BasicTS on Linux systems (*e.g.* Ubuntu and CentOS). 
-Other systems (*e.g.*, Windows and macOS) have not been tested.
-
-### Python
-
-Python >= 3.6 (recommended >= 3.9).
-
-[Miniconda](https://docs.conda.io/en/latest/miniconda.html) or [Anaconda](https://www.anaconda.com/) are recommended to create a virtual python environment.
-
-### Other Dependencies
-</details>
-
-BasicTS is built based on PyTorch and [EasyTorch](https://github.com/cnstark/easytorch).
-You can install PyTorch following the instruction in [PyTorch](https://pytorch.org/get-started/locally/). For example:
-
-```bash
-pip install torch==1.10.0+cu111 torchvision==0.11.0+cu111 torchaudio==0.10.0 -f https://download.pytorch.org/whl/torch_stable.html
-```
-
-**After ensuring** that PyTorch is installed correctly, you can install other dependencies via:
-
-```bash
-pip install -r requirements.txt
-```
-
-### Warning
-
-BasicTS is built on PyTorch 1.9.1 or 1.10.0, while other versions have not been tested.
-
-
-## 🎯 Getting Started of Developing with BasicTS
-
-### Preparing Data
-
-- **Clone BasicTS**
+## 🚀 Installation and Quick Start
 
-    ```bash
-    cd /path/to/your/project
-    git clone https://github.com/zezhishao/BasicTS.git
-    ```
+For detailed instructions, please refer to the [Getting Started](./tutorial/getting_started.md) tutorial.
 
-- **Download Raw Data**
-
-    You can download all the raw datasets at [Google Drive](https://drive.google.com/drive/folders/14EJVODCU48fGK0FkyeVom_9lETh80Yjp) or [Baidu Yun](https://pan.baidu.com/s/10gOPtlC9M4BEjx89VD1Vbw)(password: 6v0a), and unzip them to `datasets/raw_data/`.
-
-- **Pre-process Data**
-
-    ```bash
-    cd /path/to/your/project
-    python scripts/data_preparation/${DATASET_NAME}/generate_training_data.py
-    ```
-
-    Replace `${DATASET_NAME}` with one of `METR-LA`, `PEMS-BAY`, `PEMS03`, `PEMS04`, `PEMS07`, `PEMS08`, or any other supported dataset. The processed data will be placed in `datasets/${DATASET_NAME}`.
-
-
-### 3 Steps to Evaluate Your Model
-
-- **Define Your Model Architecture**
-
-    The `forward` function needs to follow the conventions of BasicTS. You can find an example of the Multi-Layer Perceptron (`MLP`) model in [baselines/MLP/mlp_arch.py](baselines/MLP/mlp_arch.py)
-
-- **Define Your Runner for Your Model** (Optional)
-
-    BasicTS provides a unified and standard pipeline in `basicts.runner.BaseTimeSeriesForecastingRunner`.
-    Nevertheless, you still need to define the specific forward process (the `forward` function in the **runner**).
-    Fortunately, BasicTS also provides such an implementation in `basicts.runner.SimpleTimeSeriesForecastingRunner`, which can cover most of the situations.
-    The runner for the `MLP` model can also use this built-in runner.
-    You can also find more runners in `basicts.runners.runner_zoo` to learn more about the runner design.
-
-- **Configure your Configuration File**
-
-    You can configure all the details of the pipeline and hyperparameters in a configuration file, *i.e.*, **everything is based on config**.
-    The configuration file is a `.py` file, in which you can import your model and runner and set all the options. BasicTS uses `EasyDict` to serve as a parameter container, which is extensible and flexible to use.
-    An example of the configuration file for the `MLP` model on the `METR-LA` dataset can be found in [baselines/MLP/MLP_METR-LA.py](baselines/MLP/MLP_METR-LA.py)
-
-### Run It!
-
-- **Reproducing Built-in Models**
-
-  BasicTS provides a wealth of built-in models. You can reproduce these models by running the following command:
-
-  ```bash
-  python experiments/train.py -c baselines/${MODEL_NAME}/${DATASET_NAME}.py --gpus '0'
-  ```
-
-  Replace `${DATASET_NAME}` and `${MODEL_NAME}` with any supported models and datasets. For example, you can run Graph WaveNet on METR-LA dataset by:
-
-  ```bash
-  python experiments/train.py -c baselines/GWNet/METR-LA.py --gpus '0'
-  ```
-
-- **Customized Your Own Model**
+## 📉 Main Results
 
-  [Example: Multi-Layer Perceptron (MLP)](baselines/MLP)
+See the paper *[Exploring Progress in Multivariate Time Series Forecasting:
+Comprehensive Benchmarking and Heterogeneity Analysis](https://arxiv.org/pdf/2310.06119.pdf).*
 
 ## Contributors ✨
 
@@ -212,11 +134,6 @@ Thanks goes to these wonderful people ([emoji key](https://allcontributors.org/d
 
 This project follows the [all-contributors](https://github.com/all-contributors/all-contributors) specification. Contributions of any kind welcome!
 
-## 📉 Main Results
-
-See the paper *[Exploring Progress in Multivariate Time Series Forecasting:
-Comprehensive Benchmarking and Heterogeneity Analysis](https://arxiv.org/pdf/2310.06119.pdf).*
-
 ## 🔗 Acknowledgement
 
 BasicTS is developed based on [EasyTorch](https://github.com/cnstark/easytorch), an easy-to-use and powerful open-source neural network training framework.