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())
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.6.8
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Built distributions (wheels)
Total release size: 266.9 MB
Release files / lunapi-1.6.8-cp314-cp314-win_amd64.whl
| Download URL | lunapi-1.6.8-cp314-cp314-win_amd64.whl |
|---|---|
| Size | 12.1 MB |
| Tags | CPython 3.14 Windows x86-64 |
|
SHA-256 checksum How to use checksums |
0183caaadbb7d9d5b8ad4888c154648b3fa38dd5e0b84ef7eae6c865d41c7dd2
|
|
BLAKE2b-256 checksum How to use checksums |
37d068621e3c49d01b3567f0bc03a5540f9e7fac2dc91959f5d12c63560358d7
|
| 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.6.8-cp314-cp314-manylinux_2_28_x86_64.whl
| Download URL | lunapi-1.6.8-cp314-cp314-manylinux_2_28_x86_64.whl |
|---|---|
| Size | 13.8 MB |
| Tags | CPython 3.14 Linux glibc 2.28+ x86-64 |
|
SHA-256 checksum How to use checksums |
61b0b5019a61c64b256e68b4905aa6818a64fff834e51fb978fb78473aa44024
|
|
BLAKE2b-256 checksum How to use checksums |
1d415262682193b0f47033eddf821126a7d2c581f21dc808cad77fcdab9c1d5c
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.9.25
|
Release files / lunapi-1.6.8-cp314-cp314-macosx_11_0_arm64.whl
| Download URL | lunapi-1.6.8-cp314-cp314-macosx_11_0_arm64.whl |
|---|---|
| Size | 8.9 MB |
| Tags | CPython 3.14 macOS 11.0+ ARM64 |
|
SHA-256 checksum How to use checksums |
d0396dec82d38380efd415eee5afb50f6f779da55d47ab2aac6d2b341db44924
|
|
BLAKE2b-256 checksum How to use checksums |
a1bbf448189a43b444de4e7aadabd0d6188c6d7767c17f7385c5dda155c21419
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.9.13
|
Release files / lunapi-1.6.8-cp314-cp314-macosx_10_15_x86_64.whl
| Download URL | lunapi-1.6.8-cp314-cp314-macosx_10_15_x86_64.whl |
|---|---|
| Size | 9.9 MB |
| Tags | CPython 3.14 macOS 10.15+ x86-64 |
|
SHA-256 checksum How to use checksums |
c6debccfe4aa575a9a969c35585129642dc63e894eea04995baf58364b4d9e3e
|
|
BLAKE2b-256 checksum How to use checksums |
f2e4f67448c7e662a770379983d76828a77c1606d96f8c92e3bd60d4102a38b8
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.9.25
|
Release files / lunapi-1.6.8-cp313-cp313-win_amd64.whl
| Download URL | lunapi-1.6.8-cp313-cp313-win_amd64.whl |
|---|---|
| Size | 11.8 MB |
| Tags | CPython 3.13 Windows x86-64 |
|
SHA-256 checksum How to use checksums |
4c2ddc723d7fae65f63c1214e37476bd92f7f20ef09cc8e873a0e8c3b14c882b
|
|
BLAKE2b-256 checksum How to use checksums |
64e237538b8ed77b8ab0d61b1fe9e04fa4e54c9c2a5d206ddd9e0067766535b1
|
| 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.6.8-cp313-cp313-manylinux_2_28_x86_64.whl
| Download URL | lunapi-1.6.8-cp313-cp313-manylinux_2_28_x86_64.whl |
|---|---|
| Size | 13.8 MB |
| Tags | CPython 3.13 Linux glibc 2.28+ x86-64 |
|
SHA-256 checksum How to use checksums |
620ba7261bfa01cd58ca9560b35889ff0965e4cc83cb41f6986f31ad99cc7109
|
|
BLAKE2b-256 checksum How to use checksums |
5a208ab3fbb98070af1bfbd1b76a66302ff47c8843f53adf4c284443523538da
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.9.25
|
Release files / lunapi-1.6.8-cp313-cp313-macosx_11_0_arm64.whl
| Download URL | lunapi-1.6.8-cp313-cp313-macosx_11_0_arm64.whl |
|---|---|
| Size | 8.9 MB |
| Tags | CPython 3.13 macOS 11.0+ ARM64 |
|
SHA-256 checksum How to use checksums |
c6775e29446d4e4b6a7906c270af6e7586787227156cf4fde4eb2d5e611f6c37
|
|
BLAKE2b-256 checksum How to use checksums |
bb7bcc2d3286ba8e470a1a8697583d1344bf5d3ef09f768fca583fc02c4ecd48
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.9.13
|
Release files / lunapi-1.6.8-cp313-cp313-macosx_10_14_x86_64.whl
| Download URL | lunapi-1.6.8-cp313-cp313-macosx_10_14_x86_64.whl |
|---|---|
| Size | 9.9 MB |
| Tags | CPython 3.13 macOS 10.14+ x86-64 |
|
SHA-256 checksum How to use checksums |
d3e400f7b67236d9124e60fbc7473a36b6af9422b494bc79bf166a8990b1226e
|
|
BLAKE2b-256 checksum How to use checksums |
2ef4f8a5c3ae1c97917b40c03187c32c3f899b8542b12cca12c0c9271960247c
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.9.25
|
Release files / lunapi-1.6.8-cp312-cp312-win_amd64.whl
| Download URL | lunapi-1.6.8-cp312-cp312-win_amd64.whl |
|---|---|
| Size | 11.8 MB |
| Tags | CPython 3.12 Windows x86-64 |
|
SHA-256 checksum How to use checksums |
b6866c11f24a0eb15f4c2baaa35cf9aa3f5e4ed8a54e1187ef6ade26d542b218
|
|
BLAKE2b-256 checksum How to use checksums |
97bcc4437d3042cca8d02b27d72d75a937f18b2a2a2e3b3eb31644efd847b0b1
|
| 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.6.8-cp312-cp312-manylinux_2_28_x86_64.whl
| Download URL | lunapi-1.6.8-cp312-cp312-manylinux_2_28_x86_64.whl |
|---|---|
| Size | 13.8 MB |
| Tags | CPython 3.12 Linux glibc 2.28+ x86-64 |
|
SHA-256 checksum How to use checksums |
a3feaa4e96d58fbc308f013e8995075f802b36a6d1b97aa0bb7cbc1cb791993a
|
|
BLAKE2b-256 checksum How to use checksums |
d51735830d54090efbc4c84b185b7973e939d545e63e79233528639967fb6ebe
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.9.25
|
Release files / lunapi-1.6.8-cp312-cp312-macosx_11_0_arm64.whl
| Download URL | lunapi-1.6.8-cp312-cp312-macosx_11_0_arm64.whl |
|---|---|
| Size | 8.9 MB |
| Tags | CPython 3.12 macOS 11.0+ ARM64 |
|
SHA-256 checksum How to use checksums |
76ebf8bff45387af49b2947f585cd7049bb53b26e8757fd4256029a964fe3792
|
|
BLAKE2b-256 checksum How to use checksums |
96b50e949d1ea1a70114f8a5e5b01408da74ee110cc37f697e23c98ea4e0cffd
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.9.13
|
Release files / lunapi-1.6.8-cp312-cp312-macosx_10_14_x86_64.whl
| Download URL | lunapi-1.6.8-cp312-cp312-macosx_10_14_x86_64.whl |
|---|---|
| Size | 9.9 MB |
| Tags | CPython 3.12 macOS 10.14+ x86-64 |
|
SHA-256 checksum How to use checksums |
75253a6b244b06a78640635bd186caddfafd091ba9c7e169b7495dac26380266
|
|
BLAKE2b-256 checksum How to use checksums |
d44b30bf5137e60d98d0b4496061c85c9409f7948275ac1824dd3699f5cd08c3
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.9.25
|
Release files / lunapi-1.6.8-cp311-cp311-win_amd64.whl
| Download URL | lunapi-1.6.8-cp311-cp311-win_amd64.whl |
|---|---|
| Size | 11.8 MB |
| Tags | CPython 3.11 Windows x86-64 |
|
SHA-256 checksum How to use checksums |
e9c1b8907f35ace2bd2f163243c276ae5f3ff893f862499b7ba0c2258abe154c
|
|
BLAKE2b-256 checksum How to use checksums |
128760c76921681d7f30e24ca5854dd17874d6fff3f10b3d2ea71a81b69e4136
|
| 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.6.8-cp311-cp311-manylinux_2_28_x86_64.whl
| Download URL | lunapi-1.6.8-cp311-cp311-manylinux_2_28_x86_64.whl |
|---|---|
| Size | 13.8 MB |
| Tags | CPython 3.11 Linux glibc 2.28+ x86-64 |
|
SHA-256 checksum How to use checksums |
a08876dac7f4fb8bc173d4c796478c4e408bd64b3d251defc68f907fb0c20071
|
|
BLAKE2b-256 checksum How to use checksums |
e292b098f2e54259d1130fc6ee886f63b8e221ffc9e9cdaaa1986c7f02f174c1
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.9.25
|
Release files / lunapi-1.6.8-cp311-cp311-macosx_11_0_arm64.whl
| Download URL | lunapi-1.6.8-cp311-cp311-macosx_11_0_arm64.whl |
|---|---|
| Size | 8.9 MB |
| Tags | CPython 3.11 macOS 11.0+ ARM64 |
|
SHA-256 checksum How to use checksums |
b95874b88e1715317a6480e236fda41aecdb9625bca42509e91b3e2e074eb976
|
|
BLAKE2b-256 checksum How to use checksums |
a79a2baa3559ee335969c099f39a1d352892b78c7b73a1d4bf3e46157d0192fc
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.9.13
|
Release files / lunapi-1.6.8-cp311-cp311-macosx_10_14_x86_64.whl
| Download URL | lunapi-1.6.8-cp311-cp311-macosx_10_14_x86_64.whl |
|---|---|
| Size | 9.9 MB |
| Tags | CPython 3.11 macOS 10.14+ x86-64 |
|
SHA-256 checksum How to use checksums |
e6a105de1ab215c610738e70c9d8c67a91c07183910cb565f47ec6e9b485f639
|
|
BLAKE2b-256 checksum How to use checksums |
bdeebab575210b7f79f4cd3f2ec88e73a54d31b44dfbbbfe1f588c9967b8d842
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.9.25
|
Release files / lunapi-1.6.8-cp310-cp310-win_amd64.whl
| Download URL | lunapi-1.6.8-cp310-cp310-win_amd64.whl |
|---|---|
| Size | 11.8 MB |
| Tags | CPython 3.10 Windows x86-64 |
|
SHA-256 checksum How to use checksums |
de6beae04c5dfda84d3dcd2e11793852f4f2d47c9061f17d459ce5827b60adfa
|
|
BLAKE2b-256 checksum How to use checksums |
1cdf421430fd22e2c3f253a360be11abd0ba6dc0d750971490e3c6e27f0102ed
|
| 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.6.8-cp310-cp310-manylinux_2_28_x86_64.whl
| Download URL | lunapi-1.6.8-cp310-cp310-manylinux_2_28_x86_64.whl |
|---|---|
| Size | 13.8 MB |
| Tags | CPython 3.10 Linux glibc 2.28+ x86-64 |
|
SHA-256 checksum How to use checksums |
e0b34b97fefa7420a12d5e58ff003dbf54676a787806be2af3dd724887cd9f80
|
|
BLAKE2b-256 checksum How to use checksums |
4febc9cc15eeffb032cb654df429ee3a1904e5945b2b8c91f2a7de787d9134cd
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.9.25
|
Release files / lunapi-1.6.8-cp310-cp310-macosx_11_0_arm64.whl
| Download URL | lunapi-1.6.8-cp310-cp310-macosx_11_0_arm64.whl |
|---|---|
| Size | 8.9 MB |
| Tags | CPython 3.10 macOS 11.0+ ARM64 |
|
SHA-256 checksum How to use checksums |
06b15d161d6aebbdb6431dc2d6fe5042a8a713cc80b687bc9292cde92bf12dda
|
|
BLAKE2b-256 checksum How to use checksums |
67dddbbb671a9793547a241638b71058b7393475579b42cfeab6c136a5481973
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.9.13
|
Release files / lunapi-1.6.8-cp310-cp310-macosx_10_14_x86_64.whl
| Download URL | lunapi-1.6.8-cp310-cp310-macosx_10_14_x86_64.whl |
|---|---|
| Size | 9.9 MB |
| Tags | CPython 3.10 macOS 10.14+ x86-64 |
|
SHA-256 checksum How to use checksums |
b98ff896f329b209525fb76553d32bd3a69b6987e33cc9efc5a9cbf815b1954c
|
|
BLAKE2b-256 checksum How to use checksums |
2fcac756ef664477ec6a43965de9fc720378008f42e9889c5ef609b791fc8478
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.9.25
|
Release files / lunapi-1.6.8-cp39-cp39-win_amd64.whl
| Download URL | lunapi-1.6.8-cp39-cp39-win_amd64.whl |
|---|---|
| Size | 11.8 MB |
| Tags | CPython 3.9 Windows x86-64 |
|
SHA-256 checksum How to use checksums |
f72dec87f3b5b9e2b37c0707c736ce9c3a6f7c44247fd2222249767cb9366a9e
|
|
BLAKE2b-256 checksum How to use checksums |
6456d80f0b8443ef77f8cdc8a1472a6d1124140ca239e89016378a04a068244e
|
| 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.6.8-cp39-cp39-manylinux_2_28_x86_64.whl
| Download URL | lunapi-1.6.8-cp39-cp39-manylinux_2_28_x86_64.whl |
|---|---|
| Size | 13.8 MB |
| Tags | CPython 3.9 Linux glibc 2.28+ x86-64 |
|
SHA-256 checksum How to use checksums |
93e19f9282911584dde482358c166bda6441704376913a4e7bfa5b6c3f1a60ce
|
|
BLAKE2b-256 checksum How to use checksums |
60988a7601d820a3bf2a4d63a37c60d07d35ca0f1ed668d167bebb8065d207f1
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.9.25
|
Release files / lunapi-1.6.8-cp39-cp39-macosx_11_0_arm64.whl
| Download URL | lunapi-1.6.8-cp39-cp39-macosx_11_0_arm64.whl |
|---|---|
| Size | 8.9 MB |
| Tags | CPython 3.9 macOS 11.0+ ARM64 |
|
SHA-256 checksum How to use checksums |
e6ba2fa980864f3f46ce138c12c512e5710d7ad70a7caa621e8aca24d7b4ef19
|
|
BLAKE2b-256 checksum How to use checksums |
8d23d6dbbfe5985b2cf5464eb793700ee9f449d302dbd3c232e94cd1d24bca43
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.9.13
|
Release files / lunapi-1.6.8-cp39-cp39-macosx_10_14_x86_64.whl
| Download URL | lunapi-1.6.8-cp39-cp39-macosx_10_14_x86_64.whl |
|---|---|
| Size | 9.9 MB |
| Tags | CPython 3.9 macOS 10.14+ x86-64 |
|
SHA-256 checksum How to use checksums |
7ce5a51a43b9a9b1137186fa84c6172e081e44b46a9576017cfa2d97f7ef525b
|
|
BLAKE2b-256 checksum How to use checksums |
235eac1121f6176b838f006b3d99f03afbaf895ac63609bec3f9c4a85d5655a8
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.9.25
|
