# gabrielmittag/nisqa architecture

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

- Interactive diagram: https://gitdiagram.com/gabrielmittag/nisqa
- Repository: https://github.com/gabrielmittag/nisqa

## Overview

##### Main Components
- Environment & Configuration:
- The project uses an Anaconda environment defined in “env.yml” and several YAML configuration files in the “config” directory (e.g., finetune, train_nisqa_cnn_sa_ap.yaml, train_nisqa_double_ended.yaml) that specify training and finetuning parameters.
- Core Library:
- The “nisqa” directory includes key modules like “NISQA_model.py” (which implements the deep learning model architectures) and “NISQA_lib.py” (providing helper functions).
- Executable Scripts:
- There are three main scripts:
- run_predict.py – for inference on single files, directories, or CSV-based inputs.
- run_train.py – for training new models or using transfer learning/finetuning.
- run_evaluate.py – for model evaluation, replicating tests from the NISQA paper.
- Pre-trained Model Weights:
- The “weights” directory contains the pre-trained weights (nisqa.tar for full quality, nisqa_mos_only.tar for single output, and nisqa_tts.tar for TTS naturalness).

##### Architectural Relationships and Data Flow
- Data Input & Preprocessing:
- Users provide speech data (WAV files or CSV listings) that are fed into the prediction or training pipelines.
- The configuration files define the mapping between data directories, CSV columns, and target labels.
- Model Execution:
- The prediction process (via run_predict.py) loads model weights from the “weights” directory and utilizes functions from the “nisqa” library to process and predict speech quality.
- For training, run_train.py uses the configurations from YAML files to orchestrate model initialization (with architectures that can include CNN, LSTM, Self-Attention, and various pooling methods) and to drive the training loop.
- Output & Reporting:
- Prediction results are output to the console and can also be saved as CSV files.
- During training and evaluation, logs and model checkpoints (stored in the “output_dir” specified in the configuration) are generated.

##### Architectural Patterns and Design Principles
- Modularity:
- The system is clearly partitioned into data ingestion, model computation (segmented logically as framewise processing, time-dependency, and pooling), and results reporting.
- Configurability:
- The YAML configuration files illustrate that the project is designed to easily swap different deep learning components (e.g., different combinations of CNN, LSTM, Self-Attention) and adapt for diverse training tasks (single-ended vs. double-ended models).
- Command-Line Driven Workflow:
- Different scripts are dedicated to prediction, training, and evaluation, which simplifies maintenance and testing.

##### Relevant Technologies, Frameworks, and Libraries
- Deep Learning Framework:
- Scripting and Configuration:
- YAML is used for experiment configuration.
- Data Formats:
- The project works with audio files (WAV format) and CSV for dataset management.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Environment & Configuration"
        Env["Anaconda Environment (env.yml)"]:::config
        Config["YAML Config Files (config/)"]:::config
    end

    subgraph "Core Library"
        Model["Core Model (nisqa/NISQA_model.py)"]:::library
        Lib["Helper Functions (nisqa/NISQA_lib.py)"]:::library
    end

    subgraph "Executable Scripts"
        Predict["Prediction Script (run_predict.py)"]:::script
        Train["Training Script (run_train.py)"]:::script
        Evaluate["Evaluation Script (run_evaluate.py)"]:::script
    end

    subgraph "Model Weights"
        Weights["Pre-trained Weights (weights/)"]:::weights
    end

    Input["Speech Data (WAV/CSV)"]:::input

    Output1["Console/CSV Output"]:::output
    Output2["Logs & Checkpoints"]:::output
    Output3["Evaluation Reports"]:::output

    ModelArch["Model Architecture (CNN→LSTM/Self-Attention→Pooling)"]:::annotation

    %% Data input flows
    Input -->|"provided to"| Predict
    Input -->|"provided to"| Train
    Input -->|"provided to"| Evaluate

    %% Environment & Config flows
    Env -->|"configures"| Predict
    Config -->|"supplies parameters to"| Train
    Config -->|"supplies parameters to"| Evaluate

    %% Prediction pipeline flows
    Predict -->|"loads model from"| Weights
    Predict -->|"invokes functions in"| Model
    Predict -->|"invokes functions in"| Lib
    Predict -->|"outputs results to"| Output1

    %% Training pipeline flows
    Train -->|"initializes model via"| Model
    Train -->|"uses helper functions from"| Lib
    Train -->|"configures"| ModelArch
    Train -->|"produces"| Output2

    %% Evaluation pipeline flows
    Evaluate -->|"computes metrics with"| Model
    Evaluate -->|"uses helper functions from"| Lib
    Evaluate -->|"reports to"| Output3

    %% Class definitions for styling
    classDef config fill:#FFD700,stroke:#333,stroke-width:2px;
    classDef library fill:#90EE90,stroke:#333,stroke-width:2px;
    classDef script fill:#ADD8E6,stroke:#333,stroke-width:2px;
    classDef weights fill:#FFB6C1,stroke:#333,stroke-width:2px;
    classDef input fill:#FFA07A,stroke:#333,stroke-width:2px;
    classDef output fill:#DDA0DD,stroke:#333,stroke-width:2px;
    classDef annotation fill:#F0E68C,stroke:#333,stroke-width:2px,stroke-dasharray: 5 5;

    %% Click Events for component mapping
    click Env "https://github.com/gabrielmittag/nisqa/blob/master/env.yml"
    click Config "https://github.com/gabrielmittag/nisqa/tree/master/config/"
    click Model "https://github.com/gabrielmittag/nisqa/blob/master/nisqa/NISQA_model.py"
    click Lib "https://github.com/gabrielmittag/nisqa/blob/master/nisqa/NISQA_lib.py"
    click Predict "https://github.com/gabrielmittag/nisqa/blob/master/run_predict.py"
    click Train "https://github.com/gabrielmittag/nisqa/blob/master/run_train.py"
    click Evaluate "https://github.com/gabrielmittag/nisqa/blob/master/run_evaluate.py"
    click Weights "https://github.com/gabrielmittag/nisqa/tree/master/weights/"
```
