Skip to content

HYPNOGRAM_ROADMAP.md

Latest commit

 

History

History
44 lines (34 loc) · 2.62 KB

HYPNOGRAM_ROADMAP.md

File metadata and controls

44 lines (34 loc) · 2.62 KB

Hypnogram Class Roadmap

Goal: make yasa.Hypnogram the industry-standard Python object for handling sleep hypnograms.

Implemented (v0.7.0)

Core class

  • Hypnogram(values, n_stages, freq, start, tz, scorer, proba) — string-based, categorical storage
  • from_integers(values, mapping, ...) — migrate from legacy integer arrays
  • from_profusion(fname, ...) — load Compumedics Profusion XML (NSRR format)
  • start / end properties — optional absolute timestamp anchoring; a plain timezone-naive string is sufficient for EDF alignment
  • upsample_to_data(data, sf, meas_date_is_local=True) — align to EEG data by sample count or absolute timestamps (MNE meas_date); default True treats meas_date as a local absolute timestamp per the EDF+ standard (which defines starttime as local time at the patient's location; MNE mislabels it as UTC); set False only for files that genuinely store UTC

Analysis

  • sleep_statistics() — full AASM summary (TIB, TST, SE, SOL, WASO, stage durations, ...)
  • transition_matrix() — stage transition counts and probabilities
  • find_periods(threshold) — detect consecutive runs of a stage
  • consolidate_stages(new_n_stages) — merge to 2/3/4-stage hypnogram
  • evaluate(obs_hyp) — epoch-by-epoch agreement metrics (kappa, MCC, F1, ...)

Python container protocol

  • __len__ — len(hyp) returns number of epochs
  • __eq__ — hyp1 == hyp2 returns a boolean NumPy array (element-wise)
  • __getitem__ — hyp[0], hyp[-1], hyp[10:50] return a new Hypnogram
  • crop(start, end) — slice by epoch index (inclusive) or absolute timestamp time

Visualization & export

  • plot_hypnogram() — standard hypnogram figure
  • plot_hypnodensity() — per-epoch stage probabilities as a stacked area chart (requires proba); supports 2/3/4/5-stage hypnograms and datetime x-axis when start is set
  • as_int() — integer-encoded pandas.Series
  • as_events() — BIDS-compatible events DataFrame (onset, duration, stage)
  • upsample(new_freq) — change epoch resolution
  • to_json(fname) / from_json(fname) — save and load to disk, preserving all metadata
  • to_dict() / from_dict(d) — JSON-serializable in-memory representation (same format as to_json)
  • get_mask(*stages) — return a boolean NumPy array for one or more stages (e.g., hyp.get_mask("N2", "N3")).

Planned (future releases)

Multi-scorer support

  • HypnogramSet — new container class for multiple scorers of the same night (alignment, pairwise agreement, consensus scoring). See HYPNOGRAM_MULTIPLE_SCORERS.md for the full design plan.