# zhangchenhaobest/tfb_time_series_forecasting_methods architecture

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

- Interactive diagram: https://gitdiagram.com/zhangchenhaobest/tfb_time_series_forecasting_methods
- Repository: https://github.com/zhangchenhaobest/tfb_time_series_forecasting_methods

## Overview

##### Project type and purpose
- TFB is an open-source Python library and benchmarking framework for time-series forecasting research.
- It provides:
- A unified pipeline for data ingestion, model execution, and evaluation
- A registry of baseline forecasting methods
- Evaluation strategies (fixed/rolling forecasts) and metrics
- Reporting outputs (CSV and a Dash dashboard)
- Utility scripts and a Docker container for reproducible experiments

##### File structure
- Top-level artifacts:
- Dockerfile, requirements.txt / requirements-docker.txt → containerization & dependencies
- config/*.json → evaluation and forecasting configurations (horizon, window, strategy)
- scripts/ → shell wrappers invoking experiments by dataset & model
- characteristics_extractor/ → standalone module computing time-series characteristics
- docs/ → static figures, tutorials, API docs links
- ts_benchmark/ → core Python package
- ts_benchmark package submodules:
- data/ → data loaders, dataset definitions, server and pool abstractions
- baselines/ → implementations of forecasting methods organized by algorithm
- evaluation/ → metric computations, evaluation strategies (fixed, rolling)
- models/ → model loader and base class
- pipeline.py → orchestration of load→train→predict→evaluate
- recording.py → experiment logging
- report/ → CSV report and Dash web app for leaderboard and queries
- utils/ → common utilities, parallel backends, design patterns

##### README for additional insights
- The “Pipeline.png” figure shows:
CLI → Pipeline → DataLoader → Model → Strategy → Metrics → Report
- Emphasizes fairness (no drop-last), extensibility (add new baselines), reproducibility (scripts + Docker)

a. Main components
- CLI Entry Point / Scripts (shell wrappers)
- Configuration Loader (reads JSON configs)
- Characteristics Extractor (optional feature module)
- Pipeline Orchestrator (ts_benchmark/pipeline.py)
- Data Layer (ts_benchmark/data)
- Model Registry & Loader (ts_benchmark/models + baselines)
- Evaluation Strategies & Metrics (ts_benchmark/evaluation)
- Reporting Engine (CSV reports + Dash app)
- External Runtimes (PyTorch, Docker container, Browser for Dash)
b. Relationships & Data flows
1. User runs a script or CLI → passes config-path, model name, dataset names →
2. Pipeline loads configuration → invokes DataLoader to fetch data →
3. (Optionally) Characteristics Extractor processes raw series →
4. Model Loader instantiates a baseline or user model →
5. Pipeline runs training / forecasting with chosen Evaluation Strategy →
6. Evaluation computes Metrics →
7. Reporting writes CSV and pushes results to Dash memory →
8. Dash app serves leaderboard UI
9. Recording module logs experiment metadata
c. Architectural patterns & design principles
- Strategy pattern for evaluation (fixed vs. rolling forecast)
- Plugin / registry pattern for baseline methods
- Factory for model instantiation via string identifiers
- Separation of concerns: data ←→ model ←→ evaluation ←→ reporting
- Containerized deployment for reproducibility (Dockerfile)
d. Key technologies & libraries
- Python 3.8+
- PyTorch 2.4.1 (model backends)
- Ray / sequential backends for parallel execution (ts_benchmark/utils/parallel)
- Plotly Dash for interactive leaderboard (ts_benchmark/report/report_dash)
- JSON for configuration (config/*.json)
- Shell scripts for experiment orchestration (scripts/)

##### Elements
- Blue for core modules (ts_benchmark/*)
- Green for data-related (data loaders, characteristics)
- Orange for evaluation & metrics
- Purple for reporting (CSV & Dash)
- Grey for external runtimes and containers (Docker, PyTorch, Browser)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% CLI Entry Point
    CLI["CLI Entry Point\n(scripts/run_benchmark.py)"]:::external
    click CLI "https://github.com/zhangchenhaobest/tfb_time_series_forecasting_methods/blob/master/scripts/run_benchmark.py"

    %% Configuration Loader
    Config["Configuration Loader\n(config/)"]:::core
    click Config "https://github.com/zhangchenhaobest/tfb_time_series_forecasting_methods/tree/master/config/"

    %% Characteristics Extractor (optional)
    CharExt["Characteristics Extractor\n(Characteristics_Extractor.py)"]:::data
    click CharExt "https://github.com/zhangchenhaobest/tfb_time_series_forecasting_methods/blob/master/characteristics_extractor/Characteristics_Extractor.py"

    %% Core Pipeline
    Pipeline["Pipeline Orchestrator\n(pipeline.py)"]:::core
    click Pipeline "https://github.com/zhangchenhaobest/tfb_time_series_forecasting_methods/blob/master/ts_benchmark/pipeline.py"

    %% Data Layer
    Data["Data Layer\n(ts_benchmark/data/)"]:::data
    click Data "https://github.com/zhangchenhaobest/tfb_time_series_forecasting_methods/tree/master/ts_benchmark/data/"

    %% Models Subgraph
    subgraph "Model Registry & Loader"
        ModelLoader["Model Loader\n(model_loader.py)"]:::core
        Baselines["Baselines Registry\n(ts_benchmark/baselines/)"]:::core
    end
    click ModelLoader "https://github.com/zhangchenhaobest/tfb_time_series_forecasting_methods/blob/master/ts_benchmark/models/model_loader.py"
    click Baselines "https://github.com/zhangchenhaobest/tfb_time_series_forecasting_methods/tree/master/ts_benchmark/baselines/"

    %% Evaluation Subgraph
    subgraph "Evaluation Strategies & Metrics"
        Strat["Evaluation Strategies\n(strategy/)"]:::eval
        Metrics["Metrics Module\n(metrics/)"]:::eval
    end
    click Strat "https://github.com/zhangchenhaobest/tfb_time_series_forecasting_methods/tree/master/ts_benchmark/evaluation/strategy/"
    click Metrics "https://github.com/zhangchenhaobest/tfb_time_series_forecasting_methods/tree/master/ts_benchmark/evaluation/metrics/"

    %% Reporting Subgraph
    subgraph "Reporting Engine"
        CSV["CSV Reporter\n(report_csv.py)"]:::report
        Dash["Dash App\n(report_dash/)"]:::report
    end
    click CSV "https://github.com/zhangchenhaobest/tfb_time_series_forecasting_methods/blob/master/ts_benchmark/report/report_csv.py"
    click Dash "https://github.com/zhangchenhaobest/tfb_time_series_forecasting_methods/tree/master/ts_benchmark/report/report_dash/"

    %% Recording Module
    Record["Recording Module\n(recording.py)"]:::core
    click Record "https://github.com/zhangchenhaobest/tfb_time_series_forecasting_methods/blob/master/ts_benchmark/recording.py"

    %% Utilities
    Utils["Utility & Parallel Backends\n(utils/)"]:::core
    click Utils "https://github.com/zhangchenhaobest/tfb_time_series_forecasting_methods/tree/master/ts_benchmark/utils/"

    %% External Runtimes & Container
    Docker["Docker Container\n(Dockerfile)"]:::external
    click Docker "https://github.com/zhangchenhaobest/tfb_time_series_forecasting_methods/tree/master/Dockerfile"
    PyTorch["PyTorch Runtime"]:::external
    Browser["Browser for Dash"]:::external

    %% Data Flows
    CLI -->|"start experiment"| Config
    Config -->|"load settings"| Pipeline
    Pipeline -->|"fetch data"| Data
    Pipeline -.->|"extract features"| CharExt
    Pipeline -->|"instantiate model"| ModelLoader
    ModelLoader --> Baselines
    Pipeline -->|"run evaluation"| Strat
    Strat --> Metrics
    Pipeline -->|"log metadata"| Record
    Strat -->|"metrics results"| CSV
    Strat -->|"metrics results"| Dash
    CSV -->|"write CSV"| Docker
    Dash -->|"serve UI"| Browser
    Pipeline -->|"use utilities"| Utils
    Pipeline --> PyTorch

    %% Container wrap
    Docker --> Pipeline

    %% Styles
    classDef core fill:#cce5ff,stroke:#4da3ff,color:#004085
    classDef data fill:#d4edda,stroke:#28a745,color:#155724
    classDef eval fill:#fff3cd,stroke:#ffcd39,color:#856404
    classDef report fill:#e2d9f3,stroke:#8e44ad,color:#4b0082
    classDef external fill:#e9ecef,stroke:#6c757d,color:#343a40
```
