Metadata-Version: 2.4
Name: sleep-kit-psg
Version: 2.1.1
Summary: Prepare PSG recordings and hypnograms for reproducible sleep-staging research
Author-email: Li Jinyang <jinyang03702@163.com>
License-Expression: Apache-2.0
Project-URL: Homepage, https://github.com/lijinyang439-arch/PSGPrep
Project-URL: Repository, https://github.com/lijinyang439-arch/PSGPrep
Project-URL: Documentation, https://github.com/lijinyang439-arch/PSGPrep#readme
Project-URL: Issues, https://github.com/lijinyang439-arch/PSGPrep/issues
Project-URL: PyPI, https://pypi.org/project/sleep-kit-psg/
Project-URL: Tutorial, https://github.com/lijinyang439-arch/PSGPrep/blob/main/docs/tutorial_sleep_edf.md
Project-URL: Validation, https://github.com/lijinyang439-arch/PSGPrep/blob/main/VALIDATION_REPORT.md
Keywords: polysomnography,PSG,EDF,sleep staging,hypnogram,EEG,MNE,NSRR,dataset preparation,reproducibility
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Scientific/Engineering :: Medical Science Apps.
Requires-Python: <3.15,>=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
License-File: NOTICE
Requires-Dist: numpy>=1.23
Requires-Dist: scipy>=1.9
Requires-Dist: mne>=1.5
Requires-Dist: PyYAML>=6.0
Provides-Extra: hdf5
Requires-Dist: h5py>=3.8; extra == "hdf5"
Provides-Extra: dev
Requires-Dist: build>=1.2; extra == "dev"
Requires-Dist: check-wheel-contents>=0.6; extra == "dev"
Requires-Dist: h5py>=3.8; extra == "dev"
Requires-Dist: mypy>=1.11; extra == "dev"
Requires-Dist: ruff>=0.9; extra == "dev"
Requires-Dist: twine>=6.0; extra == "dev"
Requires-Dist: tomli>=2.0; python_version < "3.11" and extra == "dev"
Requires-Dist: types-PyYAML>=6.0; extra == "dev"
Dynamic: license-file

# SleepKit PSG

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

```bash
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:

```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.

[中文说明](README.zh-CN.md)

## Prepare a dataset

Inspect pairing before reading signal samples:

```bash
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:

```bash
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:

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

## Find the task you need

| Task | Guide |
|---|---|
| Install and run the first dataset | [Getting started](docs/getting_started.md) |
| Use every CLI command and exit code | [CLI reference](docs/cli.md) |
| Call the typed Python interface | [Python API](docs/python_api.md) |
| Choose or write a dataset profile | [Dataset profiles](docs/dataset_profiles.md) |
| Process one public Sleep-EDF record | [Public-data tutorial](docs/tutorial_sleep_edf.md) |
| Load sequences for a downstream model | [Downstream loading](docs/downstream_loading.md) |
| Read array shapes and provenance fields | [Output format](docs/output_format.md) |
| Interpret tests and real-data evidence | [Validation](docs/validation.md) |
| Migrate an older integration | [Migration](MIGRATION.md) |
| Diagnose common failures | [FAQ](docs/faq.md) |

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

```bash
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](CONTRIBUTING.md) for the full gate.

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