Skip to content

README.md

Latest commit

 

History

History
69 lines (51 loc) · 2.51 KB

README.md

File metadata and controls

69 lines (51 loc) · 2.51 KB
Raw

BDSP Python — Decode the Night: retro arcade banner

BDSP Data Guide and Python Reader

Understand and load standardized sleep/PSG Zarr recordings from BDSP with the bdsp Python package. This repository contains the reader, data-format documentation, and examples. Start with your dataset's page on bdsp.io to request access and download its files.

Install

Use Python 3.11+ in a project environment:

pip install bdsp

Zarr support is installed automatically.

Open a Zarr recording

One recording has three matching artifacts: primary Zarr (signals and expert annotations), derivative Zarr (model annotations and time-varying features), and summary JSON (feature summaries). Pass those three paths to the reader:

from bdsp.bids_zarr import open_recording

with open_recording(
    primary="/data/primary.zarr",
    derivatives="/data/derivative.zarr",
    summary_json="/data/summary.json",
) as record:
    print(list(record.signals))
    signal = next(iter(record.signals.values()))
    window = signal.read(start=0, duration=30)
    summaries = record.features.summary.to_dataframe()

Replace the example paths with your files; .zarr paths refer to directories. window contains sample values, times, sampling rate, and physical units. Signals keep their native sampling rates, and only the requested window is loaded. Keep lazy reads inside the with block. Available channels, scorers, and features depend on the recording.

For an analysis that needs only primary signals and expert annotations, reader 0.4.0 adds a primary-only entry point:

from bdsp.bids_zarr import open_primary

with open_primary('/data/primary.zarr') as record:
    print(list(record.signals))

This validates the declared primary export without requiring or discovering derivatives or summary JSON. The ordinary open_recording() contract still requires the complete split export.

Further help

The getting started guide covers signals, annotations, features, installation, and development. The data-format guide explains the directory layout, units, and primary/derivative split; the reader reference covers the full Zarr API.

Licensed under Apache 2.0.