Sleep Sensor Analysis System

A comprehensive Python-based system for analyzing sleep patterns and physiological signals using sensor data. This project provides tools for processing, analyzing, and visualizing sleep sensor data including presence detection, movement analysis, heart rate monitoring, and sleep position classification.

Features

Core Functionality

• Data Preprocessing: Advanced signal processing with filtering, noise reduction, and data normalization
• Presence Detection: Multi-algorithm approach for detecting human presence on bed
• Movement Analysis: Continuous wavelet transform (CWT) based movement detection
• Heart Rate Monitoring: Real-time heart rate extraction and analysis with bradycardia alerts
• Respiration Analysis: Breathing pattern detection and respiratory rate calculation
• Sleep Position Classification: Machine learning-based classification of sleep positions

Signal Processing

• Median filtering for signal smoothing
• Wavelet-based feature extraction
• Zero-crossing detection for physiological signals For most up to date algorithm reference the preprocessing.py file

Project Structure

sleep_sensor/
├── README.md                    # This file
├── requirements.txt             # Python dependencies  
├── setup.py                     # Package installation script
├── .gitignore                   # Git ignore rules
├── src/
│   └── sleep_sensor/            # Main package
│       ├── __init__.py
│       ├── data/                # Data processing modules
│       │   ├── preprocessing.py # Main data processing pipeline
│       │   ├── label_data.py    # Data labeling utilities
│       │   ├── streaming.py     # Real-time data processing
│       │   └── visualization.py # Data visualization tools
│       ├── ml/                  # Machine learning modules
│       │   ├── position_classifier.py # Sleep position ML model
│       │   ├── tiny_NN.py       # Neural network implementation
│       │   └── NN_predicter     # Model prediction utilities
│       └── utils/               # Utility functions
│           ├── logMerger.py     # Log file merging
│           └── merge_files.py   # File merging utilities
├── data/                        # Data directories
│   ├── raw/                     # Original sensor data and log files
│   ├── processed/               # Processed data files
│   ├── experiments/             # Experimental data sessions
│   └── statistics/              # Statistics and analysis results
├── models/                      # Trained models and scalers
├── scripts/                     # Utility and evaluation scripts
├── examples/                    # Example usage scripts
└── docs/                        # Documentation and papers

Installation

1. Clone the repository:

   git clone https://github.com/aleo113/sleep_sensor.git
   cd sleep_sensor

2. Create and activate virtual environment:

   python -m venv .venv
   .venv\Scripts\Activate  # Windows
   # source .venv/bin/activate  # Linux/Mac

3. Install the package in development mode:

   pip install -e .

   Or install dependencies manually:

   pip install -r requirements.txt

Data Processing

Process raw sensor data through the main preprocessing pipeline:

python -m sleep_sensor.data.preprocessing [data_directory]

Key Features:

• Automatic sampling rate detection
• Multi-stage filtering (Butterworth + median)
• Movement detection using CWT
• Presence detection with configurable thresholds
• Heart rate extraction with confidence scoring
• Respiration pattern analysis

Log File Merging

Merge multiple sensor log files into a single dataset:

python -m sleep_sensor.utils.logMerger [input_directory] [output_file]

If you also want to merge the output of the sensor with the hr recorded with a chest strap use:

python -m sleep_sensor.utils.merge_files [Sensor_data] [hr_data] [output_file]

Sleep Position Classification

Train and evaluate sleep position classifier:

python src/sleep_sensor/ml/position_classifier.py

Supported Positions:

• Supine (back)
• Left side
• Right side
• Absent (no presence)

Evaluation Scripts

Run evaluation scripts from the scripts directory:

python scripts/evaluate_presence_detection.py
python scripts/evaluate_presence_detection_var.py

Configuration

The system uses JSON-based configuration for all processing parameters:

Default Configuration

{
    "sampling_rate": 95,
    "filter": {
        "cutoff": 28.0,
        "order": 8,
        "type": "butterworth"
    },
    "movement_detection": {
        "window_size": 4.0,
        "overlap": 0.25,
        "cwt_scale": 16,
        "threshold_factor": 1.0
    },
    "presence_detection": {
        "presence_iteration_threshold": 5,
        "presence_high_threshold": 75,
        "presence_low_threshold": 25
    }
}

Data Format

Input Data

• Log Files: Text files with timestamp and sensor readings
• CSV Files: Structured data with multiple sensor channels
• Real-time Streams: Continuous data processing support

Output Data

The system generates DataFrames with the following columns:

• timestamp: Time information
• value_24bit: Primary sensor reading
• heart_rate_bpm: Extracted heart rate
• respiration_bpm: Breathing rate
• presence_state: Presence detection result
• movement: Movement intensity
• sleep_position: Classified sleep position

Algorithms

Presence Detection

• Variance-based: Analysis of signal variance patterns
• Threshold-based: Configurable presence thresholds
• Probabilistic: Confidence scoring for presence decisions

Movement Detection

• Continuous Wavelet Transform (CWT): Multi-scale movement analysis
• Adaptive Thresholding: Dynamic threshold adjustment
• Temporal Smoothing: Noise reduction in movement signals

Heart Rate Extraction

• Zero-crossing Detection: Robust heartbeat identification
• Confidence Scoring: Quality assessment of HR measurements
• Bradycardia Alerts: Automatic detection of low heart rates

Contributing

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

License

This project is licensed under the MIT License - see the LICENSE file for details.

Contact

For questions and support, please open an issue on GitHub or contact the maintainers.