SleepKit PSG

SleepKit PSG turns PSG recordings and scored hypnograms into checked NumPy arrays for sleep-staging research.

python -m pip install sleep-kit-psg
sleepkit-psg demo --output sleepkit-demo

The demo is generated locally, uses no network, and finishes with this JSON:

{
  "output": "sleepkit-demo",
  "processed_records": 1,
  "total_epochs": 20,
  "total_sequences": 1,
  "valid": true
}

The demo validates software installation and output structure, not clinical correctness. Real-data evidence is limited to one-record smoke tests for 18 profiles; dcsm, dod, mass13, and wsc remain migrated-unverified. SleepKit PSG is not a medical device.

中文说明

Prepare a dataset

Inspect pairing before reading signal samples:

sleepkit-psg scan \
  --profile shhs1 \
  --input-root /path/to/shhs1/edfs \
  --annotation-root /path/to/shhs1/annotations \
  --details

Then preprocess selected channels and validate every written artifact:

sleepkit-psg preprocess \
  --profile shhs1 \
  --input-root /path/to/shhs1/edfs \
  --annotation-root /path/to/shhs1/annotations \
  --output-root outputs/shhs1 \
  --channels C4 E1 \
  --target-sfreq 100 \
  --workers 4

sleepkit-psg validate --output-root outputs/shhs1

Input paths accept str and pathlib.Path in Python. The CLI reports progress on standard error, returns JSON on standard output, and uses exit codes 0 for success, 1 for completed work with failures, and 2 for invalid invocation or setup.

What the package does

• Pairs recordings and annotations with profile-defined regular expressions and keeps unmatched files visible.
• Resolves EEG, EOG, EMG, and reference channels in the requested order.
• Reads EDF/BDF/REC through MNE, plus documented NPZ, MATLAB, HDF5, XML, text, table, and EDF-annotation contracts.
• Applies explicit filters, resampling, epoch alignment, normalization, stage mapping, and sequence generation.
• Writes record and sequence NPZ files atomically with QC, provenance, completion markers, and structured failures.
• Rejects input/output overlap, unrelated non-empty output directories, and incompatible resume contracts.

HDF5 readers are optional:

python -m pip install 'sleep-kit-psg[hdf5]'

Find the task you need

The distribution name is sleep-kit-psg, the Python import is sleep_kit, and the command is sleepkit-psg. These are the only names to use in new integrations.

Development

git clone https://github.com/lijinyang439-arch/PSGPrep.git sleepkit-psg
cd sleepkit-psg
python -m pip install -e '.[dev]'
python scripts/release_check.py

Scientific behavior changes need a synthetic regression test and a precise evidence boundary. Do not submit recordings, annotations, clinical data, participant identifiers, credentials, salts, or private paths. See CONTRIBUTING.md for the full gate.

Use CITATION.cff when citing the software and cite each source dataset separately. SleepKit PSG is licensed under Apache-2.0; that license does not cover input datasets.