Metadata-Version: 2.4
Name: hypnofunk
Version: 0.2.0
Summary: A Python package for sleep analysis and hypnogram processing
Author: Rahul Venugopal
License: MIT
Project-URL: Homepage, https://github.com/rahulvenugopal/hypnofunk
Project-URL: Documentation, https://github.com/rahulvenugopal/hypnofunk#readme
Project-URL: Repository, https://github.com/rahulvenugopal/hypnofunk
Project-URL: Bug Tracker, https://github.com/rahulvenugopal/hypnofunk/issues
Keywords: sleep,analysis,hypnogram,polysomnography,sleep-stages,transitions
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: Topic :: Scientific/Engineering :: Medical Science Apps.
Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=1.20.0
Requires-Dist: pandas>=1.3.0
Requires-Dist: matplotlib>=3.3.0
Provides-Extra: full
Requires-Dist: antropy>=0.1.4; extra == "full"
Requires-Dist: yasa>=0.6.0; extra == "full"
Requires-Dist: mne>=1.0.0; extra == "full"
Provides-Extra: dev
Requires-Dist: pytest>=6.0; extra == "dev"
Requires-Dist: pytest-cov>=2.0; extra == "dev"
Requires-Dist: black>=21.0; extra == "dev"
Requires-Dist: flake8>=3.9; extra == "dev"
Requires-Dist: mypy>=0.900; extra == "dev"
Dynamic: license-file

# hypnofunk 🌙

<p align="center">
  <img src="https://github.com/rahulvenugopal/PyKumbogram/blob/main/Logo.png" width="200" alt="hypnofunk logo">
</p>


[![Python Version](https://img.shields.io/badge/python-3.8%2B-blue.svg)](https://www.python.org/downloads/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

**hypnofunk** is a high-performance toolkit for sleep researchers. It calculates 40+ macrostructure parameters, performs first-order **Markov-chain transition analysis**, and detects sleep cycles—all from simple hypnogram sequences.

---

## Installation

```bash
# Core package
pip install hypnofunk

# Full installation — includes Lempel-Ziv complexity, plotting, and EDF support
pip install hypnofunk[full]
```

---

## Supported Input Formats

### Hypnogram data (in-memory)

hypnofunk accepts standard AASM sleep stage labels (`W`, `N1`, `N2`, `N3`, `R`) as:
- **Python lists**, **NumPy arrays**, or **Pandas Series**.

### File formats (via example workflow)

The included [`polyman_analysis.py`](examples/polyman_analysis.py) provides a turnkey solution for:
- **EDF / EDF+**: Reads Polyman-style annotations directly.
- **CSV**: Processes exported spreadsheets with epoch-by-epoch scoring.

---

## Standard Analysis Parameters

hypnofunk uses industry-standard defaults, all of which are configurable via function arguments:

| Parameter | Default | Logic |
|---|---|---|
| `epoch_duration` | `30s` | The standard temporal resolution for clinical sleep scoring. |
| `max_wake_epochs` | `10` | Keeps 5 mins of wake after final sleep before trimming terminal wake. |
| `min_nrem_epochs` | `30` | Defines a NREM cycle as ≥15 mins of continuous NREM starting with N2. |
| `min_rem_epochs` | `10` | Subsequent REM cycles must be ≥5 mins (1st REM cycle can be any length). |

---

## Sleep Cycle Detection Logic

Our detection algorithms follow standard clinical research criteria to ensure consistency across datasets:

### NREM Cycles 🌙
A sequence is identified as a NREM cycle if:
1.  It **starts with N2** sleep.
2.  It contains at least **15 minutes** (30 epochs) of continuous NREM (N1, N2, or N3).
3.  This prevents short "transitional" light sleep from being miscounted as a full cycle.

### REM Cycles ⚡
REM detection handles the unique nature of early-night sleep:
1.  **First REM Cycle**: Accepted at any length (standard research practice).
2.  **Subsequent REM Cycles**: Must be at least **5 minutes** (10 epochs) long.
3.  This ensures that REM "fragments" commonly found in fragmented sleep don't artificially inflate cycle counts.

---

## Markov-Chain Transition Analysis 🔄

hypnofunk provides a robust framework for quantifying sleep stability and fragmentation using first-order Markov chains:

- **Full Transition Matrix**: A 5×5 matrix of probabilities for transitions between every sleep stage (W, N1, N2, N3, R).
- **Stage Persistence**: The probability of remaining in a specific stage (diagonal nodes of the Markov chain).
- **Awakening Probabilities**: The specific likelihood of transitioning to Wake from each individual sleep stage.
- **Sleep Compactness**: A global consolidation index calculated as the mean persistence across all sleep stages.
- **Fragility Metrics**: Proportion of all transitions that result in awakening.

---

## Quick Start

```python
from hypnofunk import hypnoman, analyze_transitions

# 10 epochs Wake, 50 N2, 30 N3, 20 REM, 5 Wake
hypnogram = ["W"]*10 + ["N2"]*50 + ["N3"]*30 + ["R"]*20 + ["W"]*5

# Get 40+ parameters in one line (Macrostructure)
params = hypnoman(hypnogram, epoch_duration=30)
print(f"TST: {params['TST'].values[0]:.1f} min | SE: {params['Sleep_efficiency'].values[0]:.1f}%")

# Analyze stage transitions & Markov chain dynamics
trans = analyze_transitions(hypnogram)
print(f"Sleep Compactness: {trans['Sleep_Compactness'].values[0]:.3f}")
print(f"Prob. N2 Persistence: {trans['Persistence_N2'].values[0]:.3f}")
```

---

## Core Functionality

### Sleep Macrostructure — `hypnoman()`
Returns a single-row `pd.DataFrame` containing:
- **Time metrics:** TRT, TST, SPT, WASO, SOL.
- **Efficiency:** Sleep Efficiency (SE), Sleep Maintenance Efficiency (SME).
- **Stage statistics:** Duration, percentage, and onset latency for all stages.
- **Streak analysis:** Longest, mean, and median "runs" (streaks) for every stage.
- **Information Theory:** **Lempel-Ziv complexity (LZc)** — a non-linear measure of sleep stage variety (requires `antropy`).

### Transition Analysis — `analyze_transitions()`
Performs the Markov-chain analysis described above, returning:
- Total transitions (fragmentation count).
- Probability of awakening.
- Sleep compactness index.
- Per-stage persistence and awakening probabilities.
- Complete transition matrix (25 probability values).

---

## API Reference

### `hypnofunk.io`
- `read_edf_hypnogram()`: Standardized loader for Polyman EDF and EDF+ files.

### `hypnofunk.core`
- `hypnoman()`: The main entry point for macrostructure metrics.
- `find_nremstretches()` & `find_rem_stretches()`: Cycle detection engines.
- `trim_terminal_wake()`: Utility to clean extended wake at the end of recordings.

### `hypnofunk.transitions`
- `analyze_transitions()`: Main entry point for fragmentation and Markov metrics.
- `compute_transition_matrix()`: Raw transition probability calculations.
- `compute_sleep_compactness()`: Statistical consolidated sleep index.

### `hypnofunk.visualization`
- `plot_hypnogram_with_cycles()`: Clean hypnograms with cycle-overlay bars.
- `plot_transition_matrix()`: Heatmap visualization of stage dynamics (Markov matrix).

---

## Citation

```bibtex
@software{hypnofunk2026,
  author = {Venugopal, Rahul},
  title  = {hypnofunk: A Python package for sleep analysis},
  year   = {2026},
  url    = {https://github.com/rahulvenugopal/hypnofunk}
}
```

## License
MIT — see [LICENSE](LICENSE) for details. Developed by **Rahul Venugopal**.
