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.
Metadata
Release files for lunapi 1.6.7
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Built distributions (wheels)
Total release size: 261.8 MB
Release files / lunapi-1.6.7-cp314-cp314-win_amd64.whl
| Download URL | lunapi-1.6.7-cp314-cp314-win_amd64.whl |
|---|---|
| Size | 11.9 MB |
| Tags | CPython 3.14 Windows x86-64 |
|
SHA-256 checksum How to use checksums |
755107e4f169788dad5174ff1a97091f4d8d1e1a20a57940fe26ce145df96dca
|
|
BLAKE2b-256 checksum How to use checksums |
c404d1191885423083f75bfa5325f1b351e6b2c7d66872c260e27d1bfb31d346
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.13.14
|
Release files / lunapi-1.6.7-cp314-cp314-manylinux_2_28_x86_64.whl
| Download URL | lunapi-1.6.7-cp314-cp314-manylinux_2_28_x86_64.whl |
|---|---|
| Size | 13.5 MB |
| Tags | CPython 3.14 Linux glibc 2.28+ x86-64 |
|
SHA-256 checksum How to use checksums |
4b43b734d6de8c5f424cd75ec4dcd4435867396369b0cb5dacffd9f82c037776
|
|
BLAKE2b-256 checksum How to use checksums |
6ebdca926affe7c6fec548dcad872f5bbfbd9ca827cde733153bea11af28397a
|
| 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.7-cp314-cp314-macosx_11_0_arm64.whl
| Download URL | lunapi-1.6.7-cp314-cp314-macosx_11_0_arm64.whl |
|---|---|
| Size | 8.7 MB |
| Tags | CPython 3.14 macOS 11.0+ ARM64 |
|
SHA-256 checksum How to use checksums |
a6d0325e2dd0e1b33fc1654f22d79bf9ddc1bb6ca5062efa8de1596ecb04ffca
|
|
BLAKE2b-256 checksum How to use checksums |
0b4b75e61ebe2b399396e9032b134ebcb368c6a009331a66913b241116386617
|
| 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.7-cp314-cp314-macosx_10_15_x86_64.whl
| Download URL | lunapi-1.6.7-cp314-cp314-macosx_10_15_x86_64.whl |
|---|---|
| Size | 9.7 MB |
| Tags | CPython 3.14 macOS 10.15+ x86-64 |
|
SHA-256 checksum How to use checksums |
70febd64a1a55e5f02e7cf31ea8d339ee03ae674633758c90f485cf1d5b5d977
|
|
BLAKE2b-256 checksum How to use checksums |
667550d3a2b008623a3284f6dc1d9c33643727e2d388f1a091c20c23b1d71b47
|
| 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.7-cp313-cp313-win_amd64.whl
| Download URL | lunapi-1.6.7-cp313-cp313-win_amd64.whl |
|---|---|
| Size | 11.7 MB |
| Tags | CPython 3.13 Windows x86-64 |
|
SHA-256 checksum How to use checksums |
85295c8b775819151bfd93ae4b83b32904643c8f4273688c1da673622fa0e8f9
|
|
BLAKE2b-256 checksum How to use checksums |
913e9d97055d9f98744d4871e97e19fa49444e0a671e623a705f1f07dcdb06fc
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.13.14
|
Release files / lunapi-1.6.7-cp313-cp313-manylinux_2_28_x86_64.whl
| Download URL | lunapi-1.6.7-cp313-cp313-manylinux_2_28_x86_64.whl |
|---|---|
| Size | 13.5 MB |
| Tags | CPython 3.13 Linux glibc 2.28+ x86-64 |
|
SHA-256 checksum How to use checksums |
48c77ef7732bbf4c59d66c11934b91d866024032958fda5b49cd88223fb81914
|
|
BLAKE2b-256 checksum How to use checksums |
0a685fcfd3e679169feedd846bc7b7cd8ecc037938fa5e644ee39bf2cdcccfed
|
| 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.7-cp313-cp313-macosx_11_0_arm64.whl
| Download URL | lunapi-1.6.7-cp313-cp313-macosx_11_0_arm64.whl |
|---|---|
| Size | 8.7 MB |
| Tags | CPython 3.13 macOS 11.0+ ARM64 |
|
SHA-256 checksum How to use checksums |
ba0154bbe94523ce5106265af33406cc1eaa968279dc44372d0daa91db3baaa9
|
|
BLAKE2b-256 checksum How to use checksums |
5f6c4f08e1d821024fac6fc5f7bea337fe21750b3388c6e5e937b24915763110
|
| 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.7-cp313-cp313-macosx_10_14_x86_64.whl
| Download URL | lunapi-1.6.7-cp313-cp313-macosx_10_14_x86_64.whl |
|---|---|
| Size | 9.7 MB |
| Tags | CPython 3.13 macOS 10.14+ x86-64 |
|
SHA-256 checksum How to use checksums |
1ce87fe168b3ca7d2c9218e8c4a47abbc5b5fc6221773fc057c7f2f1bf5d8939
|
|
BLAKE2b-256 checksum How to use checksums |
bffb6acd565f2c8f507a7fa8b9ab13499f2d0fd7dab15eb636127a97666889d9
|
| 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.7-cp312-cp312-win_amd64.whl
| Download URL | lunapi-1.6.7-cp312-cp312-win_amd64.whl |
|---|---|
| Size | 11.7 MB |
| Tags | CPython 3.12 Windows x86-64 |
|
SHA-256 checksum How to use checksums |
57ffe3213d57e8807e9a5cbcae6292986f123fe6256728015b90794102a7e469
|
|
BLAKE2b-256 checksum How to use checksums |
ef3e0763c5420fd2230fbba392b27991ac99fd936639244a4ea2f4f6f03d9ab1
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.13.14
|
Release files / lunapi-1.6.7-cp312-cp312-manylinux_2_28_x86_64.whl
| Download URL | lunapi-1.6.7-cp312-cp312-manylinux_2_28_x86_64.whl |
|---|---|
| Size | 13.5 MB |
| Tags | CPython 3.12 Linux glibc 2.28+ x86-64 |
|
SHA-256 checksum How to use checksums |
0c71bdf212e927c0a039fc6d56bcf56f42ffb155eb13213a83c315c934c9b7bf
|
|
BLAKE2b-256 checksum How to use checksums |
5c7f087072072878bdd60ed1a84b20edec136ed3272ecd1a9fbab5f9ee368e0c
|
| 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.7-cp312-cp312-macosx_11_0_arm64.whl
| Download URL | lunapi-1.6.7-cp312-cp312-macosx_11_0_arm64.whl |
|---|---|
| Size | 8.7 MB |
| Tags | CPython 3.12 macOS 11.0+ ARM64 |
|
SHA-256 checksum How to use checksums |
519476d1a34e3e5fbfa2703aca0333f4cd1bdf254d9ffd254fbd057ffe0a805d
|
|
BLAKE2b-256 checksum How to use checksums |
086346c8f460c9da630213fbab612914da32e1b4183bb592c2575b77b74bcc20
|
| 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.7-cp312-cp312-macosx_10_14_x86_64.whl
| Download URL | lunapi-1.6.7-cp312-cp312-macosx_10_14_x86_64.whl |
|---|---|
| Size | 9.7 MB |
| Tags | CPython 3.12 macOS 10.14+ x86-64 |
|
SHA-256 checksum How to use checksums |
ed2f443c8b08b53d61feafc789231ab641af150a7d1a79ff3b7eb3c622eaa38e
|
|
BLAKE2b-256 checksum How to use checksums |
f1c36057d3ff7a3696a4582c00b3e59c19e4e42b1e420384e391b35421ad7930
|
| 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.7-cp311-cp311-win_amd64.whl
| Download URL | lunapi-1.6.7-cp311-cp311-win_amd64.whl |
|---|---|
| Size | 11.7 MB |
| Tags | CPython 3.11 Windows x86-64 |
|
SHA-256 checksum How to use checksums |
a566ccd3535b50228ff661422baf94489747970c1eeb2607266a2a2c9a8d0510
|
|
BLAKE2b-256 checksum How to use checksums |
6ed9741c4e5b114d12940d446325d08630ea40f0239069c953c29ae1da55c1a4
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.13.14
|
Release files / lunapi-1.6.7-cp311-cp311-manylinux_2_28_x86_64.whl
| Download URL | lunapi-1.6.7-cp311-cp311-manylinux_2_28_x86_64.whl |
|---|---|
| Size | 13.5 MB |
| Tags | CPython 3.11 Linux glibc 2.28+ x86-64 |
|
SHA-256 checksum How to use checksums |
740021934f03b88045597e893fbdd4953234557c3aa4d973d1f9a863d605c976
|
|
BLAKE2b-256 checksum How to use checksums |
4c4cb8107d77b1b89eaf3ea6526c5b18ac9227cda263963930f4c79283d346fb
|
| 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.7-cp311-cp311-macosx_11_0_arm64.whl
| Download URL | lunapi-1.6.7-cp311-cp311-macosx_11_0_arm64.whl |
|---|---|
| Size | 8.7 MB |
| Tags | CPython 3.11 macOS 11.0+ ARM64 |
|
SHA-256 checksum How to use checksums |
7f38ed1746d57f7de9b88d3117a339156772a4d7465ec21090862f022122c98b
|
|
BLAKE2b-256 checksum How to use checksums |
c45f75195fa035dc993de65b0883306f9aece1eb5dab4ea153e051e152a6c665
|
| 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.7-cp311-cp311-macosx_10_14_x86_64.whl
| Download URL | lunapi-1.6.7-cp311-cp311-macosx_10_14_x86_64.whl |
|---|---|
| Size | 9.7 MB |
| Tags | CPython 3.11 macOS 10.14+ x86-64 |
|
SHA-256 checksum How to use checksums |
1e061282df8908f3434e7f1936b867186a532b346743859e79a4cac7a59604f3
|
|
BLAKE2b-256 checksum How to use checksums |
42414c715ae6ca6481a4eb92f262d681c7062509f68cf3d466256bb3340363ae
|
| 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.7-cp310-cp310-win_amd64.whl
| Download URL | lunapi-1.6.7-cp310-cp310-win_amd64.whl |
|---|---|
| Size | 11.7 MB |
| Tags | CPython 3.10 Windows x86-64 |
|
SHA-256 checksum How to use checksums |
85b959657cc8f02638ccea6f3fef6a6600c7cfa7f27e15b38fa1c103b3d5af92
|
|
BLAKE2b-256 checksum How to use checksums |
27523132312f0970011cce60b05179559b5b8287bc0f69b0faaa9026e101f49b
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.13.14
|
Release files / lunapi-1.6.7-cp310-cp310-manylinux_2_28_x86_64.whl
| Download URL | lunapi-1.6.7-cp310-cp310-manylinux_2_28_x86_64.whl |
|---|---|
| Size | 13.5 MB |
| Tags | CPython 3.10 Linux glibc 2.28+ x86-64 |
|
SHA-256 checksum How to use checksums |
f3f65daf63b2646e58828e2d51c9dee511f9cf621d2f3d5a82bc013512459111
|
|
BLAKE2b-256 checksum How to use checksums |
c3508445785b538179007a8c42aec20fd726e64d83895f4a1186d7acd86e30b7
|
| 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.7-cp310-cp310-macosx_11_0_arm64.whl
| Download URL | lunapi-1.6.7-cp310-cp310-macosx_11_0_arm64.whl |
|---|---|
| Size | 8.7 MB |
| Tags | CPython 3.10 macOS 11.0+ ARM64 |
|
SHA-256 checksum How to use checksums |
550c012c117903a30e66adf2fe5abce0133ddc1ea84b5bb7b4f8a35be64fc14c
|
|
BLAKE2b-256 checksum How to use checksums |
32400a279f664fdbb977ab421bd8b01fa99ded9c3e872ee685d7f38059c92354
|
| 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.7-cp310-cp310-macosx_10_14_x86_64.whl
| Download URL | lunapi-1.6.7-cp310-cp310-macosx_10_14_x86_64.whl |
|---|---|
| Size | 9.7 MB |
| Tags | CPython 3.10 macOS 10.14+ x86-64 |
|
SHA-256 checksum How to use checksums |
b95fe6536e86e90355d61e1728771fe02b3fdb3cd12b5245e862dd1b6e0e0724
|
|
BLAKE2b-256 checksum How to use checksums |
7eee44035ffac84837693b079f53b791eebfd8960278cb2e873867db60d8da80
|
| 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.7-cp39-cp39-win_amd64.whl
| Download URL | lunapi-1.6.7-cp39-cp39-win_amd64.whl |
|---|---|
| Size | 11.7 MB |
| Tags | CPython 3.9 Windows x86-64 |
|
SHA-256 checksum How to use checksums |
0832906df70f5896aaee94ad6434759c94cdca72814253540a1f5fabfa021583
|
|
BLAKE2b-256 checksum How to use checksums |
8565bdc08f89feec1afa28fc63043a4ca13c0c6f4bfefff0e21e51d981e6d3a2
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.13.14
|
Release files / lunapi-1.6.7-cp39-cp39-manylinux_2_28_x86_64.whl
| Download URL | lunapi-1.6.7-cp39-cp39-manylinux_2_28_x86_64.whl |
|---|---|
| Size | 13.5 MB |
| Tags | CPython 3.9 Linux glibc 2.28+ x86-64 |
|
SHA-256 checksum How to use checksums |
58889095c0f9bdd30891b1353b6687e7440f1bc121834b1e3fe61e1d7625f683
|
|
BLAKE2b-256 checksum How to use checksums |
ca43da3646d2f52b5d495fa2ea4b945dadb48f92ddc8eb82728bd3bd4c38002c
|
| 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.7-cp39-cp39-macosx_11_0_arm64.whl
| Download URL | lunapi-1.6.7-cp39-cp39-macosx_11_0_arm64.whl |
|---|---|
| Size | 8.7 MB |
| Tags | CPython 3.9 macOS 11.0+ ARM64 |
|
SHA-256 checksum How to use checksums |
327018d1312415f998d14292bb2b77a2e79f6f036b80dd48ce5065f1e19d6458
|
|
BLAKE2b-256 checksum How to use checksums |
ad724b53e8fbabca2df5e9755e756245ab98468a4c16d14b2d864e87a73acb8e
|
| 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.7-cp39-cp39-macosx_10_14_x86_64.whl
| Download URL | lunapi-1.6.7-cp39-cp39-macosx_10_14_x86_64.whl |
|---|---|
| Size | 9.7 MB |
| Tags | CPython 3.9 macOS 10.14+ x86-64 |
|
SHA-256 checksum How to use checksums |
5e51d6ff05da9f36decf6a5b3ac9bec3206dfeddd183a084836e39e3ad95df2f
|
|
BLAKE2b-256 checksum How to use checksums |
099bf0b944a6f534bb011e1ddf33b9c07e83fd2e5c0f8d31b8f4844ffb9af96f
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.9.25
|