Metadata-Version: 2.4
Name: openspindlenet
Version: 0.1.1
Summary: Open-source tool for sleep spindle detection using neural networks
Author-email: Michal Seják <michalsejak@gmail.com>
Project-URL: Homepage, https://github.com/CaptainTrojan/openspindlenet
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=1.19.0
Requires-Dist: onnxruntime>=1.7.0
Requires-Dist: pywavelets>=1.1.0
Provides-Extra: cli
Requires-Dist: rich>=10.0.0; extra == "cli"
Requires-Dist: typer[all]>=0.9.0; extra == "cli"
Requires-Dist: click<8.2,>=8.1; extra == "cli"
Requires-Dist: matplotlib>=3.3.0; extra == "cli"
Requires-Dist: tqdm>=4.66.0; extra == "cli"
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: pytest-cov>=3.0.0; extra == "dev"
Dynamic: license-file

# OpenSpindleNet

An open-source tool for sleep spindle detection using neural networks.

## Installation

Basic installation (core detection only):
```bash
pip install .
```

Full installation with CLI capabilities:
```bash
pip install .[cli]
```

## Usage

### Python API

```python
import numpy as np
from openspindlenet import detect

# From a file
results = detect("path/to/eeg.txt", model_type="eeg")

# From a numpy array
eeg_data = np.random.randn(7500)
results = detect(eeg_data, model_type="eeg")

# Optional: evaluate against segmentation labels (same length as signal)
labels = np.zeros(7500, dtype=np.float32)
scored = detect(eeg_data, model_type="eeg", labels=labels)
print(scored["metrics"]["detection"])  # precision/recall/f1 + TP/FP/FN
print(scored["metrics"]["segmentation"])  # precision/recall/f1 + TP/FP/FN

# Access results
print(f"Number of spindles detected: {len(results['detection_intervals'])}")
for i, (start, end, confidence) in enumerate(results['detection_intervals']):
  print(f"Spindle {i+1}: start={start:.1f}, end={end:.1f}, conf={confidence:.2f}")
```

### Command Line Interface

The CLI requires additional dependencies. Install with `pip install openspindlenet[cli]`.

```bash
# Detect spindles in an EEG file
openspindlenet detect path/to/eeg.txt --model-type eeg --visualize

# Detect spindles in an iEEG file
openspindlenet detect path/to/ieeg.txt --model-type ieeg --visualize

# Evaluate one signal against labels and write JSON/CSV outputs
openspindlenet eval path/to/eeg.txt path/to/labels.txt --visualize

# Show information about available models
openspindlenet info

# Run detection on included example data
openspindlenet example --data-type eeg
```

`eval` writes timestamped JSON and CSV metric outputs by default and, with `--visualize`, generates a PDF that includes predictions, labels, and metric summary.

## Development

### Testing

Run the test suite:
```bash
# Install dev dependencies
pip install -e .[dev]

# Run tests
pytest tests/
```

## Cite

If you find our work useful, please cite our publication
```
@article{sejak2025openspindlenet,
  title={OpenSpindleNet: An open-source deep learning network for reliable sleep spindle detection in scalp and intracranial EEG},
  author={Sejak, Michal and Mivalt, Filip and Sladky, Vladimir and Vsiansky, Vit and Carvalho, Diego Z and Louis, Erik K St and Worrell, Gregory A and Kremen, Vaclav},
  journal={Computers in Biology and Medicine},
  volume={197},
  pages={110854},
  year={2025},
  publisher={Elsevier}
}
```

### Contributing

Contributions are welcome! Please feel free to submit a Pull Request.
