How stanford-stages/narcolepsy-detector works
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.