Metadata-Version: 2.4
Name: turtlewave-hdEEG
Version: 3.3.0
Summary: High-density EEG processing for sleep event detection
Author-email: Tancy Kao <tancy.kao@woolcock.org.au>
License: MIT
Project-URL: Documentation, https://turtlewave-hdeeg.readthedocs.io/
Project-URL: Repository, https://github.com/TancyKao/TurtleWave-hdEEG
Project-URL: Issues, https://github.com/TancyKao/TurtleWave-hdEEG/issues
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: MacOS
Classifier: Operating System :: POSIX :: Linux
Classifier: Operating System :: Microsoft :: Windows
Classifier: Intended Audience :: Science/Research
Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy==1.26.4
Requires-Dist: wonambi==7.15
Requires-Dist: scipy>=1.10
Requires-Dist: matplotlib>=3.5
Requires-Dist: h5py>=3.0
Requires-Dist: pandas>=2.0
Requires-Dist: tensorpac>=0.6.5
Requires-Dist: mne>=1.0
Requires-Dist: PyQt5>=5.15
Requires-Dist: pyqtgraph>=0.12
Provides-Extra: dev
Requires-Dist: pytest>=7; extra == "dev"
Requires-Dist: build>=1.0; extra == "dev"
Requires-Dist: twine>=4.0; extra == "dev"
Requires-Dist: uv>=0.4; extra == "dev"
Provides-Extra: docs
Requires-Dist: mkdocs>=1.5; extra == "docs"
Requires-Dist: mkdocs-material>=9.0; extra == "docs"
Requires-Dist: mkdocstrings[python]>=0.24; extra == "docs"
Requires-Dist: pymdown-extensions>=10.0; extra == "docs"
Dynamic: license-file

# TurtleWave hdEEG

High-density EEG processing for sleep research, extending [Wonambi](https://wonambi-python.github.io/) for large multi-channel datasets. Detects sleep spindles, slow waves, K-complexes, and phase–amplitude coupling, and ships PyQt5 GUIs for both detection (`turtlewave_gui`) and event review (`eeg_review_gui`).

[Documentation](https://turtlewave-hdeeg.readthedocs.io/) · [Source](https://github.com/TancyKao/TurtleWave-hdEEG) · [Issues](https://github.com/TancyKao/TurtleWave-hdEEG/issues)

## Install

```bash
pip install turtlewave-hdEEG
```

Requires Python ≥ 3.10. Tested on macOS, Linux, and Windows.

Launch a GUI:

```bash
turtlewave_gui          # detection
eeg_review_gui          # event review
```

Or use the library directly:

```python
from turtlewave_hdEEG import LargeDataset, ParalSWA, CustomAnnotations

dataset = LargeDataset("subject001.set")
annot = CustomAnnotations("subject001.xml")

proc = ParalSWA(dataset=dataset, annotations=annot)
slow_waves = proc.detect_slow_waves(
    method="AASM/Massimini2004",
    chan=["Cz", "Fz"],
    stage=["NREM2", "NREM3"],
    json_dir="sw_results",
)
```

Full examples for spindles, K-complexes, and PAC are in [`examples/`](examples/) and the [documentation](https://turtlewave-hdeeg.readthedocs.io/).

## Develop

```bash
git clone https://github.com/TancyKao/TurtleWave-hdEEG.git
cd TurtleWave-hdEEG

python3 -m venv .venv
source .venv/bin/activate           # macOS / Linux
# .venv\Scripts\activate            # Windows (PowerShell or cmd)

pip install -r requirements.txt
pip install -e ".[dev]"

python -c "import turtlewave_hdEEG; print(turtlewave_hdEEG.__version__)"
```

`requirements.txt` is a fully-pinned lockfile generated from `pyproject.toml` via `uv pip compile`. To regenerate after changing dependencies:

```bash
uv pip compile pyproject.toml --extra dev --extra docs --output-file requirements.txt
```

For docs work:

```bash
pip install -e ".[docs]"
mkdocs serve            # http://127.0.0.1:8000
```

## Repository layout

```
turtlewave_hdEEG/   # core library (detectors, processors, exporters)
frontend/           # PyQt5 GUIs
examples/           # standalone scripts and HPC batch templates
docs/               # MkDocs Material source
tests/              # smoke tests
```

HPC batch templates in `examples/NCI_commands/` target NCI Gadi (PBS) and use plain pip + venv on the cluster — no conda required.

## License

MIT — see [LICENSE](https://github.com/TancyKao/TurtleWave-hdEEG/blob/master/LICENSE).

## Citation

If you use TurtleWave in your research, please cite:

```bibtex
@software{turtlewave,
  title  = {TurtleWave hdEEG: High-density EEG event detection for sleep research},
  author = {Kao, Tancy},
  url    = {https://github.com/TancyKao/TurtleWave-hdEEG}
}
```
