How tanishy7777/sleep-stage-classification-using-non-invasive-signals-from-thermal-imagery works
Project Type and Purpose
• This is a research-oriented machine learning pipeline for sleep stage classification using non-invasive signals (thermal imagery, flow, ribcage) as an alternative to EEG/EOG/EMG.
File Structure Analysis
• Top-level:
• BetterModels/ – the main Python package
– dataprocessor/ (dataloader.py, dataset.py, preprocessor.py, featurizer.py)
– models/ (implementations: InceptionTime, RandomForests, XGboost, biLSTM_CNN, transformer)
– utils/ (crossvalidation.py, metrics.py, traintest.py)
– visualizations/ (plots.py)
• dataset/files/ – raw input files (REC, EDF, stage annotations)
• ConvTran.py, Transformer architecture/transformer.py, boosting.ipynb, model*.ipynb – experiment drivers and notebooks
• requirements.txt – dependencies
• Architectural pattern: a staged, modular ML pipeline (ingest → preprocess → feature extraction → modeling → evaluation → visualization).
README Insights
• Methodology sections confirm the pipeline stages:
a. Preprocessing (normalization, smoothing)
b. Feature Extraction (TSFEL, CNN embeddings, handcrafted)
c. Modeling (Random Forests, XGBoost, BiLSTM, Transformer)
d. Evaluation (accuracy, specificity across class counts)
• Dependencies implied: Python scientific stack (pandas, numpy, scipy, TSFEL), ML frameworks (scikit-learn, xgboost, PyTorch or TensorFlow), plotting (matplotlib, seaborn).
a. Main Components
• Raw Data Store (dataset/files)
• Data Ingestion Layer (dataloader.py, dataset.py)
• Preprocessing Module (preprocessor.py: normalization, smoothing)
• Feature Engineering Module (featurizer.py: TSFEL, handcrafted, CNN-based)
• Model Training & Inference Layer (models/: RandomForests, XGBoost, biLSTM_CNN, Transformer)
• Evaluation & Validation Module (utils: traintest.py, crossvalidation.py, metrics.py)
• Visualization Layer (visualizations/plots.py, notebooks, Result images/)
b. Relationships and Data Flow
• Branching: Feature Engineering outputs feed into multiple model types in parallel.
• Feedback loop: Evaluation metrics may influence hyperparameter tuning in preprocessing or feature stages.
c. Architectural Patterns & Principles
• Modularity: each pipeline stage is its own package/submodule
• Pluggability: models and feature extractors can be swapped without rewiring the pipeline
• Separation of concerns: data, logic, visualization, and experiments are isolated
d. Key Technologies & Frameworks
• Python, pandas, NumPy, SciPy, TSFEL
• scikit-learn, xgboost
• PyTorch or TensorFlow (for BiLSTM, Transformer, CNN)
• Matplotlib/Seaborn for plots
Key Advice
• Pipeline stage as a separate node.
• How modules plug into one another without over-collapsing components.
• Both batch training and interactive notebook-driven experimentation.
• Artifacts (Result images folder) as the final output node.