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.9
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Built distributions (wheels)
Total release size: 268.2 MB
Release files / lunapi-1.6.9-cp314-cp314-manylinux_2_28_x86_64.whl
| Download URL | lunapi-1.6.9-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 |
3f4b8172e5d78e79c8248ed21bf2bbcb15b3d2819c05c30076780cd4e44d576f
|
|
BLAKE2b-256 checksum How to use checksums |
22440dc3ff71d47822ea424f2c68ead58953860e252cb7ff6114e8c0440dea2d
|
| 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.6.9-cp314-cp314-macosx_11_0_arm64.whl
| Download URL | lunapi-1.6.9-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 |
b81f85e543ac8624ee2ec15af481573a304efcb51d74330663cdf80f147e2269
|
|
BLAKE2b-256 checksum How to use checksums |
f7e74e10512573bfbb45b2270e9f812e8180e3dc5240485502a858c00d143a8f
|
| 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.6.9-cp314-cp314-macosx_10_15_x86_64.whl
| Download URL | lunapi-1.6.9-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 |
03358ad85498b226b48d8ee1af17343348ae81c681f4e7172de141979ad1157b
|
|
BLAKE2b-256 checksum How to use checksums |
a8eae28431cfe4cb62b91c91774c38bbfb24ba243aecce27ab3c07005c60c1dc
|
| 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.6.9-cp313-cp313-manylinux_2_28_x86_64.whl
| Download URL | lunapi-1.6.9-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 |
be6e3588087c6267e923b7343e7570136cbaadd05b32b2ab83eaa525f188227c
|
|
BLAKE2b-256 checksum How to use checksums |
c4a77e1212bcf35330f0d50f4ab8cbd17055662342a252c15ac9d13a79b5cd3c
|
| 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.6.9-cp313-cp313-macosx_11_0_arm64.whl
| Download URL | lunapi-1.6.9-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 |
c4a4e7d022eb50132bca9b2448b67c29f020b7a25a12e7da6eff3389c460885e
|
|
BLAKE2b-256 checksum How to use checksums |
ec559de41ecadc61af9fbdbc0f500b14f8ae679dee3762c0fd017e254cebec4e
|
| 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.6.9-cp313-cp313-macosx_10_15_x86_64.whl
| Download URL | lunapi-1.6.9-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 |
a7a88744b6a8519c8ccf05615008b0258e9bc33ca09b697685dcf6ca83c53a55
|
|
BLAKE2b-256 checksum How to use checksums |
fa89f9d8c44186a66310880e878fdec53a79cb16e4b82006e4c5ced31288c458
|
| 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.6.9-cp312-cp312-manylinux_2_28_x86_64.whl
| Download URL | lunapi-1.6.9-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 |
f104767490e60bb0a50c3037b2e5f2a0e2c76c6941c7705a2f211fdcb97a9d76
|
|
BLAKE2b-256 checksum How to use checksums |
08469e2a510dd79d9ae6f7acee09e40f9fa93631333cc7764fb27d049a4ab91e
|
| 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.6.9-cp312-cp312-macosx_11_0_arm64.whl
| Download URL | lunapi-1.6.9-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 |
bebc2bad64949b37714bcbeb647d0000b5807d96072bc8faf05b52def5e0f5e1
|
|
BLAKE2b-256 checksum How to use checksums |
7994fead3bc52776bb96f74d54f89542f99e15667d71adf5f211a8f2d8fb34ad
|
| 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.6.9-cp312-cp312-macosx_10_15_x86_64.whl
| Download URL | lunapi-1.6.9-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 |
c49e5713899dcb04701776ea9627243a372bd8acc036913f7d64fccadd7b5331
|
|
BLAKE2b-256 checksum How to use checksums |
43f3506f1ace4850549ff68220c773d6da1903bdd8b915fcfed0bbae5183343f
|
| 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.6.9-cp311-cp311-manylinux_2_28_x86_64.whl
| Download URL | lunapi-1.6.9-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 |
0abfb343f2f7362695582e8e249d8c9ea39c98e79910d785756de62fb9ce905f
|
|
BLAKE2b-256 checksum How to use checksums |
086e86dc3d6798da63af0e9132c3153b746e11500cdadef8fd3b1b00ccce0574
|
| 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.6.9-cp311-cp311-macosx_11_0_arm64.whl
| Download URL | lunapi-1.6.9-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 |
2d13ab830bb7b02dbbe7403cd25d6059bf68a6aad63636370bff7457e244789f
|
|
BLAKE2b-256 checksum How to use checksums |
fd58b22c68c8b69dd938a354b45163a8ca0b41848eddd88411ee8bc4fa02747d
|
| 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.6.9-cp311-cp311-macosx_10_15_x86_64.whl
| Download URL | lunapi-1.6.9-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 |
98f5fb95ececb7cf7d675184fbcd968ea8d6a6c91b9d3bb96b39a064603dc03e
|
|
BLAKE2b-256 checksum How to use checksums |
c739d68134925d8db8945146ca70e01f9aa02fd1b88c14f786cc3b78263dd162
|
| 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.6.9-cp310-cp310-manylinux_2_28_x86_64.whl
| Download URL | lunapi-1.6.9-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 |
ed3985a47b6beb1b18b00f23d29ac4efb4175f2e700e70b60bd5c545f00010fb
|
|
BLAKE2b-256 checksum How to use checksums |
780eea5863c0613c3b103f56eb051f78b0e89eba08986abee82d66dda472fc2d
|
| 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.6.9-cp310-cp310-macosx_11_0_arm64.whl
| Download URL | lunapi-1.6.9-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 |
adfebb101c26027555496e73e0e5bc70d315e2fc58104fe122b9536a2ed0076d
|
|
BLAKE2b-256 checksum How to use checksums |
59c4de4cae87fa5aee1206ae7a3170caa1c8a7a1be7985eb56441e2540a85fc4
|
| 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.6.9-cp310-cp310-macosx_10_15_x86_64.whl
| Download URL | lunapi-1.6.9-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 |
3d2c3f71e092a4bffe4a346b6700c763ebcc5b3d41c933f262fdd6a68bad5ed2
|
|
BLAKE2b-256 checksum How to use checksums |
4943b420c6a352d1a34ed6bd1e7597b32559b6c6bd5bb50f818464f4b527ee7a
|
| 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.6.9-cp39-cp39-manylinux_2_28_x86_64.whl
| Download URL | lunapi-1.6.9-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 |
43fc2de88550b793e21959ef813f2663d2efb42a9af30d3a6b86a5ba2ef57be3
|
|
BLAKE2b-256 checksum How to use checksums |
a4b50a85bc2653ebe72f097a63afbf514469effa58943944bd4a12d0925c46b5
|
| 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.6.9-cp39-cp39-macosx_11_0_arm64.whl
| Download URL | lunapi-1.6.9-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 |
0614e462a9839a8899506270d6ec327da9788383698eacfc801372d5f6d60fa1
|
|
BLAKE2b-256 checksum How to use checksums |
615e2ca2a811529dff125250c2d1c4fce73ba006a3cd672c762d7ebcaae92ce9
|
| 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.6.9-cp39-cp39-macosx_10_15_x86_64.whl
| Download URL | lunapi-1.6.9-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 |
4fbd696793bcc51b7f1be0ebe63c17341876dea2ecce1a7cf5d481fd29c691e3
|
|
BLAKE2b-256 checksum How to use checksums |
5a3e57bd9b2cd777c9f34dc28995f70ef5c00dcc349245cf55f6a70bad79c260
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.10.21
|
