# oliverguhr/transformer-time-series-prediction architecture

> Architecture diagram of the GitHub repository oliverguhr/transformer-time-series-prediction, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-12). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/oliverguhr/transformer-time-series-prediction
- Repository: https://github.com/oliverguhr/transformer-time-series-prediction

## Overview

##### Project type and purpose
- This is a proof-of-concept machine learning pipeline for time series forecasting.
- It provides two scripts:
- transformer-singlestep.py (single-step forecast)
- transformer-multistep.py (multi-step forecast)

##### File structure
- Top-level files:
- daily-min-temperatures.csv – raw dataset
- requirements.txt – Python dependencies (PyTorch, pandas, matplotlib, etc.)
- transformer-*.py – core training/inference entry points
- docs/ – output visualizations (GIF, PNG)
- graph/ – placeholder for visualization exports

##### Extract insights from the README
- Data is loaded from CSV, preprocessed, windowed into sequences.
- A PyTorch Transformer model is trained and then used for inference.
- Outputs are plotted and saved under docs/.

##### Main components
a. Data Ingestion & Storage
- CSV file → pandas DataFrame → sliding-window dataset
b. Preprocessing Module
- Normalization/Scaling
- Sequence windowing (input_length → target_length)
c. Model Training Module
- PyTorch DataLoader
- Transformer architecture (encoder, decoder)
- Training loop (loss calc, backprop, optimizer)
d. Model Inference Module
- Load trained weights
- Single-step vs. multi-step differ in decoder usage
e. Evaluation & Visualization
- Matplotlib for plotting predictions vs. actual
- Export to docs/ (GIF, PNG)
f. Configuration & Dependencies
- requirements.txt for environment setup

##### Relationships and data flow
- Preprocessing → Training DataLoader → Model Training
- Model Training → Trained Model Artifact
- Trained Model → Inference Module
- Inference → Visualization → docs/

##### Architectural patterns and design principles
- Modular pipeline: clear separation of data, model, and visualization
- Reusability: same preprocessing code for both single‐ and multi‐step scripts
- Extensibility: graph/ directory for adding new visual outputs

##### Relevant technologies & frameworks
- Python 3.x
- PyTorch (torch, torch.nn, torch.optim)
- pandas (data loading & windowing)
- matplotlib or seaborn for plotting

## Diagram (Mermaid)

```mermaid
graph TB
    %% Entry Points
    Entry1["transformer-singlestep.py"]:::entry
    Entry2["transformer-multistep.py"]:::entry

    %% Configuration & Documentation
    Requirements["requirements.txt"]:::config
    Readme["readme.md"]:::config

    %% Data Layer
    CSV["daily-min-temperatures.csv"]:::data

    %% Processing Layer
    Preproc["Preprocessing Module\n(normalization & windowing)"]:::compute
    DataLoader["PyTorch DataLoader"]:::compute

    %% Model Layer
    Training["Model Training\n(Transformer Encoder/Decoder)"]:::compute
    TrainedModel["Trained Weights"]:::compute
    Inference["Model Inference Module"]:::compute

    %% Output Layer
    Visualization["Evaluation & Visualization"]:::output
    Docs["docs/"]:::output
    GraphExt["graph/"]:::output

    %% Connections
    CSV -->|"raw data"| Preproc
    Preproc -->|"windowed sequences"| DataLoader
    DataLoader -->|"batches"| Training
    Training -->|"trained weights"| TrainedModel
    TrainedModel -->|"weights"| Inference
    Entry1 --> Preproc
    Entry1 --> Training
    Entry1 --> Inference
    Entry2 --> Preproc
    Entry2 --> Training
    Entry2 --> Inference
    Inference -->|"predictions"| Visualization
    Visualization -->|"output files"| Docs
    GraphExt -.-> Visualization
    Requirements -.-> Entry1
    Requirements -.-> Entry2
    Readme -.-> CSV
    Readme -.-> Preproc
    Readme -.-> Training
    Readme -.-> Visualization

    %% Click Events
    click CSV "https://github.com/oliverguhr/transformer-time-series-prediction/blob/master/daily-min-temperatures.csv"
    click Entry1 "https://github.com/oliverguhr/transformer-time-series-prediction/blob/master/transformer-singlestep.py"
    click Entry2 "https://github.com/oliverguhr/transformer-time-series-prediction/blob/master/transformer-multistep.py"
    click Requirements "https://github.com/oliverguhr/transformer-time-series-prediction/blob/master/requirements.txt"
    click Readme "https://github.com/oliverguhr/transformer-time-series-prediction/blob/master/readme.md"
    click Docs "https://github.com/oliverguhr/transformer-time-series-prediction/tree/master/docs/"
    click GraphExt "https://github.com/oliverguhr/transformer-time-series-prediction/tree/master/graph/"
    click Training "https://github.com/oliverguhr/transformer-time-series-prediction/blob/master/transformer-singlestep.py"
    click Training "https://github.com/oliverguhr/transformer-time-series-prediction/blob/master/transformer-multistep.py"
    click Preproc "https://github.com/oliverguhr/transformer-time-series-prediction/blob/master/transformer-singlestep.py"
    click Preproc "https://github.com/oliverguhr/transformer-time-series-prediction/blob/master/transformer-multistep.py"
    click Inference "https://github.com/oliverguhr/transformer-time-series-prediction/blob/master/transformer-singlestep.py"
    click Inference "https://github.com/oliverguhr/transformer-time-series-prediction/blob/master/transformer-multistep.py"

    %% Styles
    classDef data fill:#AED6F1,stroke:#1B4F72,color:#154360;
    classDef compute fill:#A9DFBF,stroke:#196F3D,color:#145A32;
    classDef output fill:#F9E79F,stroke:#B7950B,color:#7D6608;
    classDef config fill:#D7DBDD,stroke:#979A9A,color:#515A5A;
    classDef entry fill:#E8DAEF,stroke:#7D3C98,color:#512E5F;
```
