# shalinvachheta017/sequence-2-sequence-event-prediction architecture

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

- Interactive diagram: https://gitdiagram.com/shalinvachheta017/sequence-2-sequence-event-prediction
- Repository: https://github.com/shalinvachheta017/sequence-2-sequence-event-prediction

## Overview

##### Project Type and Purpose
- This is a command-line-driven, machine-learning pipeline implementing a sequence-to-sequence (Seq2Seq) LSTM model for event prediction.
- It supports K-Fold cross-validation, automatic hyperparameter tuning (via `config.yaml`), post-training analysis, and final retraining & evaluation on test data.
- The purpose is to load historical event sequences, train multiple LSTM encoder-decoder configurations, select the best model, and produce robust evaluation metrics and visualizations.

##### File Structure
- Top-Level Scripts:
- `main.py` – orchestrates the full training pipeline
- `train.py` – implements training & validation loops (including k-fold logic)
- `post_analysis.py` – reads training outputs, selects the best model
- `retrain.py` – retrains the chosen configuration on the full train set and evaluates on unseen data
- Core Modules:
- `data_loader.py` – loads `Events.csv`, preprocesses sequences, builds k-fold splits
- `model_definition.py` – defines the bidirectional LSTM encoder-decoder and FC output layer
- `metrics.py` – custom loss functions and evaluation metrics (coverage, accuracy)
- `utils.py` – logging, configuration parsing, plotting utilities
- Configuration and Dependencies:
- `config.yaml` – hyperparameter grid (batch sizes, learning rates, hidden sizes, etc.)
- `requirements.txt` – Python packages (e.g., PyTorch, NumPy, pandas)
- Outputs & Analysis:
- `outputs/` – saved model weights (`.pth`), loss/accuracy curves
- `Ten fold analysis/` & `Traning Result/` – Jupyter notebooks and CSVs for exploratory and post-hoc EDA

##### Extract Architecture Insights from the README
- Model flow: Encoder (LSTM) → Decoder (LSTM) → Fully Connected Layer
- Training loop uses teacher forcing (ratio 0.3)
- Evaluation metrics: cross-entropy loss, coverage, accuracy
- Hyperparameter search and K-fold cross-validation are first-class citizens in the pipeline

a. Main Components
- Data Storage: `Events.csv` (raw input)
- Preprocessing Module: `data_loader.py`
- Configuration Store: `config.yaml`
- Training Engine: `train.py` & `main.py`
- Model Definition: `model_definition.py` (Encoder/Decoder)
- Metrics & Logging: `metrics.py`, `utils.py`
- Model Artifacts: `outputs/model_run_*.pth`, logs, CSVs
- Post-Training Analysis: `post_analysis.py`, EDA notebooks
- Final Retraining & Evaluation: `retrain.py` → `final_test_results.csv`

b. Relationships & Data Flow
1. Read `config.yaml` → feed hyperparameter grid into `main.py`
2. `main.py` invokes `data_loader.py` to load and split data
3. For each hyperparameter set and each fold:
– Call `train.py` which uses `model_definition.py`
– During training, use `metrics.py` & `utils.py` for loss calculation and logging
– Save model weights and performance logs into `outputs/`
4. After all folds/hyperparams, run `post_analysis.py`:
– Read `outputs/` artifacts → select best configuration
5. Run `retrain.py` with best config on full train set → evaluate on test split → write `final_test_results.csv`
6. Separately, Jupyter notebooks in `Ten fold analysis/` and `Traning Result/` read CSVs from `outputs/` for deeper visualization

c. Architectural Patterns & Design Principles
- Modular separation of concerns: data loading, model definition, training logic, metrics, utilities
- Configuration-driven design: hyperparameters completely externalized
- Iterative pipeline with loops for k-fold and grid search
- Artifact versioning: each model run saved independently
- Offline analysis: EDA notebooks separate from production pipeline

d. Key Technologies & Frameworks
- PyTorch (LSTM, training loops, model serialization)
- pandas / NumPy (data handling)
- YAML (configuration management)
- Jupyter (EDA and result visualization)

## Diagram (Mermaid)

```mermaid
flowchart TD
    EventsCSV["Events.csv"]:::dataComp
    Config["config.yaml"]:::dataComp
    Req["requirements.txt"]:::dataComp
    Main["main.py<br/>(Orchestrator)"]:::compute
    DataLoader["data_loader.py<br/>(Preprocessing)"]:::compute
    subgraph "Hyperparameter & K-Fold Loop"
        direction TB
        TrainEngine["train.py<br/>(Training Loop & K-Fold)"]:::compute
        ModelDef["model_definition.py<br/>(Encoder/Decoder)"]:::compute
        Metrics["metrics.py<br/>(Loss & Metrics)"]:::compute
        Utils["utils.py<br/>(Logging & Utilities)"]:::compute
        OutputsLoop["outputs/"]:::storage
        TrainEngine -->|uses| ModelDef
        TrainEngine -->|calculates & logs| Metrics
        TrainEngine -->|utilizes| Utils
        TrainEngine -->|saves artifacts| OutputsLoop
    end
    PostAnalysis["post_analysis.py<br/>(Post-Training Analysis)"]:::analysis
    subgraph "Offline Analysis Notebooks"
        direction TB
        TenNotebooks["Ten fold analysis/"]:::analysis
        TrainNotebooks["Traning Result/"]:::analysis
    end
    Retrain["retrain.py<br/>(Final Retraining & Evaluation)"]:::compute
    FinalResults["final_test_results.csv"]:::storage

    EventsCSV -->|loads raw data| DataLoader
    Config -->|hyperparameter grid| Main
    Req -.->|dependencies| Main
    Main -->|invokes| DataLoader
    Main -->|iterates| TrainEngine
    OutputsLoop -->|artifacts| PostAnalysis
    OutputsLoop -->|data for notebooks| TenNotebooks
    OutputsLoop -->|data for notebooks| TrainNotebooks
    PostAnalysis -->|selects best config| Retrain
    Retrain -->|evaluates| FinalResults

    click DataLoader "https://github.com/shalinvachheta017/sequence-2-sequence-event-prediction/blob/main/data_loader.py"
    click Config "https://github.com/shalinvachheta017/sequence-2-sequence-event-prediction/blob/main/config.yaml"
    click Main "https://github.com/shalinvachheta017/sequence-2-sequence-event-prediction/blob/main/main.py"
    click TrainEngine "https://github.com/shalinvachheta017/sequence-2-sequence-event-prediction/blob/main/train.py"
    click ModelDef "https://github.com/shalinvachheta017/sequence-2-sequence-event-prediction/blob/main/model_definition.py"
    click Metrics "https://github.com/shalinvachheta017/sequence-2-sequence-event-prediction/blob/main/metrics.py"
    click Utils "https://github.com/shalinvachheta017/sequence-2-sequence-event-prediction/blob/main/utils.py"
    click OutputsLoop "https://github.com/shalinvachheta017/sequence-2-sequence-event-prediction/tree/main/outputs/"
    click PostAnalysis "https://github.com/shalinvachheta017/sequence-2-sequence-event-prediction/blob/main/post_analysis.py"
    click Retrain "https://github.com/shalinvachheta017/sequence-2-sequence-event-prediction/blob/main/retrain.py"
    click Req "https://github.com/shalinvachheta017/sequence-2-sequence-event-prediction/blob/main/requirements.txt"
    click TenNotebooks "https://github.com/shalinvachheta017/sequence-2-sequence-event-prediction/tree/main/Ten fold analysis/"
    click TrainNotebooks "https://github.com/shalinvachheta017/sequence-2-sequence-event-prediction/tree/main/Traning Result/"

    classDef dataComp fill:#ADD8E6,stroke:#000,stroke-width:1px
    classDef compute fill:#90EE90,stroke:#000,stroke-width:1px
    classDef storage fill:#FFA500,stroke:#000,stroke-width:1px
    classDef analysis fill:#DDA0DD,stroke:#000,stroke-width:1px
```
