# almadani92/w-netr-for-fecg-extraction architecture

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

- Interactive diagram: https://gitdiagram.com/almadani92/w-netr-for-fecg-extraction
- Repository: https://github.com/almadani92/w-netr-for-fecg-extraction

## Overview

##### Project Type and Purpose
- The project is a deep-learning pipeline built upon MONAI (a PyTorch-based framework for healthcare signals). Its aim is to extract fetal ECG (FECG) signals using a one-dimensional W-NETR architecture. There are two domains of interest: simulation (synthetic signals) and real data.
- The README explicitly explains that there are separate dataset generation scripts and network definitions for synthetic and real data.

##### File Structure for Architectural Components
- Data Organization & Generation:
- Directories such as “fetal-ecg-synthetic-database-1.0.0”, “ADFECGDB”, and “PCDB” hold raw data files and scripts that organize these datasets.
- Files like “generate_dataset.py”, “generate_dataset_real.py”, “Dataset_gen2.py”, “Dataset_gen_real.py”, “Dataset_gen_pcdb.py” indicate preprocessing/organizing steps.
- Within these directories you also see sub-components like “fecg_ground”, “mixture”, “mecg_ground” which represent specific channels or aspects of the ECG data.

- Network Architecture:
- The “networks.py” and “networks_real.py” files define the W-NETR architectures tailored for simulation and real data tests.
- The “models” directory holds detailed building blocks (e.g. unetr, PatchEmbeddingBlock, vit etc.) that are used to construct the network layers.
- “init.py” provides configuration options for training.

- Testing & Evaluation:
- Test scripts “test_simulation.py”, “test_real.py”, and “test_pcdb.py” indicate the layers where testing or evaluation is performed.
- The results images in the README (synthetic_results.png and real_results.png in the “images” folder) reflect the output of these tests.

- Utility Support:
- The “util” directory and files like “utils.py” support dataset handling, pre/post processing, and other helper functions.
- Configuration files like “requirements.txt” and “installation_commands_.txt” indicate dependencies and installation instructions.

- External Dependencies:

##### Defining the Main Components and Their Relationships
A. Data Ingestion and Preprocessing:
- Components: Raw Dataset directories (fetal-ecg-synthetic-database-1.0.0, ADFECGDB, PCDB)
- Process: Dataset generation scripts (e.g., generate_dataset.py, Dataset_gen2.py, Dataset_gen_real.py)
- Data Flow: Raw Data Files → Preprocessing Scripts → Structured Dataloader Files

B. Network Architecture & Training / Testing Modules:
- Components: Network definitions (networks.py, networks_real.py) and associated building blocks in the “models” folder.
- Process: The deep-learning models (W-NETR) are constructed using the components provided in the “models” directory, configured via “init.py”.
- Data Flow: Processed data from the preprocessing stage is fed into the network; model architecture flows through input layers, through the embedding blocks and dynamic blocks (like in unetr and vit) to output prediction signals.

C. Evaluation and Results:
- Components: Testing scripts (test_simulation.py, test_real.py, test_pcdb.py)
- Process: Evaluating model outputs; generating visualization and result plots (as shown in the “images” folder).
- Data Flow: Inference results → Testing scripts → Result visualizations

D. Utility and Helper Modules:
- Components: “util” and “utils.py”
- Process: Support dataset management, logging, and configurations across the data processing and model execution pipelines.

##### Architectural Patterns and Design Principles
- Separation of Concerns: The architecture distinguishes between data processing and model execution phases. There is a clear split between synthetic (simulation) and real datasets.
- Modularity: Different directories and scripts handle dataset creation, network definition, and testing. This modularity is crucial for extending or debugging different parts.
- Dependency Injection: Configuration settings from “init.py” and clear definitions in “requirements.txt” mean that the runtime environment is controlled and reproducible.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Dependencies
    D1["MONAI"]:::dependency
    D2["PyTorch"]:::dependency

    %% Data Ingestion & Preprocessing
    subgraph "Data Ingestion & Preprocessing"
        %% Synthetic Data Preprocessing
        subgraph "Synthetic Data Preprocessing"
            S_DATA["fetal-ecg-synthetic-database-1.0.0"]:::data
            S_SCRIPT1["generate_dataset.py"]:::data
            S_SCRIPT2["Dataset_gen2.py"]:::data
        end
        %% Real Data Preprocessing
        subgraph "Real Data Preprocessing"
            R_DATA["ADFECGDB"]:::data
            R_SCRIPT1["generate_dataset_real.py"]:::data
            R_SCRIPT2["Dataset_gen_real.py"]:::data
        end
        %% PCDB Data Preprocessing
        subgraph "PCDB Data Preprocessing"
            P_DATA["PCDB"]:::data
            P_SCRIPT1["generate_dataset_pcdb.py"]:::data
            P_SCRIPT2["Dataset_gen_pcdb.py"]:::data
        end
        %% Aggregated Preprocessed Data Nodes
        PSDYN["Preprocessed Synthetic Data"]:::data
        PRDY["Preprocessed Real Data"]:::data
        PPDY["Preprocessed PCDB Data"]:::data
    end

    %% Network Architecture & Training
    subgraph "Network Architecture & Training"
        subgraph "Synthetic Network"
            NET_SYN["networks.py"]:::network
            MODELS_SYN["models"]:::network
        end
        subgraph "Real Network"
            NET_REAL["networks_real.py"]:::network
            MODELS_REAL["models"]:::network
        end
    end

    %% Testing & Evaluation
    subgraph "Testing & Evaluation"
        T_SIM["test_simulation.py"]:::test
        T_REAL["test_real.py"]:::test
        T_PCDB["test_pcdb.py"]:::test
    end

    %% Utilities & Configuration
    subgraph "Utilities & Configuration"
        UTIL_DIR["util"]:::util
        UTILS_FILE["utils.py"]:::util
        CONFIG["init.py"]:::util
    end

    %% Connections for Synthetic Data Flow
    S_DATA -->|"feeds"| S_SCRIPT1
    S_DATA -->|"feeds"| S_SCRIPT2
    S_SCRIPT1 -->|"processes"| PSDYN
    S_SCRIPT2 -->|"processes"| PSDYN

    %% Connections for Real Data Flow
    R_DATA -->|"feeds"| R_SCRIPT1
    R_DATA -->|"feeds"| R_SCRIPT2
    R_SCRIPT1 -->|"processes"| PRDY
    R_SCRIPT2 -->|"processes"| PRDY

    %% Connections for PCDB Data Flow
    P_DATA -->|"feeds"| P_SCRIPT1
    P_DATA -->|"feeds"| P_SCRIPT2
    P_SCRIPT1 -->|"processes"| PPDY
    P_SCRIPT2 -->|"processes"| PPDY

    %% Data to Network Flow
    PSDYN -->|"input"| NET_SYN
    PRDY -->|"input"| NET_REAL

    %% Network Internal Flow
    NET_SYN -->|"builds"| MODELS_SYN
    NET_REAL -->|"builds"| MODELS_REAL

    %% External Dependencies into Networks
    D1 ---|"dependency"| NET_SYN
    D2 ---|"dependency"| NET_SYN
    D1 ---|"dependency"| NET_REAL
    D2 ---|"dependency"| NET_REAL

    %% Networks to Testing
    MODELS_SYN -->|"inference"| T_SIM
    MODELS_REAL -->|"inference"| T_REAL
    PPDY -->|"direct evaluation"| T_PCDB

    %% Configuration Link to Networks
    CONFIG ---|"configures"| NET_SYN
    CONFIG ---|"configures"| NET_REAL

    %% Click Events for Data Ingestion & Preprocessing (Synthetic)
    click S_DATA "https://github.com/almadani92/w-netr-for-fecg-extraction/blob/main/fetal-ecg-synthetic-database-1.0.0"
    click S_SCRIPT1 "https://github.com/almadani92/w-netr-for-fecg-extraction/blob/main/fetal-ecg-synthetic-database-1.0.0/generate_dataset.py"
    click S_SCRIPT2 "https://github.com/almadani92/w-netr-for-fecg-extraction/blob/main/fetal-ecg-synthetic-database-1.0.0/Dataset_gen2.py"

    %% Click Events for Data Ingestion & Preprocessing (Real)
    click R_DATA "https://github.com/almadani92/w-netr-for-fecg-extraction/tree/main/ADFECGDB"
    click R_SCRIPT1 "https://github.com/almadani92/w-netr-for-fecg-extraction/blob/main/ADFECGDB/generate_dataset_real.py"
    click R_SCRIPT2 "https://github.com/almadani92/w-netr-for-fecg-extraction/blob/main/ADFECGDB/Dataset_gen_real.py"

    %% Click Events for Data Ingestion & Preprocessing (PCDB)
    click P_DATA "https://github.com/almadani92/w-netr-for-fecg-extraction/tree/main/PCDB"
    click P_SCRIPT1 "https://github.com/almadani92/w-netr-for-fecg-extraction/blob/main/PCDB/generate_dataset_pcdb.py"
    click P_SCRIPT2 "https://github.com/almadani92/w-netr-for-fecg-extraction/blob/main/PCDB/Dataset_gen_pcdb.py"

    %% Click Events for Network Architecture
    click NET_SYN "https://github.com/almadani92/w-netr-for-fecg-extraction/blob/main/networks.py"
    click MODELS_SYN "https://github.com/almadani92/w-netr-for-fecg-extraction/tree/main/models"
    click NET_REAL "https://github.com/almadani92/w-netr-for-fecg-extraction/blob/main/networks_real.py"
    click MODELS_REAL "https://github.com/almadani92/w-netr-for-fecg-extraction/tree/main/models"

    %% Click Events for Testing & Evaluation
    click T_SIM "https://github.com/almadani92/w-netr-for-fecg-extraction/blob/main/test_simulation.py"
    click T_REAL "https://github.com/almadani92/w-netr-for-fecg-extraction/blob/main/test_real.py"
    click T_PCDB "https://github.com/almadani92/w-netr-for-fecg-extraction/blob/main/test_pcdb.py"

    %% Click Events for Utilities & Configuration
    click UTIL_DIR "https://github.com/almadani92/w-netr-for-fecg-extraction/tree/main/util"
    click UTILS_FILE "https://github.com/almadani92/w-netr-for-fecg-extraction/blob/main/utils.py"
    click CONFIG "https://github.com/almadani92/w-netr-for-fecg-extraction/blob/main/init.py"

    %% Styles
    classDef data fill:#ADD8E6,stroke:#000,stroke-width:2px;
    classDef network fill:#98FB98,stroke:#000,stroke-width:2px;
    classDef test fill:#FFD700,stroke:#000,stroke-width:2px;
    classDef util fill:#FFB6C1,stroke:#000,stroke-width:2px;
    classDef dependency fill:#D3D3D3,stroke:#000,stroke-width:2px;
```
