# rajatsen91/deepglo architecture

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

- Interactive diagram: https://gitdiagram.com/rajatsen91/deepglo
- Repository: https://github.com/rajatsen91/deepglo

## Overview

1. **Repository purpose**
   - This is a research codebase for reproducing the DeepGLO paper’s forecasting experiments, not a general-purpose application or service. The main concern is training and evaluating time-series models on benchmark datasets.

2. **Top-level structure**
   - The repo splits into three practical areas:
     - `DeepGLO/`: reusable model and support library
     - `run_scripts/`: dataset-specific experiment entrypoints
     - `datasets/`: data acquisition and reshaping utilities

3. **Core model orchestration**
   - `DeepGLO/DeepGLO.py` is the central coordination layer. It likely exposes the main model class that wires together preprocessing, the local learner, and the broader forecasting logic.
   - This is the main boundary for training and prediction: scripts call into this module rather than constructing components directly.

4. **Local temporal model**
   - `DeepGLO/LocalModel.py` implements the TCN-based “LeveledInit” local model mentioned in the README.
   - Architecturally, this is the short-horizon sequence learner that handles temporal pattern extraction on the raw or normalized series.

5. **Global/auxiliary modeling**
   - `DeepGLO/Ftree.py` appears to support the global side of the method, likely a factor/tree-style structure used by the overall DeepGLO algorithm.
   - In the architecture diagram, treat this as the complementary model component that operates across series or captures shared structure beyond the local TCN.

6. **Data loading and preprocessing**
   - `DeepGLO/data_loader.py` is the ingestion boundary between dataset files and model-ready tensors/arrays.
   - `DeepGLO/time.py` likely handles time indexing, windowing, or calendar-related transformations.
   - `DeepGLO/utilities.py` contains shared helpers used across data preparation, training, and evaluation.

7. **Evaluation layer**
   - `DeepGLO/metrics.py` centralizes forecast scoring, which is important because the repo is designed for reproducing paper results.
   - The evaluation flow is typically: model predictions → metrics module → reported results.

8. **Experiment entrypoints**
   - `run_scripts/run_electricity.py`, `run_pems.py`, `run_traffic.py`, and `run_wiki.py` are dataset-specific drivers.
   - These scripts are the user-facing orchestration layer: they load a dataset, configure normalization and model settings, run training/inference, and print or save results.

9. **Dataset preparation boundary**
   - `datasets/download-data.sh` fetches the raw benchmark data.
   - `datasets/reshape_data.py` converts downloaded data into the format expected by the loaders and experiment scripts.
   - This means the repo has a clear offline preprocessing step before model training begins.

10. **Data flow**
   - The main flow is: raw benchmark data → download/reshape scripts → loaders/time utilities → `DeepGLO` model wrapper → `LocalModel` plus global component → metrics.
   - The run scripts sit at the top of this pipeline and choose dataset-specific parameters and normalization mode.

11. **Runtime and dependencies**
   - The code expects **PyTorch with CUDA** for training, which makes GPU execution a core architectural assumption.
   - Supporting packages (`numpy`, `scipy`, `pandas`, `scikit-learn`, `matplotlib`) indicate a scientific Python pipeline with preprocessing, evaluation, and result visualization.

12. **How to diagram it**
   - A good architecture diagram would show:
     - dataset preparation on the left,
     - the `run_scripts` layer as the entrypoint,
     - `DeepGLO` as the central orchestration package,
     - `LocalModel` and the global component as internal model branches,
     - and `metrics` as the output/evaluation sink.
   - This is a single-machine research pipeline rather than a distributed or service-oriented system.

Main entry points: [`DeepGLO/DeepGLO.py`](https://github.com/rajatsen91/deepglo/blob/master/DeepGLO/DeepGLO.py) (DeepGLO core), [`DeepGLO/data_loader.py`](https://github.com/rajatsen91/deepglo/blob/master/DeepGLO/data_loader.py) (Data loader), [`DeepGLO/__init__.py`](https://github.com/rajatsen91/deepglo/blob/master/DeepGLO/__init__.py) (Package init), [`run_scripts/run_electricity.py`](https://github.com/rajatsen91/deepglo/blob/master/run_scripts/run_electricity.py) (Electricity run)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_prep["Dataset prep"]
  node_datasets_download["Download data<br/>bash script<br/>[download-data.sh]"]
  node_datasets_reshape["Reshape data<br/>python script<br/>[reshape_data.py]"]
end

subgraph group_entry["Experiments"]
  node_run_electricity["Electricity run<br/>experiment script<br/>[run_electricity.py]"]
  node_run_pems["PEMS run<br/>experiment script<br/>[run_pems.py]"]
  node_run_traffic["Traffic run<br/>experiment script<br/>[run_traffic.py]"]
  node_run_wiki["Wiki run<br/>experiment script<br/>[run_wiki.py]"]
end

subgraph group_core["DeepGLO package"]
  node_deepglo_wrapper["DeepGLO core<br/>model orchestrator<br/>[DeepGLO.py]"]
  node_data_loader["Data loader<br/>ingestion layer<br/>[data_loader.py]"]
  node_time_utils["Time utils<br/>sequence utilities<br/>[time.py]"]
  node_utilities["Shared utils<br/>helpers<br/>[utilities.py]"]
  node_local_model["Local model<br/>TCN learner<br/>[LocalModel.py]"]
  node_ftree["Global model<br/>shared-structure model<br/>[Ftree.py]"]
  node_metrics["Metrics<br/>evaluation<br/>[metrics.py]"]
  node_deepglo_init["Package init<br/>package export<br/>[__init__.py]"]
end

node_datasets_download -->|"raw data"| node_datasets_reshape
node_datasets_reshape -->|"prepared files"| node_data_loader
node_run_electricity -->|"configure/train"| node_deepglo_wrapper
node_run_pems -->|"configure/train"| node_deepglo_wrapper
node_run_traffic -->|"configure/train"| node_deepglo_wrapper
node_run_wiki -->|"configure/train"| node_deepglo_wrapper
node_run_electricity -->|"load data"| node_data_loader
node_run_pems -->|"load data"| node_data_loader
node_run_traffic -->|"load data"| node_data_loader
node_run_wiki -->|"load data"| node_data_loader
node_deepglo_wrapper -->|"local branch"| node_local_model
node_deepglo_wrapper -->|"global branch"| node_ftree
node_deepglo_wrapper -->|"time features"| node_time_utils
node_deepglo_wrapper -->|"shared helpers"| node_utilities
node_deepglo_wrapper -->|"evaluate"| node_metrics
node_data_loader -->|"index windows"| node_time_utils
node_data_loader -->|"prep helpers"| node_utilities
node_deepglo_init -->|"exports"| node_deepglo_wrapper
node_deepglo_init -->|"exports"| node_local_model
node_deepglo_init -->|"exports"| node_ftree

click node_datasets_download "https://github.com/rajatsen91/deepglo/blob/master/datasets/download-data.sh"
click node_datasets_reshape "https://github.com/rajatsen91/deepglo/blob/master/datasets/reshape_data.py"
click node_run_electricity "https://github.com/rajatsen91/deepglo/blob/master/run_scripts/run_electricity.py"
click node_run_pems "https://github.com/rajatsen91/deepglo/blob/master/run_scripts/run_pems.py"
click node_run_traffic "https://github.com/rajatsen91/deepglo/blob/master/run_scripts/run_traffic.py"
click node_run_wiki "https://github.com/rajatsen91/deepglo/blob/master/run_scripts/run_wiki.py"
click node_deepglo_wrapper "https://github.com/rajatsen91/deepglo/blob/master/DeepGLO/DeepGLO.py"
click node_data_loader "https://github.com/rajatsen91/deepglo/blob/master/DeepGLO/data_loader.py"
click node_time_utils "https://github.com/rajatsen91/deepglo/blob/master/DeepGLO/time.py"
click node_utilities "https://github.com/rajatsen91/deepglo/blob/master/DeepGLO/utilities.py"
click node_local_model "https://github.com/rajatsen91/deepglo/blob/master/DeepGLO/LocalModel.py"
click node_ftree "https://github.com/rajatsen91/deepglo/blob/master/DeepGLO/Ftree.py"
click node_metrics "https://github.com/rajatsen91/deepglo/blob/master/DeepGLO/metrics.py"
click node_deepglo_init "https://github.com/rajatsen91/deepglo/blob/master/DeepGLO/__init__.py"

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_datasets_download,node_datasets_reshape toneBlue
class node_run_electricity,node_run_pems,node_run_traffic,node_run_wiki toneAmber
class node_deepglo_wrapper,node_data_loader,node_time_utils,node_utilities,node_local_model,node_ftree,node_metrics,node_deepglo_init toneMint
```

## Components

### Dataset prep

Offline acquisition and reshaping of benchmark time-series data.

- [Download data](https://github.com/rajatsen91/deepglo/blob/master/datasets/download-data.sh): bash script · Fetches raw benchmark datasets before experimentation. · `datasets/download-data.sh`
- [Reshape data](https://github.com/rajatsen91/deepglo/blob/master/datasets/reshape_data.py): python script · Converts downloaded data into loader-friendly experiment format. · `datasets/reshape_data.py`

### Experiments

Dataset-specific entrypoints that configure and launch runs.

- [Electricity run](https://github.com/rajatsen91/deepglo/blob/master/run_scripts/run_electricity.py): experiment script · Entrypoint for the electricity forecasting benchmark. · `run_scripts/run_electricity.py`
- [PEMS run](https://github.com/rajatsen91/deepglo/blob/master/run_scripts/run_pems.py): experiment script · Entrypoint for the PEMS forecasting benchmark. · `run_scripts/run_pems.py`
- [Traffic run](https://github.com/rajatsen91/deepglo/blob/master/run_scripts/run_traffic.py): experiment script · Entrypoint for the traffic forecasting benchmark. · `run_scripts/run_traffic.py`
- [Wiki run](https://github.com/rajatsen91/deepglo/blob/master/run_scripts/run_wiki.py): experiment script · Entrypoint for the Wikipedia forecasting benchmark. · `run_scripts/run_wiki.py`

### DeepGLO package

Reusable model, loading, timing, and evaluation code.

- [DeepGLO core](https://github.com/rajatsen91/deepglo/blob/master/DeepGLO/DeepGLO.py): model orchestrator · Main coordination layer that wires preprocessing, local modeling, and overall forecasting logic. · `DeepGLO/DeepGLO.py`
- [Data loader](https://github.com/rajatsen91/deepglo/blob/master/DeepGLO/data_loader.py): ingestion layer · Loads prepared datasets into model-ready arrays and tensors. · `DeepGLO/data_loader.py`
- [Time utils](https://github.com/rajatsen91/deepglo/blob/master/DeepGLO/time.py): sequence utilities · Handles windowing, time indexing, or calendar-related transformations. · `DeepGLO/time.py`
- [Shared utils](https://github.com/rajatsen91/deepglo/blob/master/DeepGLO/utilities.py): helpers · Common helper functions used across training, preprocessing, and evaluation. · `DeepGLO/utilities.py`
- [Local model](https://github.com/rajatsen91/deepglo/blob/master/DeepGLO/LocalModel.py): TCN learner · LeveledInit temporal learner for short-horizon pattern extraction. · `DeepGLO/LocalModel.py`
- [Global model](https://github.com/rajatsen91/deepglo/blob/master/DeepGLO/Ftree.py): shared-structure model · Complementary component that captures cross-series structure in DeepGLO. · `DeepGLO/Ftree.py`
- [Metrics](https://github.com/rajatsen91/deepglo/blob/master/DeepGLO/metrics.py): evaluation · Centralizes forecast scoring and result reporting. · `DeepGLO/metrics.py`
- [Package init](https://github.com/rajatsen91/deepglo/blob/master/DeepGLO/__init__.py): package export · Package surface for importing DeepGLO components. · `DeepGLO/__init__.py`

## Connections

- Download data → Reshape data: raw data · Downloaded benchmark files are reshaped before use.
- Reshape data → Data loader: prepared files · Reshaped datasets are consumed by the loader boundary.
- Electricity run → DeepGLO core: configure/train · Dataset script instantiates and runs the model pipeline.
- PEMS run → DeepGLO core: configure/train · Dataset script instantiates and runs the model pipeline.
- Traffic run → DeepGLO core: configure/train · Dataset script instantiates and runs the model pipeline.
- Wiki run → DeepGLO core: configure/train · Dataset script instantiates and runs the model pipeline.
- Electricity run → Data loader: load data · Entrypoints use the ingestion layer to obtain model inputs.
- PEMS run → Data loader: load data · Entrypoints use the ingestion layer to obtain model inputs.
- Traffic run → Data loader: load data · Entrypoints use the ingestion layer to obtain model inputs.
- Wiki run → Data loader: load data · Entrypoints use the ingestion layer to obtain model inputs.
- DeepGLO core → Local model: local branch · Core wrapper delegates short-horizon learning to the TCN-based local model.
- DeepGLO core → Global model: global branch · Core wrapper combines the complementary cross-series component.
- DeepGLO core → Time utils: time features · Wrapper uses time indexing and windowing utilities.
- DeepGLO core → Shared utils: shared helpers · Wrapper relies on common helper functions.
- DeepGLO core → Metrics: evaluate · Predictions are scored through the metrics layer.
- Data loader → Time utils: index windows · Loader depends on time utilities for sequence shaping.
- Data loader → Shared utils: prep helpers · Loader shares helper functions for preprocessing.
- Package init → DeepGLO core: exports · Package init exposes the main model API.
- Package init → Local model: exports · Package init exposes the local model component.
- Package init → Global model: exports · Package init exposes the global component.