# thuml/timexer architecture

> Architecture diagram of the GitHub repository thuml/timexer, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-10-16). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/thuml/timexer
- Repository: https://github.com/thuml/timexer

## Overview

##### Project Type and Purpose
- This is a PyTorch‐based machine‐learning research repository implementing “TimeXer,” a Transformer variant for time‐series forecasting with exogenous variables.
- Purpose: ingest endogenous series plus exogenous signals, train/evaluate on benchmarks (EPF, ETTh, Weather, etc.), produce results and figures.

##### File Structure Analysis
- Top‐level directories:
- data_provider: factories and loaders for different dataset formats (M4, UEA, custom CSVs)
- dataset: raw CSV data (e.g., ./dataset/EPF/*.csv)
- layers: low‐level neural network building blocks (attention, convolution, normalization, etc.)
- models: high‐level architectures (TimeXer, Autoformer, Informer, etc.) each wrapping layer components
- exp: experiment driver scripts written in Python, one per task (classification, forecasting, imputation, etc.)
- scripts: shell wrappers to run experiments on specific datasets via run.py
- utils: helper modules (metrics, losses, augmentation, time features, argument parsing)
- figures: embedded PNGs for documentation
- run.py: central entry point that glues data loading, model instantiation, training loop, evaluation
- requirements.txt: dependency list

- Patterns:
- Modular separation between data ingestion, preprocessing, model definition, experiment orchestration.
- Experiment folder mirrors high‐level use cases.
- Script folder provides reproducible bash commands per dataset.

##### README Insights
a. Patch‐level representation for endogenous series
b. Variate‐level representation for exogenous variables
c. Global endogenous token bridging the two
- Dependencies: PyTorch and common scientific Python libraries.
- Workflow: data → preprocessing → model training → evaluation → result figures.

a. Main Components
1. Data Layer
- Local CSV files (./dataset)
- External sources (M4, UEA via data_provider)
2. Preprocessing & Augmentation
- data_provider/data_loader.py
- utils/timefeatures.py, utils/augmentation.py, utils/masking.py
3. Model Layer
- Embedding modules (layers/Embed.py)
- Correlation modules (Patch, Fourier, Wavelet, AutoCorrelation, etc.)
- Transformer encoders/decoders (layers/*_EncDec.py)
- TimeXer wrapper (models/TimeXer.py) among other model classes
4. Training & Orchestration
- run.py: sets up configurations, instantiates datasets and models, kicks off training loop
- exp/*.py: experiment definitions per task
- scripts/*/*.sh: dataset‐specific invocation scripts
5. Evaluation & Results
- utils/metrics.py, utils/losses.py
- figures/: saves and stores result plots
6. External Services
- Google/Baidu Drive for large external datasets
- PyTorch ecosystem

b. Relationships & Data Flow

c. Architectural Patterns & Principles
- Pipeline pattern: clear flow from data ingestion to result plotting
- Modular layering: low‐level layers assemble into high‐level model classes
- Experiment reproducibility: bash scripts tied to specific datasets
- Separation of concerns: data, model, training loop, utilities all in dedicated modules

d. Key Technologies & Frameworks
- Python 3.x, PyTorch (core DL framework)
- Numpy, Pandas (data manipulation)
- Bash scripting for orchestration
- Matplotlib/Seaborn (implied for figure generation)

##### Capturing Essential Architectural Elements
- Don’t omit the experiment folder or script folder—they’re critical for reproducibility.
- Central “TimeXer Model” block with its sub‐layers, since that’s the core contribution.
- Metrics/loss utilities feeding back into training for monitoring.
- External data sources and dependency on PyTorch.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Data Layer
    subgraph "Data Layer"
        direction TB
        D1[(dataset/)]:::data
        subgraph "data_provider"
            direction TB
            DF["data_factory.py"]:::data
            DL["data_loader.py"]:::data
            M4["m4.py"]:::data
            UEA["uea.py"]:::data
        end
    end
    ext1(("Cloud Storage")):::external

    ext1 --> DF
    ext1 --> DL
    ext1 --> M4
    ext1 --> UEA
    D1 --> DF
    D1 --> DL
    D1 --> M4
    D1 --> UEA

    %% Preprocessing & Augmentation
    subgraph "Preprocessing & Augmentation"
        direction TB
        A1["augmentation.py"]:::pre
        A2["timefeatures.py"]:::pre
        A3["masking.py"]:::pre
    end
    DF --> A1
    DL --> A1
    M4 --> A1
    UEA --> A1
    DF --> A2
    DL --> A2
    M4 --> A2
    UEA --> A2
    DF --> A3
    DL --> A3
    M4 --> A3
    UEA --> A3

    %% Model Layer
    subgraph "Model Layer"
        direction TB
        subgraph "Layers"
            direction TB
            E1["Embed.py"]:::model
            C1["AutoCorrelation.py"]:::model
            C2["FourierCorrelation.py"]:::model
            C3["MultiWaveletCorrelation.py"]:::model
            T1["Transformer_EncDec.py"]:::model
            T2["Autoformer_EncDec.py"]:::model
            T3["Crossformer_EncDec.py"]:::model
            T4["ETSformer_EncDec.py"]:::model
            T5["Pyraformer_EncDec.py"]:::model
        end
        MX["TimeXer.py"]:::model
    end
    A1 --> MX
    A2 --> MX
    A3 --> MX
    E1 --> MX
    C1 --> MX
    C2 --> MX
    C3 --> MX
    T1 --> MX
    T2 --> MX
    T3 --> MX
    T4 --> MX
    T5 --> MX

    %% Orchestration
    subgraph "Orchestration"
        direction TB
        R1(["run.py"]):::orch
        subgraph "Experiments"
            direction TB
            EX1["exp_short_term_forecasting.py"]:::orch
            EX2["exp_long_term_forecasting.py"]:::orch
            EX3["exp_classification.py"]:::orch
            EX4["exp_imputation.py"]:::orch
            EX5["exp_anomaly_detection.py"]:::orch
            EX6["exp_basic.py"]:::orch
        end
        subgraph "Scripts"
            direction TB
            S1["forecast_exogenous/TimeXer.sh"]:::orch
            S2["multivariate/TimeXer.sh"]:::orch
        end
    end
    S1 -.-> R1
    S2 -.-> R1
    R1 --> EX1
    R1 --> EX2
    R1 --> EX3
    R1 --> EX4
    R1 --> EX5
    R1 --> EX6
    EX1 --> MX
    EX2 --> MX
    EX3 --> MX
    EX4 --> MX
    EX5 --> MX
    EX6 --> MX

    %% Evaluation & Results
    subgraph "Evaluation & Results"
        direction TB
        U1["metrics.py"]:::out
        U2["losses.py"]:::out
        F1[(figures/)]:::out
    end
    MX --> U1
    MX --> U2
    U1 --> F1
    U2 --> F1

    %% Click Events
    click D1 "https://github.com/thuml/timexer/tree/main/dataset/"
    click DF "https://github.com/thuml/timexer/blob/main/data_provider/data_factory.py"
    click DL "https://github.com/thuml/timexer/blob/main/data_provider/data_loader.py"
    click M4 "https://github.com/thuml/timexer/blob/main/data_provider/m4.py"
    click UEA "https://github.com/thuml/timexer/blob/main/data_provider/uea.py"
    click A1 "https://github.com/thuml/timexer/blob/main/utils/augmentation.py"
    click A2 "https://github.com/thuml/timexer/blob/main/utils/timefeatures.py"
    click A3 "https://github.com/thuml/timexer/blob/main/utils/masking.py"
    click E1 "https://github.com/thuml/timexer/blob/main/layers/Embed.py"
    click C1 "https://github.com/thuml/timexer/blob/main/layers/AutoCorrelation.py"
    click C2 "https://github.com/thuml/timexer/blob/main/layers/FourierCorrelation.py"
    click C3 "https://github.com/thuml/timexer/blob/main/layers/MultiWaveletCorrelation.py"
    click T1 "https://github.com/thuml/timexer/blob/main/layers/Transformer_EncDec.py"
    click T2 "https://github.com/thuml/timexer/blob/main/layers/Autoformer_EncDec.py"
    click T3 "https://github.com/thuml/timexer/blob/main/layers/Crossformer_EncDec.py"
    click T4 "https://github.com/thuml/timexer/blob/main/layers/ETSformer_EncDec.py"
    click T5 "https://github.com/thuml/timexer/blob/main/layers/Pyraformer_EncDec.py"
    click MX "https://github.com/thuml/timexer/blob/main/models/TimeXer.py"
    click EX1 "https://github.com/thuml/timexer/blob/main/exp/exp_short_term_forecasting.py"
    click EX2 "https://github.com/thuml/timexer/blob/main/exp/exp_long_term_forecasting.py"
    click EX3 "https://github.com/thuml/timexer/blob/main/exp/exp_classification.py"
    click EX4 "https://github.com/thuml/timexer/blob/main/exp/exp_imputation.py"
    click EX5 "https://github.com/thuml/timexer/blob/main/exp/exp_anomaly_detection.py"
    click EX6 "https://github.com/thuml/timexer/blob/main/exp/exp_basic.py"
    click R1 "https://github.com/thuml/timexer/blob/main/run.py"
    click S1 "https://github.com/thuml/timexer/blob/main/scripts/forecast_exogenous/TimeXer.sh"
    click S2 "https://github.com/thuml/timexer/blob/main/scripts/multivariate/TimeXer.sh"
    click U1 "https://github.com/thuml/timexer/blob/main/utils/metrics.py"
    click U2 "https://github.com/thuml/timexer/blob/main/utils/losses.py"
    click F1 "https://github.com/thuml/timexer/tree/main/figures/"

    %% Styles
    classDef data fill:#ADD8E6,stroke:#000,stroke-width:1px
    classDef pre fill:#E0FFFF,stroke:#000,stroke-width:1px
    classDef model fill:#98FB98,stroke:#000,stroke-width:1px
    classDef orch fill:#FFA500,stroke:#000,stroke-width:1px
    classDef out fill:#FF00FF,stroke:#000,stroke-width:1px
    classDef external fill:#D3D3D3,stroke:#000,stroke-width:1px,stroke-dasharray: 5 5
```
