lunapi
Python interface to the Luna C/C++ sleep-signal analysis engine.
lunapi exposes the full Luna command set to Python, enabling scripted and notebook-based workflows for polysomnographic (PSG) data — using the same analytical core as the Luna command-line tool and the Lunascope desktop application.
Statement of Need
Large-scale sleep research increasingly requires processing thousands of PSG recordings programmatically, while maintaining the ability to inspect individual records interactively. Existing Python EEG libraries are general-purpose frameworks that lack dedicated sleep-analysis primitives. lunapi provides direct Python access to Luna's domain-specific command set — covering spectral analysis, sleep staging, annotation handling, artifact detection, connectivity, and more — without requiring users to leave the Python/notebook environment or learn the Luna command-line interface.
Features
- Full Luna command set — run any Luna command (PSD, SPINDLES, SOAP, POPS, …) directly from Python and receive structured results as DataFrames
- Project-level workflows — load a sample list and execute commands across an entire cohort in a few lines
- Per-recording access — attach EDF and annotation files, extract raw signals and annotation events, insert or modify signals in memory
- Structured output — results returned as
pandasDataFrames keyed by command and stratum - SQLite result stores — write output to
.dbfiles that can be queried as virtual TSV-like tables - Sleep staging — SOAP and POPS automated staging models accessible directly from Python
- Visualization helpers — hypnogram, PSD, spectrogram, and topographic map plotting for notebooks
- NSRR Moonbeam — download and attach recordings directly from the National Sleep Research Resource
- GPA association modeling — linear association analysis on cohort-level result matrices
- Docker containers — pre-built images with Luna,
lunapi, and all dependencies
Installation
lunapi is distributed as a binary wheel via PyPI (no compiler required):
pip install lunapi
Supported platforms: macOS (Intel & Apple Silicon), Linux (x86_64), Windows 10/11 (x86_64), Python 3.9–3.14.
Using a virtual environment is recommended:
python3 -m venv .venv
source .venv/bin/activate # Windows: .venv\Scripts\activate
pip install lunapi
Worked Example
Single-recording workflow
import lunapi as lp
# Create a project and attach a recording
p = lp.proj(verbose=False)
rec = p.inst("my_subject")
rec.attach_edf("/path/to/recording.edf")
rec.attach_annot("/path/to/recording.annot")
# List available channels
print(rec.chs())
# Run a Luna command and retrieve results as a DataFrame
rec.eval("PSD sig=EEG dB spectrum")
df = rec.table("PSD", "CH_F")
print(df.head())
Cohort workflow
import lunapi as lp
p = lp.proj(verbose=False)
p.sample_list("study.lst") # three-column file: ID, EDF path, annot path
# Run PSD across all recordings (returns dict of DataFrames)
results = p.proc("PSD sig=EEG dB spectrum")
df = results["PSD"]["CH_F"]
print(df.groupby("CH")["PSD"].mean())
Python destrat command
The package also installs destrat.py, a Python/SQLite reader for Luna
output databases. It accepts the common native destrat query options,
including row and column stratifiers and level restrictions:
destrat.py out.db
destrat.py out.db +PSD -r CH F -v PSD
destrat.py out.db +PSD -r F/11,15 CH -c B -v PSD
Multiple databases and glob patterns are accepted. Extracted tables are
written as tab-delimited output to standard output, so they can be redirected
or piped to another program. The same reader is available from Python as
lp.destrat(...).
Automated sleep staging
rec.eval("RUN-POPS sig=C3 ref=M2 path=~/dropbox/pops") # point to downloaded POPS models
stages = rec.table("RUN_POPS", "E") # per-epoch predictions
print(stages["PRED"].value_counts())
Full documentation, command reference, and interactive notebooks are at zzz.nyspi.org/luna/.
Testing
pip install -e ".[dev]"
pytest
This runs 59 tests covering the core workflow (load instance, run commands, retrieve tables, extract signals, annotation handling, sample-list workflow), visualization helpers, GPA utilities, and package smoke tests. No real EDF files are required — a synthetic in-memory recording is generated by the test fixtures.
Documentation
| Resource | URL |
|---|---|
| Luna ecosystem | https://zzz.nyspi.org/luna/ |
| lunapi notebooks | https://github.com/remnrem/luna-api/tree/main/notebooks |
| Lunascope desktop app | https://github.com/Lorcan7274/lunascope |
| NSRR | https://sleepdata.org |
Contributing
See CONTRIBUTING.md for guidelines on bug reports, feature requests, and pull requests.
Questions / Support
Open an issue on GitHub or write to luna.remnrem@gmail.com.
1 maintainer
Metadata
1 maintainer
Release files for lunapi 1.7.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Built distributions (wheels)
Total release size: 340.1 MB
Release files / lunapi-1.7.0-cp314-cp314-win_amd64.whl
| Download URL | lunapi-1.7.0-cp314-cp314-win_amd64.whl |
|---|---|
| Size | 12.1 MB |
| Tags | CPython 3.14 Windows x86-64 |
|
SHA-256 checksum How to use checksums |
d011dd6e3d0f15cac5a0f272005c1444caaf2439bc0599478508c26eede07ed3
|
|
BLAKE2b-256 checksum How to use checksums |
d59d3e567189be3b94da0657ec8c08d1850611c1321c5bb919a9ef3122a898f1
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.13.15
|
Release files / lunapi-1.7.0-cp314-cp314-manylinux_2_28_x86_64.whl
| Download URL | lunapi-1.7.0-cp314-cp314-manylinux_2_28_x86_64.whl |
|---|---|
| Size | 13.9 MB |
| Tags | CPython 3.14 Linux glibc 2.28+ x86-64 |
|
SHA-256 checksum How to use checksums |
afc821d4d9dea05dba9ee77482fb33c099639435bd5bff144addd510b2e2b981
|
|
BLAKE2b-256 checksum How to use checksums |
b7f33f3bf22f27a93875b729879b22ea51bce4ee460b4580c90ad326dfa0ea05
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.10.21
|
Release files / lunapi-1.7.0-cp314-cp314-macosx_11_0_arm64.whl
| Download URL | lunapi-1.7.0-cp314-cp314-macosx_11_0_arm64.whl |
|---|---|
| Size | 14.5 MB |
| Tags | CPython 3.14 macOS 11.0+ ARM64 |
|
SHA-256 checksum How to use checksums |
afdc49f2b6b883d4aba206174443cdff80c9d50d6403fde556e7ca39b1c30d71
|
|
BLAKE2b-256 checksum How to use checksums |
b1b50c71af7485d40039a8b9803e704d43ee02146cf962f393a9763d58bd1617
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.10.11
|
Release files / lunapi-1.7.0-cp314-cp314-macosx_10_15_x86_64.whl
| Download URL | lunapi-1.7.0-cp314-cp314-macosx_10_15_x86_64.whl |
|---|---|
| Size | 16.4 MB |
| Tags | CPython 3.14 macOS 10.15+ x86-64 |
|
SHA-256 checksum How to use checksums |
3802310b2bb6ac20c38b7441d028b117e5c62f3f5de2dbd62948f8aaeb80081d
|
|
BLAKE2b-256 checksum How to use checksums |
aaa877491146bc0f37eeb8fc355c91d2c6cfff80a38affbb10f069cedb24c399
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.10.21
|
Release files / lunapi-1.7.0-cp313-cp313-win_amd64.whl
| Download URL | lunapi-1.7.0-cp313-cp313-win_amd64.whl |
|---|---|
| Size | 11.8 MB |
| Tags | CPython 3.13 Windows x86-64 |
|
SHA-256 checksum How to use checksums |
487015934c80a16117896e3af761633bcd154211c986fba43993f4878cd552e8
|
|
BLAKE2b-256 checksum How to use checksums |
3f13d499b7de8ea56c96d14ea06413d5c66291be4edf5d2fb1e3323c66ecfce5
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.13.15
|
Release files / lunapi-1.7.0-cp313-cp313-manylinux_2_28_x86_64.whl
| Download URL | lunapi-1.7.0-cp313-cp313-manylinux_2_28_x86_64.whl |
|---|---|
| Size | 13.9 MB |
| Tags | CPython 3.13 Linux glibc 2.28+ x86-64 |
|
SHA-256 checksum How to use checksums |
aa202bd700af7f86b379a4468bb528ae6576aa0b01e89eaeff34d245b531a2ba
|
|
BLAKE2b-256 checksum How to use checksums |
c09a32f3ef987662e5522292140453349a616bf99361ca56cf76c2ab07d1e1a7
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.10.21
|
Release files / lunapi-1.7.0-cp313-cp313-macosx_11_0_arm64.whl
| Download URL | lunapi-1.7.0-cp313-cp313-macosx_11_0_arm64.whl |
|---|---|
| Size | 14.5 MB |
| Tags | CPython 3.13 macOS 11.0+ ARM64 |
|
SHA-256 checksum How to use checksums |
105728fa28eb903992e2a3a72effc2a884503d34f5e184e4e16750d97a2f1184
|
|
BLAKE2b-256 checksum How to use checksums |
e12ef273f3e6402ce678f1f81ca349ddb106e493707b1a2168fcc4322571ec25
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.10.11
|
Release files / lunapi-1.7.0-cp313-cp313-macosx_10_15_x86_64.whl
| Download URL | lunapi-1.7.0-cp313-cp313-macosx_10_15_x86_64.whl |
|---|---|
| Size | 16.4 MB |
| Tags | CPython 3.13 macOS 10.15+ x86-64 |
|
SHA-256 checksum How to use checksums |
67826452ee44fe03d61c201b55a6ccadb5530407f0389fcf098fc29348b05d99
|
|
BLAKE2b-256 checksum How to use checksums |
ef968a351cf42549b0cb7ad7c837a0c2bcbc776de98970e57f97b39b0b49543b
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.10.21
|
Release files / lunapi-1.7.0-cp312-cp312-win_amd64.whl
| Download URL | lunapi-1.7.0-cp312-cp312-win_amd64.whl |
|---|---|
| Size | 11.8 MB |
| Tags | CPython 3.12 Windows x86-64 |
|
SHA-256 checksum How to use checksums |
bb6d3c7752e921edd9f13030d418e63f1312c20ee1101fc133fe89049f9ab94c
|
|
BLAKE2b-256 checksum How to use checksums |
7ea66c05cc32e54f5e044f70ab3be3153f599e7cfc50a251f00111761872393a
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.13.15
|
Release files / lunapi-1.7.0-cp312-cp312-manylinux_2_28_x86_64.whl
| Download URL | lunapi-1.7.0-cp312-cp312-manylinux_2_28_x86_64.whl |
|---|---|
| Size | 13.9 MB |
| Tags | CPython 3.12 Linux glibc 2.28+ x86-64 |
|
SHA-256 checksum How to use checksums |
06719095366da49acb8ead9697325e3f92c46bcda68d70f553e50733aa07350f
|
|
BLAKE2b-256 checksum How to use checksums |
3c828cbf1eb583c5c14401e846e7141e68cedb205ff496b63d9ef3fc26b1555f
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.10.21
|
Release files / lunapi-1.7.0-cp312-cp312-macosx_11_0_arm64.whl
| Download URL | lunapi-1.7.0-cp312-cp312-macosx_11_0_arm64.whl |
|---|---|
| Size | 14.5 MB |
| Tags | CPython 3.12 macOS 11.0+ ARM64 |
|
SHA-256 checksum How to use checksums |
bf463431ccfab71016b541368fa5a099b746fd41a32058fedd9bffd757842cb9
|
|
BLAKE2b-256 checksum How to use checksums |
c1ee3d4aeaa46a0b00eab38a076e0c7399eaa55456dd0946e11dc57de537a162
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.10.11
|
Release files / lunapi-1.7.0-cp312-cp312-macosx_10_15_x86_64.whl
| Download URL | lunapi-1.7.0-cp312-cp312-macosx_10_15_x86_64.whl |
|---|---|
| Size | 16.4 MB |
| Tags | CPython 3.12 macOS 10.15+ x86-64 |
|
SHA-256 checksum How to use checksums |
1182728c32f9aabf389cc5f976ee6dc4a453354c66c0e70b502b82e87ca1ba05
|
|
BLAKE2b-256 checksum How to use checksums |
aa890b0e497728e15e0635404bde74ed1b06574842d01afa2567978b6ffb02d1
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.10.21
|
Release files / lunapi-1.7.0-cp311-cp311-win_amd64.whl
| Download URL | lunapi-1.7.0-cp311-cp311-win_amd64.whl |
|---|---|
| Size | 11.8 MB |
| Tags | CPython 3.11 Windows x86-64 |
|
SHA-256 checksum How to use checksums |
4b7f1bbc2c203208a9d56f3a5311e3d3b536e8f70a34c21e1276fbb3862c1a40
|
|
BLAKE2b-256 checksum How to use checksums |
4ff1acbee46f0e681dd06a5f94336f2f0a38e488b6cc015664de188e66da4c4a
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.13.15
|
Release files / lunapi-1.7.0-cp311-cp311-manylinux_2_28_x86_64.whl
| Download URL | lunapi-1.7.0-cp311-cp311-manylinux_2_28_x86_64.whl |
|---|---|
| Size | 13.9 MB |
| Tags | CPython 3.11 Linux glibc 2.28+ x86-64 |
|
SHA-256 checksum How to use checksums |
f6c488a34d1529c7265d484d9f209970989a0f52724a7888dc6df856c54a3c99
|
|
BLAKE2b-256 checksum How to use checksums |
5c6af2f6fe63cb3432e3267eb81b14fc30fa56090ef7b9096c9ef7ac34be8d57
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.10.21
|
Release files / lunapi-1.7.0-cp311-cp311-macosx_11_0_arm64.whl
| Download URL | lunapi-1.7.0-cp311-cp311-macosx_11_0_arm64.whl |
|---|---|
| Size | 14.5 MB |
| Tags | CPython 3.11 macOS 11.0+ ARM64 |
|
SHA-256 checksum How to use checksums |
0f7e4cd3893a87533c4de08760efa1999cddc617f3f28a877ada14f4ad7cd37d
|
|
BLAKE2b-256 checksum How to use checksums |
51232be075e16ab1fc7173ad662f1e5f0c26469b4add10a4903cafa31c154b59
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.10.11
|
Release files / lunapi-1.7.0-cp311-cp311-macosx_10_15_x86_64.whl
| Download URL | lunapi-1.7.0-cp311-cp311-macosx_10_15_x86_64.whl |
|---|---|
| Size | 16.4 MB |
| Tags | CPython 3.11 macOS 10.15+ x86-64 |
|
SHA-256 checksum How to use checksums |
c8ee80b41e67e73093092bfc18cfca1e66e8a5cb1cecd2aad643ad1117e6b846
|
|
BLAKE2b-256 checksum How to use checksums |
a1264fc59974c60129e0c72dbf5c90d1103128810be83df68c784f4113a30329
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.10.21
|
Release files / lunapi-1.7.0-cp310-cp310-win_amd64.whl
| Download URL | lunapi-1.7.0-cp310-cp310-win_amd64.whl |
|---|---|
| Size | 11.8 MB |
| Tags | CPython 3.10 Windows x86-64 |
|
SHA-256 checksum How to use checksums |
221d6d78c4c16c6dcf8a68cc7619f291fbd91d486feb4c3dc6f4ef3d639936eb
|
|
BLAKE2b-256 checksum How to use checksums |
0eab060e147622ea550f5ae55133ff974943861a2aba245fa17d2178727c2dc0
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.13.15
|
Release files / lunapi-1.7.0-cp310-cp310-manylinux_2_28_x86_64.whl
| Download URL | lunapi-1.7.0-cp310-cp310-manylinux_2_28_x86_64.whl |
|---|---|
| Size | 13.9 MB |
| Tags | CPython 3.10 Linux glibc 2.28+ x86-64 |
|
SHA-256 checksum How to use checksums |
0b97d3e5d39d1b7c61cd33bae576a69900f5410d0a3db89f9feabbe13b2890f5
|
|
BLAKE2b-256 checksum How to use checksums |
56cb4fd2a54b03aa772bc1c000a40724d806313bba811513ac3bd766e4b97816
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.10.21
|
Release files / lunapi-1.7.0-cp310-cp310-macosx_11_0_arm64.whl
| Download URL | lunapi-1.7.0-cp310-cp310-macosx_11_0_arm64.whl |
|---|---|
| Size | 14.5 MB |
| Tags | CPython 3.10 macOS 11.0+ ARM64 |
|
SHA-256 checksum How to use checksums |
c685056a17c38acb374eb6c0bca9a5e9f62b94275bc18f1c0b89ae08f91b39f8
|
|
BLAKE2b-256 checksum How to use checksums |
3471a5b37bf2a209f35c07f04fc1493e5296b4629bb9c2171e5c73479fff4c89
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.10.11
|
Release files / lunapi-1.7.0-cp310-cp310-macosx_10_15_x86_64.whl
| Download URL | lunapi-1.7.0-cp310-cp310-macosx_10_15_x86_64.whl |
|---|---|
| Size | 16.4 MB |
| Tags | CPython 3.10 macOS 10.15+ x86-64 |
|
SHA-256 checksum How to use checksums |
39e0189efe2acac13edfa00326312f5b2e18514fcc7c98ad26082bccc9a849ba
|
|
BLAKE2b-256 checksum How to use checksums |
a310848c8f1b410c8eca7a7784e77619abbb0d5b4b95c00033928b6e62a9948b
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.10.21
|
Release files / lunapi-1.7.0-cp39-cp39-win_amd64.whl
| Download URL | lunapi-1.7.0-cp39-cp39-win_amd64.whl |
|---|---|
| Size | 11.8 MB |
| Tags | CPython 3.9 Windows x86-64 |
|
SHA-256 checksum How to use checksums |
7362270f974d44e78860fb81ac67d019d7b0efbbdc35950f7d726462fdcfbcaa
|
|
BLAKE2b-256 checksum How to use checksums |
e7ca9baa97f04ea20e53225974fdfc7249a562dd30668941a9ff1f28ff3f8347
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.13.15
|
Release files / lunapi-1.7.0-cp39-cp39-manylinux_2_28_x86_64.whl
| Download URL | lunapi-1.7.0-cp39-cp39-manylinux_2_28_x86_64.whl |
|---|---|
| Size | 13.9 MB |
| Tags | CPython 3.9 Linux glibc 2.28+ x86-64 |
|
SHA-256 checksum How to use checksums |
704c5fbeeddbffb32fe7521481373e26d6cc3fcabd9fcc72341776c8a3b74187
|
|
BLAKE2b-256 checksum How to use checksums |
2aa715f49a0c7e1d7e685bd8ef912df7214f65823f9d3567c25de32bdb681720
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.10.21
|
Release files / lunapi-1.7.0-cp39-cp39-macosx_11_0_arm64.whl
| Download URL | lunapi-1.7.0-cp39-cp39-macosx_11_0_arm64.whl |
|---|---|
| Size | 14.5 MB |
| Tags | CPython 3.9 macOS 11.0+ ARM64 |
|
SHA-256 checksum How to use checksums |
b38a585efd1368d943bca0b0313729273bf4720d00d8964ed3fbffc10930e2f1
|
|
BLAKE2b-256 checksum How to use checksums |
a2d875056b9ce238faa228ae44f392b174ae1a9b9ac8023af24c5babe1f433fb
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.10.11
|
Release files / lunapi-1.7.0-cp39-cp39-macosx_10_15_x86_64.whl
| Download URL | lunapi-1.7.0-cp39-cp39-macosx_10_15_x86_64.whl |
|---|---|
| Size | 16.4 MB |
| Tags | CPython 3.9 macOS 10.15+ x86-64 |
|
SHA-256 checksum How to use checksums |
21cf766d451c00ad282dd9eac8c014d54af9aa86cd43f73f80f5b2c151dcc186
|
|
BLAKE2b-256 checksum How to use checksums |
d26e435fb9f893ba71895f728cd9b8f02417c544c8938b59979c6dee4d2a3a9e
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.10.21
|
