Migrating to the Hypnogram class#

YASA 0.7 introduced the Hypnogram class as the new standard for working with sleep hypnograms. Previous versions used plain integer or string NumPy arrays together with a set of standalone functions. This page shows the most common old patterns alongside their new equivalents, so you can update your code quickly.

Note

The old helper functions (hypno_upsample_to_data, hypno_str_to_int, etc.) still work in v0.7 but will be removed in v0.8. Migrating now will make your code cleaner and compatible with future releases.

Loading a hypnogram from a file#

Most pipelines start by loading an integer-encoded hypnogram from a plain-text or CSV file.

import numpy as np
import yasa

# Load as integer array (0=W, 1=N1, 2=N2, 3=N3, 4=REM)
hypno = np.loadtxt("hypnogram.txt").astype(int)

import numpy as np
import pandas as pd
import yasa

# From a .txt file
hypno = np.loadtxt("hypnogram.txt").astype(int)
hyp = yasa.Hypnogram.from_integers(hypno, freq="30s")

# From a .csv file
hypno = pd.read_csv("hypnogram.csv").squeeze().to_numpy()
hyp = yasa.Hypnogram.from_integers(hypno, freq="30s")

Loading a Profusion XML file#

# Returns (integer array, sampling frequency)
hypno, sf_hyp = yasa.load_profusion_hypno("hypnogram.xml")

# Returns a Hypnogram object with freq set automatically from the XML
hyp = yasa.Hypnogram.from_profusion("hypnogram.xml")

Upsampling to match EEG data#

Upsampling the hypnogram to the EEG sampling frequency was a required manual step before passing it to detection or analysis functions.

import mne
import yasa

raw = mne.io.read_raw_edf("recording.edf", preload=True)
sf = raw.info["sfreq"]
data = raw.get_data(units="uV")

# Upsample the 30-second hypnogram to the EEG sampling frequency
hypno_up = yasa.hypno_upsample_to_data(
    hypno=hypno, sf_hypno=1/30, data=data, sf_data=sf
)

# Then pass the upsampled array to detection functions
sp = yasa.spindles_detect(data, sf=sf, hypno=hypno_up, include=(2, 3))

import mne
import yasa

raw = mne.io.read_raw_edf("recording.edf", preload=True)
hyp = yasa.Hypnogram.from_integers(hypno, freq="30s")

# Pass the Hypnogram directly — upsampling is automatic
sp = yasa.spindles_detect(raw, hypno=hyp, include=["N2", "N3"])

If you still need the upsampled integer array (e.g. for a custom analysis):

hypno_up = hyp.upsample_to_data(raw)

Note

Detection functions now accept string stage labels in include (e.g. include=["N2", "N3"]) when a Hypnogram is passed. Integer labels (e.g. include=(2, 3)) still work when a plain array is passed.

Sleep statistics#

# Standalone function — takes an integer array and sf_hyp
stats = yasa.sleep_statistics(hypno, sf_hyp=1/30)

hyp = yasa.Hypnogram.from_integers(hypno, freq="30s")
stats = hyp.sleep_statistics()

Stage-transition matrix#

# Standalone function — integer input, integer labels in output
counts, probs = yasa.transition_matrix(hypno)

hyp = yasa.Hypnogram.from_integers(hypno, freq="30s")
# Method — string labels in output (e.g. "WAKE", "N2")
counts, probs = hyp.transition_matrix()

Finding sleep periods#

# Standalone function — takes sf_hypno as a float
periods = yasa.hypno_find_periods(
    hypno, sf_hypno=1/30, threshold="5min"
)

hyp = yasa.Hypnogram.from_integers(hypno, freq="30s")
periods = hyp.find_periods(threshold="5min")

Plotting the hypnogram#

# plot_hypnogram accepted a plain integer or string array
yasa.plot_hypnogram(hypno)

hyp = yasa.Hypnogram.from_integers(hypno, freq="30s")
hyp.plot_hypnogram()

Converting between strings and integers#

The old hypno_str_to_int and hypno_int_to_str utility functions are replaced by Hypnogram methods.

# Integer array to string array
hypno_str = yasa.hypno_int_to_str(hypno_int)

# String array to integer array
hypno_int = yasa.hypno_str_to_int(hypno_str)

# Integer array to Hypnogram (string storage)
hyp = yasa.Hypnogram.from_integers(hypno_int, freq="30s")
hypno_str = hyp.hypno.to_numpy()   # string NumPy array if needed

# String array to Hypnogram
hyp = yasa.Hypnogram(hypno_str, freq="30s")
hypno_int = hyp.as_int().to_numpy()  # integer NumPy array if needed

Automatic sleep staging#

SleepStaging.predict now returns a Hypnogram instead of a NumPy array.

sls = yasa.SleepStaging(raw, eeg_name="C3-A2")
hypno_pred = sls.predict()   # returned a string NumPy array
hypno_pred_int = yasa.hypno_str_to_int(hypno_pred)  # convert if needed

stats = yasa.sleep_statistics(hypno_pred_int, sf_hyp=1/30)

sls = yasa.SleepStaging(raw, eeg_name="C3-A2")
hyp = sls.predict()   # returns a Hypnogram

# Use methods directly on the object
stats = hyp.sleep_statistics()
hyp.plot_hypnogram()
hyp.plot_hypnodensity()  # stage probabilities are included automatically

# Recover arrays if needed for custom code
hypno_str = hyp.hypno.to_numpy()
hypno_int = hyp.as_int().to_numpy()

Reference table#

Old (v0.6)

New (v0.7+)

np.loadtxt(...).astype(int) passed directly

Hypnogram.from_integers

yasa.load_profusion_hypno(fname)

Hypnogram.from_profusion

yasa.hypno_upsample_to_data(hypno, sf_hypno, data, sf_data)

Hypnogram.upsample_to_data

yasa.sleep_statistics(hypno, sf_hyp)

Hypnogram.sleep_statistics

yasa.transition_matrix(hypno)

Hypnogram.transition_matrix

yasa.hypno_find_periods(hypno, sf_hypno, threshold)

Hypnogram.find_periods

yasa.plot_hypnogram(hypno_array)

hyp.plot_hypnogram() or yasa.plot_hypnogram(hyp)

yasa.hypno_int_to_str(hypno_int)

hyp.hypno.to_numpy() (after Hypnogram.from_integers)

yasa.hypno_str_to_int(hypno_str)

Hypnogram.as_int

SleepStaging.predict() returned a string array

SleepStaging.predict() returns a Hypnogram

include=(2, 3) in detection functions

include=["N2", "N3"] when passing a Hypnogram

Next steps#