# hyunwookl/tilde-q architecture

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

- Interactive diagram: https://gitdiagram.com/hyunwookl/tilde-q
- Repository: https://github.com/hyunwookl/tilde-q

## Overview

- Data Ingestion and Preprocessing: Represented by the directory “src/data_provider” where modules like data_factory.py, data_loader.py, m4.py, and uea.py exist.
- Experiment Management: The “src/exp” directory holds different experiment scripts (for anomaly detection, classification, imputation, long-term and short-term forecasting). The main entry point “src/run.py” orchestrates experiments and model training.
- Models and Layers: The architecture implementations are split into “src/models” (implementing various forecasting models) and “src/layers” (providing core deep learning blocks like various attention or convolution blocks).
- Loss Functions: The custom loss (TILDE‑Q) is implemented (found in “src/loss/tildeq.py”) and also there’s advice for integrating DILATE components.
- Automation / Scripts: Under “src/TILDEQ_scripts” and “src/scripts”, many Bash scripts are provided to run various experiments on different datasets (ETT, ECL, Traffic, Weather, etc.). These scripts trigger the experiments by calling run.py with different configurations.
- Results and Output: Directories like “qualitative_results” and “tables” store visual and tabulated outputs of experiments.

##### Component Interactions & Data Flow
- Experimental Workflow: Illustrate how a user starts by executing a Bash script (via TILDEQ_scripts) which calls “run.py” along with model-specific and loss-specific flags.
- Model Pipeline: “run.py” initializes the experiment module from “src/exp”, which then loads data using “src/data_provider”. The selected deep-learning model (from “src/models”) is built using defined layers (from “src/layers”) and optimized using the chosen loss functions (TILDE‑Q or DILATE from “src/loss”).
- Experiment Outcomes: After training, predictions and metrics (computed possibly using “src/utils/metrics.py” and related utilities) lead to quantitative outputs (saved in “tables”) and visualization outputs (saved in “qualitative_results”).

##### Architectural Patterns and Design Principles
- Modularity and Separation of Concerns: Distinct components for data management, experiment logic, model definitions, and loss functions.
- Script-driven Experimentation: Many Bash scripts are used for automating a series of experiment runs across multiple datasets and models, ensuring reproducibility.
- Plug-and-Play Loss Functions: The design allows experimentation with different loss functions through configurable parameters passed to “run.py”.
- Reuse of External Research: The repository builds on the “Time-Series-Library” GitHub, so consider showing external integration for background models.

##### Specify Relevant Technologies/Frameworks
- Deep Learning Framework: Although not explicitly mentioned, the file structure (e.g., layers, models) and use of Python suggest a framework like PyTorch or TensorFlow.
- Scripting & Shell Commands: Numerous Bash scripts are used for quick experimentation.
- Pipeline Tools: Python utilities in “src/utils” handle metric computation and other supportive functions.

##### Elements
- You might also include a note regarding “external dependencies” such as the Time-Series-Library integration.
- To annotate the customizable hyperparameters (for example, the arguments for TILDE‑Q passed into “run.py”).

## Diagram (Mermaid)

```mermaid
graph TD
    %% Experiment Interface & Script Layer
    subgraph "Experiment Interface & Script Layer"
        A1["TILDEQ Scripts"]:::script
        A2["Other Scripts"]:::script
        B["Experiment Orchestrator (src/run.py)"]:::script
    end
    A1 --> B
    A2 --> B

    %% Application Core
    subgraph "Application Core"
        C["Experiment Modules (src/exp)"]:::experiment
        D["Data Provider (src/data_provider)"]:::data
    end
    B --> C
    B --> D
    C --> D

    %% Model and Loss Layer
    subgraph "Model and Loss Layer"
        E1["Models (src/models)"]:::model
        E2["Layers (src/layers)"]:::model
        F["Loss Functions (src/loss/tildeq.py)"]:::loss
    end
    C --> E1
    C --> E2
    D --> E1
    D --> E2
    E1 --> F
    E2 --> F

    %% External Dependency
    H["External: Time-Series-Library"]:::external
    H --> E1

    %% Output & Analysis
    subgraph "Output & Analysis"
        G1["Quantitative Results (tables)"]:::output
        G2["Qualitative Results (qualitative_results)"]:::output
    end
    F --> G1
    F --> G2

    %% Click Events
    click A1 "https://github.com/hyunwookl/tilde-q/tree/main/src/TILDEQ_scripts"
    click A2 "https://github.com/hyunwookl/tilde-q/tree/main/src/scripts"
    click B "https://github.com/hyunwookl/tilde-q/blob/main/src/run.py"
    click C "https://github.com/hyunwookl/tilde-q/tree/main/src/exp"
    click D "https://github.com/hyunwookl/tilde-q/tree/main/src/data_provider"
    click E1 "https://github.com/hyunwookl/tilde-q/tree/main/src/models"
    click E2 "https://github.com/hyunwookl/tilde-q/tree/main/src/layers"
    click F "https://github.com/hyunwookl/tilde-q/blob/main/src/loss/tildeq.py"
    click G1 "https://github.com/hyunwookl/tilde-q/tree/main/tables"
    click G2 "https://github.com/hyunwookl/tilde-q/tree/main/qualitative_results"

    %% Styles
    classDef script fill:#ffdead,stroke:#333,stroke-width:2px;
    classDef experiment fill:#98fb98,stroke:#333,stroke-width:2px;
    classDef data fill:#add8e6,stroke:#333,stroke-width:2px;
    classDef model fill:#dda0dd,stroke:#333,stroke-width:2px;
    classDef loss fill:#f08080,stroke:#333,stroke-width:2px;
    classDef output fill:#ffff99,stroke:#333,stroke-width:2px;
    classDef external fill:#e0e0e0,stroke:#333,stroke-width:2px;
```
