# google/vsf-time-series architecture

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

- Interactive diagram: https://gitdiagram.com/google/vsf-time-series
- Repository: https://github.com/google/vsf-time-series

## Overview

##### Project Type and Purpose
- This is a Python-based research codebase for multivariate time series forecasting on variable subsets, packaged as a set of CLI scripts and modules.
- It implements data preparation, model definition (wrapping MTGNN), training loops, evaluation/inference settings, and a nonparametric wrapper technique for partial‐variable inference.

##### High-Level Architecture
- There are no separate “frontend” or “service” layers; it’s a script-oriented ML pipeline.
- Core functional areas:
a. Data Preparation (generate_training_data.py)
b. Model Definition (layer.py, net.py)
c. Training & Experiment Orchestration (trainer.py, train_multi_step.py)
d. Utility Functions (util.py)
e. External Dependencies (MTGNN code, datasets on disk)

##### Main Components and Their Relationships
- Data Preparation Module
- Input: Raw dataset files (METR-LA, SOLAR, TRAFFIC, ECG)
- Output: Train/validation/test splits in ./data/{dataset}/
- Model Definition Module
- layer.py: Custom graph convolution or attention layers
- net.py: High‐level model wrapper that instantiates MTGNN or other backbones
- Exposes a standard PyTorch nn.Module interface
- Training & Orchestration Module
- trainer.py: Contains training loop, loss computation, checkpointing, evaluation metrics
- train_multi_step.py: CLI entry point; parses flags (partial vs. full vs. oracle vs. wrapper settings), instantiates trainer & model, kicks off runs, aggregates results
- Utility Module
- util.py: Helper functions for logging, graph adjacency handling (identity vs. sensor_graph), random subset sampling, metrics calculations
- External Services & Storage
- ./data folder (datasets, adjacency matrices)
- MTGNN Git submodule or pip dependency
- Compute environment: Python3, PyTorch, CUDA­enabled GPU

##### Architectural Patterns & Design Principles
- Modular separation of concerns: data, model, training, utilities
- Single responsibility per script/module (generate data vs. train vs. define layers)
- Experiment reproducibility via CLI flags and random seed parameters
- Wrapper design pattern for nonparametric post-training technique (borrow_from_train_data)

## Diagram (Mermaid)

```mermaid
graph TB
    %% Components
    subgraph "Modules"
        direction TB
        DataPrep["generate_training_data.py"]:::python
        ModelLayers["layer.py"]:::python
        ModelWrapper["net.py"]:::python
        Trainer["trainer.py"]:::python
        Utils["util.py"]:::python
    end

    CLI["train_multi_step.py"]:::cli
    Storage["./data (Datasets & Adjacency)"]:::storage
    MTGNN["MTGNN Library"]:::external
    GPU["GPU / CUDA Compute"]:::compute

    %% Flows
    DataPrep -->|DataLoader| Trainer
    ModelLayers -->|Custom Layers| Trainer
    ModelWrapper -->|nn.Module Interface| Trainer
    MTGNN -->|Imported by net.py| ModelWrapper
    Utils -->|Helpers| Trainer
    Utils -->|Helpers| CLI
    CLI -->|--data,--model,--epochs...| Trainer
    Trainer -->|Checkpoints,Logs| Storage
    Trainer -- GPU Access --> GPU
    GPU -- Compute Feedback --> Trainer

    %% Legend
    subgraph "Legend"
        direction TB
        A["Blue: Python Modules"]:::python
        B["Green: CLI Entry"]:::cli
        C["Orange: Data Storage"]:::storage
        D["Red: Compute"]:::compute
        E["Gray: External Lib"]:::external
    end

    %% Click Events
    click DataPrep "https://github.com/google/vsf-time-series/blob/master/generate_training_data.py"
    click ModelLayers "https://github.com/google/vsf-time-series/blob/master/layer.py"
    click ModelWrapper "https://github.com/google/vsf-time-series/blob/master/net.py"
    click Trainer "https://github.com/google/vsf-time-series/blob/master/trainer.py"
    click Utils "https://github.com/google/vsf-time-series/blob/master/util.py"
    click CLI "https://github.com/google/vsf-time-series/blob/master/train_multi_step.py"

    %% Styles
    classDef python fill:#aed6f1,stroke:#1f4e79,stroke-width:1px
    classDef cli fill:#a9dfbf,stroke:#207f3b,stroke-width:1px,shape:hexagon
    classDef storage fill:#f9e79f,stroke:#b47d0e,stroke-width:1px,shape:cylinder
    classDef compute fill:#f5b7b1,stroke:#871f0f,stroke-width:1px,shape:cloud
    classDef external fill:#d5dbdb,stroke:#7f8c8d,stroke-width:1px,stroke-dasharray: 5 5
    class CLI cli
    class Storage storage
    class GPU compute
```
