# shrutii07/cap-phase-detection architecture

> Architecture diagram of the GitHub repository shrutii07/cap-phase-detection, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-17). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/shrutii07/cap-phase-detection
- Repository: https://github.com/shrutii07/cap-phase-detection

## Overview

##### Project Type and Purpose
- This is a machine‐learning research pipeline (not a traditional web app). It ingests single‐channel EEG recordings (EDF + annotation TXT), automatically preprocesses them, prepares a balanced dataset, then trains and evaluates a 1-D CNN to classify CAP sleep phases A/B for healthy and disordered subjects.

##### Key Components (to include
a. Data Sources
- PhysioNet CAP Sleep Database (EDF + annotation TXT files)
- Optional: Kaggle dataset (already balanced)
b. Data Preprocessing
- MATLAB/Octave scripts:
- Data_preparation_from_annotations.m
- edfread.m
- Output: raw segmented EEG signals with labels
c. Cloud/Object Storage
- Google Drive (or any cloud storage) to persist preprocessed files
d. Dataset Preparation Notebook
- Dataset_preparation_CAP_phases.ipynb running in Colab
- Reads preprocessed data, balances classes, serializes into training/test sets (e.g., NumPy arrays or TFRecords)
e. Model Training & Evaluation Notebook
- CAP_phase_detection.ipynb running in Colab
- Loads prepared dataset, defines/compiles 1-D CNN (TensorFlow/Keras or PyTorch), trains model, logs metrics, saves trained weights and history files
f. Outputs/Artifacts
- Trained model files (.h5, .pt)
- Training history and evaluation reports
- Figures (accuracy/loss plots, confusion matrices)

##### Architectural Patterns & Design Principles
- Pipeline/ETL Pattern: clear separation of extraction (EDF read), transformation (preprocessing & balancing), and loading (dataset serialization).
- Modular Notebooks: each notebook handles one stage (data prep vs. model training).
- Stateless Compute: using Colab for ephemeral compute—state is kept in cloud storage.
- Reproducibility: all steps are scripted (MATLAB + Jupyter) and stored in version control.

##### Technologies & Frameworks to annotate
- MATLAB or GNU Octave (for .m scripts)
- Python 3.x, Jupyter/Colab
- NumPy, Pandas (data manipulation)
- TensorFlow/Keras or PyTorch (CNN model)
- Google Drive API (for data storage)
- PhysioNet, Kaggle (external data sources)

##### Diagramming Conventions
- Components: rectangles with clear labels (e.g., “EDF Reader (edfread.m)”).
- External services: clouds or parallelograms (e.g., “PhysioNet CAP DB”).
- Blue for compute/process modules
- Green for data storage
- Orange for external systems

## Diagram (Mermaid)

```mermaid
graph TD
    subgraph "External Data Sources"
        phys["PhysioNet CAP DB"]:::external
        kaggle["Kaggle Balanced Dataset"]:::external
    end

    subgraph "Data Ingestion"
        matlab_edf["EDF Reader (edfread.m)"]:::compute
        matlab_prep["Annotation Prep (Data_preparation_from_annotations.m)"]:::compute
    end

    subgraph "Cloud Storage"
        gdrive["Google Drive Bucket"]:::storage
    end

    subgraph "Dataset Preparation"
        nb_prep["Dataset Prep Notebook"]:::compute
    end

    subgraph "Serialized Data"
        serialized["Serialized Dataset (NumPy/TFRecords)"]:::storage
    end

    subgraph "Training & Evaluation"
        nb_train["Training & Eval Notebook"]:::compute
    end

    subgraph "Artifacts & Documentation"
        model["Trained Model Files (.h5/.pt)"]:::storage
        reports["Reports & Figures"]:::storage
        readme["Project README.md"]:::external
    end

    %% Data Flow
    phys -->|"EDF + TXT"| matlab_edf
    matlab_edf -->|"MATLAB Data"| matlab_prep
    matlab_prep -->|"Segmented EEG + Labels"| gdrive
    kaggle -->|"Balanced Data"| nb_prep

    gdrive -->|"Preprocessed Files"| nb_prep
    nb_prep -->|"Serialized Dataset"| serialized

    serialized -->|"Dataset Files"| nb_train
    nb_train -->|"Model Weights & History"| model
    nb_train -->|"Metrics & Figures"| reports

    model -->|"Optional Upload"| gdrive
    reports -->|"Optional Upload"| gdrive

    %% Click Events
    click matlab_prep "https://github.com/shrutii07/cap-phase-detection/blob/main/Dataset Preparation/Data_preparation_from_annotations.m"
    click matlab_edf "https://github.com/shrutii07/cap-phase-detection/blob/main/Dataset Preparation/edfread.m"
    click nb_prep "https://github.com/shrutii07/cap-phase-detection/blob/main/Dataset Preparation/Dataset_preparation_CAP_phases.ipynb"
    click nb_train "https://github.com/shrutii07/cap-phase-detection/blob/main/CAP_phase_detection.ipynb"
    click readme "https://github.com/shrutii07/cap-phase-detection/blob/main/README.md"

    %% Styles
    classDef compute fill:#bbdefb,stroke:#000
    classDef storage fill:#c8e6c9,stroke:#000
    classDef external fill:#ffe0b2,stroke:#000
```
