# stanford-stages/narcolepsy-detector architecture

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

- Interactive diagram: https://gitdiagram.com/stanford-stages/narcolepsy-detector
- Repository: https://github.com/stanford-stages/narcolepsy-detector

## Overview

##### Project type and purpose
- This is a research-focused machine learning pipeline, not a web or full-stack application. Its sole purpose is to take raw polysomnography (PSG) data, extract and select biomarkers, train a classifier for narcolepsy, and evaluate performance.

##### File structure
- Top-level Python scripts each represent a pipeline stage or helper:
- create_scale_n_dataset.py
- extract_features.py
- narco_biomarker.py
- narcolepsy_feature_selection.py
- narcolepsy_GP.py
- sc_eval.py
- run_file.py (pipeline orchestrator)
- run_file.py ties everything together end-to-end.
- No separate “src” or “tests” directories indicates a linear, script-driven workflow.

##### Extract insights from the README
- Confirms it’s a standalone research pipeline for classification using PSG biomarkers.
- Not intended for production or deployment; it’s for historical reference.

##### Main components and their relationships
a. Raw data ingestion
- Raw PSG and label files (external to repo)
- Handed off to create_scale_n_dataset.py
b. Preprocessing & dataset creation
- Scaling, formatting into training/test splits
- Output: standardized dataset files
c. Feature extraction
- extract_features.py computes time/frequency domain features
- narco_biomarker.py derives specialized biomarker signals
- Output: feature matrix files
d. Feature selection
- narcolepsy_feature_selection.py runs statistical or wrapper methods
- Outputs a reduced feature set
e. Model training
- narcolepsy_GP.py trains Gaussian Process (GP) or other models
- Saves trained model artifacts
f. Evaluation
- sc_eval.py loads model + test data, computes metrics (ROC, AUC, accuracy)
g. Orchestration
- run_file.py sequentially calls above scripts, manages I/O paths

##### Architectural patterns & design principles
- Modular pipeline: each stage isolated in its own script
- Linear data flow: raw → preprocess → features → selection → model → evaluation
- Single responsibility: every script focuses on one transformation
- Scripts exchange data via filesystem (CSV, NumPy arrays, pickles)

##### Final recommendations
- Use arrowheads to show exact data flow direction.
- Related modules under containers (e.g., “Feature Engineering”).
- With file names and formats for clarity.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Data Ingestion & Preprocessing
    RawData[(Raw PSG Data)]:::data
    createScale["create_scale_n_dataset.py"]:::ingestion
    scaledData[(Scaled Dataset.csv)]:::data

    %% Feature Engineering
    extractFeatures["extract_features.py"]:::feature
    rawFeatures[(Raw Features.npy)]:::data
    biomarker["narco_biomarker.py"]:::feature
    biomSignals[(Biomarker Signals.npy)]:::data
    featureSelect["narcolepsy_feature_selection.py"]:::feature
    selectedFeatures[(Selected Features.npy)]:::data

    %% Modeling
    modelTrain["narcolepsy_GP.py"]:::model
    trainedModel[(Trained Model.pkl)]:::data

    %% Evaluation
    evaluation["sc_eval.py"]:::eval
    evalReport[(Evaluation Report)]:::eval

    %% Orchestration & Documentation
    orchestrator["run_file.py"]:::orchestrator
    docs["README.md"]:::external

    %% Data Flow
    RawData -->|"input files"| createScale -->|"scaled_dataset.csv"| scaledData
    scaledData --> extractFeatures -->|"features.npy"| rawFeatures
    rawFeatures --> biomarker -->|"biomarker_signals.npy"| biomSignals
    biomSignals --> featureSelect -->|"selected_features.npy"| selectedFeatures
    selectedFeatures --> modelTrain -->|"model.pkl"| trainedModel
    trainedModel --> evaluation -->|"metrics"| evalReport

    %% Orchestration
    orchestrator -.-> createScale
    orchestrator -.-> extractFeatures
    orchestrator -.-> biomarker
    orchestrator -.-> featureSelect
    orchestrator -.-> modelTrain
    orchestrator -.-> evaluation

    %% Documentation
    docs -.-> orchestrator

    %% Click Events
    click createScale "https://github.com/stanford-stages/narcolepsy-detector/blob/master/create_scale_n_dataset.py"
    click extractFeatures "https://github.com/stanford-stages/narcolepsy-detector/blob/master/extract_features.py"
    click biomarker "https://github.com/stanford-stages/narcolepsy-detector/blob/master/narco_biomarker.py"
    click featureSelect "https://github.com/stanford-stages/narcolepsy-detector/blob/master/narcolepsy_feature_selection.py"
    click modelTrain "https://github.com/stanford-stages/narcolepsy-detector/blob/master/narcolepsy_GP.py"
    click evaluation "https://github.com/stanford-stages/narcolepsy-detector/blob/master/sc_eval.py"
    click orchestrator "https://github.com/stanford-stages/narcolepsy-detector/blob/master/run_file.py"
    click docs "https://github.com/stanford-stages/narcolepsy-detector/blob/master/README.md"

    %% Styles
    classDef ingestion fill:#D6E9FF,stroke:#0000FF,color:#000
    classDef feature fill:#DFFFD6,stroke:#00AA00,color:#000
    classDef model fill:#FFEFD6,stroke:#FF8C00,color:#000
    classDef eval fill:#F0D6FF,stroke:#800080,color:#000
    classDef orchestrator fill:#F0D6FF,stroke:#800080,color:#000
    classDef data fill:#EFEFEF,stroke:#888888,color:#000
    classDef external fill:#FFFFFF,stroke:#000000,color:#000
```
