# datawhalechina/time-series-learning architecture

> Architecture diagram of the GitHub repository datawhalechina/time-series-learning, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-14). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/datawhalechina/time-series-learning
- Repository: https://github.com/datawhalechina/time-series-learning

## Overview

1. This repository is a notebook-based learning and solution workspace for the 2021 “AI Earth” ENSO forecasting competition. It is not a packaged application; the architecture is organized as five progressively more advanced analysis/modeling tasks, each implemented in a Jupyter notebook.

2. The problem boundary is a spatiotemporal prediction pipeline: use the past 12 months of four climate variables to predict future Nino3.4 index values for horizons 1–24 months. The repository’s core technical challenge is converting multi-year gridded climate data into a model-ready tensor representation and then forecasting a long lead-time sequence.

3. Task1, “气象数据分析常用工具,” is the tooling/onboarding layer. It is meant to establish the meteorological data analysis stack and working conventions for handling climate datasets, likely including file inspection, array handling, and domain-specific preprocessing concepts. This forms the foundation for the later tasks.

4. Task2, “数据分析,” is the data understanding and exploration layer. Its role is to inspect the provided training data structure, temporal overlap, variable semantics, and sample construction. This task is where the repository explains how the raw climate fields are organized and how the Nino3.4 target relates to the input data.

5. The dataset boundary is important to the architecture. Training data comes from CMIP5, CMIP6, and SODA in NetCDF format with dimensions like year, month, lat, lon, and four channels: SST, T300, Ua, Va. Test data is provided as `.npy` tensors shaped as `(12, lat, lon, 4)`. This repo’s modeling notebooks bridge those two formats by transforming climate grids into model inputs.

6. Task3, “模型建立之 CNN+LSTM,” is the first deep learning modeling branch. It combines convolutional layers for spatial feature extraction with LSTM layers for temporal modeling, reflecting the repository’s main design pattern: separate spatial and temporal information processing, then fuse them for sequence forecasting.

7. Task4, “模型建立之 TCNN+RNN,” is an alternative model family focused on temporal convolution plus recurrent processing. It represents a second architecture path for the same prediction problem, showing the repo explores multiple ways to capture long-range dependencies while keeping the model relatively compact for the small dataset regime.

8. Task5, “模型建立之 SA-ConvLSTM,” is the most advanced modeling branch in the repo. It adds attention-aware ConvLSTM-style spatiotemporal modeling, indicating an effort to improve feature selection across both space and time and better handle the long forecast horizon.

9. The `fig/` subfolders under Tasks 3–5 are supporting assets for model explanation and visualization. They likely contain architecture diagrams, loss curves, or result plots used by the notebooks, so they belong to the presentation/analysis layer rather than the data or model code path.

10. The README is effectively the project’s architecture document: it defines the competition setting, data modality, sample construction, and evaluation metric. That metric matters architecturally because it rewards both correlation and RMSE across 24 forecast steps, so the modeling stack is designed for multi-step sequence prediction rather than single-step regression.

11. Overall data flow is: raw climate reanalysis/simulation data → exploratory analysis and preprocessing understanding → spatiotemporal tensor construction → alternative deep learning models (CNN+LSTM, TCNN+RNN, SA-ConvLSTM) → 24-month Nino3.4 predictions evaluated by a competition-specific score. The repository contains no deployment or serving layer; its boundary ends at offline experimentation and model comparison.

12. The main architectural theme is iterative competition workflow rather than software system decomposition. Each notebook is a stage in the analysis/modeling pipeline, and the repo’s value is in documenting how to move from domain data understanding to model design choices under a small-sample, long-horizon forecasting constraint.

Main entry points: [`README.md`](https://github.com/datawhalechina/time-series-learning/blob/main/README.md) (README), [`Task3/Task3 模型建立之CNN+LSTM.ipynb`](https://github.com/datawhalechina/time-series-learning/blob/HEAD/Task3/Task3%20%E6%A8%A1%E5%9E%8B%E5%BB%BA%E7%AB%8B%E4%B9%8BCNN%2BLSTM.ipynb) (CNN+LSTM), [`Task4/Task4 模型建立之TCNN+RNN.ipynb`](https://github.com/datawhalechina/time-series-learning/blob/HEAD/Task4/Task4%20%E6%A8%A1%E5%9E%8B%E5%BB%BA%E7%AB%8B%E4%B9%8BTCNN%2BRNN.ipynb) (TCNN+RNN), [`Task5/Task5 模型建立之SA-ConvLSTM.ipynb`](https://github.com/datawhalechina/time-series-learning/blob/HEAD/Task5/Task5%20%E6%A8%A1%E5%9E%8B%E5%BB%BA%E7%AB%8B%E4%B9%8BSA-ConvLSTM.ipynb) (SA-ConvLSTM)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_docs["Docs"]
  node_readme["README<br/>project brief<br/>[README.md]"]
end

subgraph group_foundation["Foundation"]
  node_task1["Task1<br/>tooling notebook"]
  node_task2["Task2<br/>analysis notebook<br/>[Task2 数据分析.ipynb]"]
  node_data_boundary[("Climate data<br/>dataset boundary")]
  node_tensor_prep["Tensor build<br/>preprocessing step"]
end

subgraph group_models["Models"]
  node_task3["CNN+LSTM<br/>model notebook"]
  node_task4["TCNN+RNN<br/>model notebook"]
  node_task5["SA-ConvLSTM<br/>model notebook"]
  node_forecast_output(("Nino3.4 forecast<br/>prediction output"))
end

subgraph group_assets["Figures"]
  node_task3_fig["Task3 figs<br/>model visuals"]
  node_task4_fig["Task4 figs<br/>model visuals"]
  node_task5_fig["Task5 figs<br/>model visuals"]
end

node_readme -->|"introduces"| node_task1
node_readme -->|"frames"| node_task2
node_readme -->|"defines"| node_data_boundary
node_task1 -->|"prepares"| node_task2
node_task2 -->|"derives"| node_tensor_prep
node_data_boundary -->|"feeds"| node_tensor_prep
node_tensor_prep -->|"supplies"| node_task3
node_tensor_prep -->|"supplies"| node_task4
node_tensor_prep -->|"supplies"| node_task5
node_task3 -->|"predicts"| node_forecast_output
node_task4 -->|"predicts"| node_forecast_output
node_task5 -->|"predicts"| node_forecast_output
node_task3 -->|"documents"| node_task3_fig
node_task4 -->|"documents"| node_task4_fig
node_task5 -->|"documents"| node_task5_fig
node_readme -->|"scores"| node_forecast_output

click node_readme "https://github.com/datawhalechina/time-series-learning/blob/main/README.md"
click node_task1 "https://github.com/datawhalechina/time-series-learning/blob/main/Task1/Task1 气象数据分析常用工具.ipynb"
click node_task2 "https://github.com/datawhalechina/time-series-learning/blob/main/Task2/Task2 数据分析.ipynb"
click node_task3 "https://github.com/datawhalechina/time-series-learning/blob/main/Task3/Task3 模型建立之CNN+LSTM.ipynb"
click node_task3_fig "https://github.com/datawhalechina/time-series-learning/tree/main/Task3/fig"
click node_task4 "https://github.com/datawhalechina/time-series-learning/blob/main/Task4/Task4 模型建立之TCNN+RNN.ipynb"
click node_task4_fig "https://github.com/datawhalechina/time-series-learning/tree/main/Task4/fig"
click node_task5 "https://github.com/datawhalechina/time-series-learning/blob/main/Task5/Task5 模型建立之SA-ConvLSTM.ipynb"
click node_task5_fig "https://github.com/datawhalechina/time-series-learning/tree/main/Task5/fig"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_readme toneBlue
class node_task1,node_task2,node_data_boundary,node_tensor_prep toneAmber
class node_task3,node_task4,node_task5,node_forecast_output toneMint
class node_task3_fig,node_task4_fig,node_task5_fig toneRose
```

## Components

### Docs

Project framing and competition rules

- [README](https://github.com/datawhalechina/time-series-learning/blob/main/README.md): project brief · Competition setting, data modality, sample construction, and scoring overview. · `README.md`

### Foundation

Tooling and data understanding

- [Task1](https://github.com/datawhalechina/time-series-learning/blob/HEAD/Task1/Task1%20%E6%B0%94%E8%B1%A1%E6%95%B0%E6%8D%AE%E5%88%86%E6%9E%90%E5%B8%B8%E7%94%A8%E5%B7%A5%E5%85%B7.ipynb): tooling notebook · Meteorological data analysis tools and working conventions for climate datasets. · `Task1/Task1 气象数据分析常用工具.ipynb`
- [Task2](https://github.com/datawhalechina/time-series-learning/blob/HEAD/Task2/Task2%20%E6%95%B0%E6%8D%AE%E5%88%86%E6%9E%90.ipynb): analysis notebook · Explores training data structure, variable semantics, and target/input relationships. · `Task2/Task2 数据分析.ipynb`
- **Climate data**: dataset boundary · NetCDF training data and .npy test tensors spanning SST, T300, Ua, and Va across space and time.
- **Tensor build**: preprocessing step · Converts gridded climate fields into model-ready spatiotemporal tensors.

### Models

Alternative forecasting branches

- [CNN+LSTM](https://github.com/datawhalechina/time-series-learning/blob/HEAD/Task3/Task3%20%E6%A8%A1%E5%9E%8B%E5%BB%BA%E7%AB%8B%E4%B9%8BCNN%2BLSTM.ipynb): model notebook · Spatial feature extraction with convolution followed by temporal sequence modeling with LSTM. · `Task3/Task3 模型建立之CNN+LSTM.ipynb`
- [TCNN+RNN](https://github.com/datawhalechina/time-series-learning/blob/HEAD/Task4/Task4%20%E6%A8%A1%E5%9E%8B%E5%BB%BA%E7%AB%8B%E4%B9%8BTCNN%2BRNN.ipynb): model notebook · Temporal convolution plus recurrent modeling for long-range dependency capture. · `Task4/Task4 模型建立之TCNN+RNN.ipynb`
- [SA-ConvLSTM](https://github.com/datawhalechina/time-series-learning/blob/HEAD/Task5/Task5%20%E6%A8%A1%E5%9E%8B%E5%BB%BA%E7%AB%8B%E4%B9%8BSA-ConvLSTM.ipynb): model notebook · Attention-aware spatiotemporal ConvLSTM branch for long-horizon forecasting. · `Task5/Task5 模型建立之SA-ConvLSTM.ipynb`
- **Nino3.4 forecast**: prediction output · 24-step monthly prediction target evaluated by the competition score.

### Figures

Supporting visual assets

- [Task3 figs](https://github.com/datawhalechina/time-series-learning/tree/main/Task3/fig): model visuals · Architecture and result figures supporting the CNN+LSTM notebook. · `Task3/fig`
- [Task4 figs](https://github.com/datawhalechina/time-series-learning/tree/main/Task4/fig): model visuals · Architecture and result figures supporting the TCNN+RNN notebook. · `Task4/fig`
- [Task5 figs](https://github.com/datawhalechina/time-series-learning/tree/main/Task5/fig): model visuals · Architecture and result figures supporting the SA-ConvLSTM notebook. · `Task5/fig`

## Connections

- README → Task1: introduces · Sets up the workflow with analysis tools.
- README → Task2: frames · Explains the data and target structure.
- README → Climate data: defines · Describes the climate data and tensor formats.
- Task1 → Task2: prepares · Tooling and conventions support later analysis.
- Task2 → Tensor build: derives · Turns exploration into model-ready representations.
- Climate data → Tensor build: feeds · Raw NetCDF and .npy inputs are transformed for modeling.
- Tensor build → CNN+LSTM: supplies · Prepared tensors enter the CNN+LSTM branch.
- Tensor build → TCNN+RNN: supplies · Prepared tensors enter the TCNN+RNN branch.
- Tensor build → SA-ConvLSTM: supplies · Prepared tensors enter the SA-ConvLSTM branch.
- CNN+LSTM → Nino3.4 forecast: predicts · Produces multi-step Nino3.4 forecasts.
- TCNN+RNN → Nino3.4 forecast: predicts · Produces multi-step Nino3.4 forecasts.
- SA-ConvLSTM → Nino3.4 forecast: predicts · Produces multi-step Nino3.4 forecasts.
- CNN+LSTM → Task3 figs: documents · Uses supporting figures for explanation and results.
- TCNN+RNN → Task4 figs: documents · Uses supporting figures for explanation and results.
- SA-ConvLSTM → Task5 figs: documents · Uses supporting figures for explanation and results.
- README → Nino3.4 forecast: scores · Describes the competition metric and evaluation horizon.