Metadata-Version: 2.1
Name: pysleep
Version: 0.2.0
Summary: A Python library for sleep pattern analysis, sleep metrics calculation, and comprehensive sleep stage statistics
Keywords: sleep,analysis,metrics,medical,research,health,sleep-stages,sleep-analysis,sleep-tracking,polysomnography
Author-Email: Hankyeol Kyung <kghnkl0103@gmail.com>
License: MIT
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Healthcare Industry
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Medical Science Apps.
Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
Project-URL: Homepage, https://github.com/asleep-ai/pysleep
Project-URL: Bug Tracker, https://github.com/asleep-ai/pysleep/issues
Requires-Python: >=3.10
Provides-Extra: dev
Requires-Dist: pytest; extra == "dev"
Requires-Dist: parameterized; extra == "dev"
Description-Content-Type: text/markdown

# pysleep

A Python library for sleep pattern analysis and sleep metrics calculation commonly used in medical and research fields.

## Installation

```bash
pip install pysleep
```

## Features

- Definition of sleep stages and events in the Python ecosystem
- Various sleep metrics used in medical field
- Sleep statistics calculation and analysis tools
- Comprehensive sleep stage calculator for 30+ metrics from epoch data
- Returns `None` for breathing fields (requires sensor data)
- Returns `None` for sleep_index (scoring not implemented)

## Sleep Stage Calculator

The `SleepStageCalculator` analyzes 30-second epoch sleep stage data to compute comprehensive sleep metrics including latencies, durations, ratios, and sleep quality indices.

### Quick Example

```python
from pysleep import SleepStageCalculator
from datetime import datetime

# Initialize calculator
calculator = SleepStageCalculator()

# Define session times
start_time = datetime(2024, 1, 1, 22, 0, 0)
end_time = datetime(2024, 1, 2, 6, 0, 0)

# Sleep stages (30-second epochs): 0=WAKE, 1=LIGHT, 2=DEEP, 3=REM
sleep_stages = [0, 0, 1, 1, 2, 2, 3, 3, 1, 1, 0, 1, 2, 3]  # ... more epochs

# Calculate metrics
stats = calculator.calculate(sleep_stages, start_time, end_time)

# Access results (returns SleepStat object)
print(f"Sleep efficiency: {stats.sleep_efficiency:.1%}")
print(f"Time in sleep: {stats.time_in_sleep}")
print(f"Sleep latency: {stats.sleep_latency}")
print(f"Sleep cycles: {stats.sleep_cycle}")
```

For detailed documentation on all available metrics and advanced usage, see the [Sleep Stage Calculator documentation](src/pysleep/calculator/README.md).

## License

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