yasa.Hypnogram.upsample_to_data#

Hypnogram.upsample_to_data(data, sf=None, meas_date_is_local=True, verbose=False)[source]#

Upsample a hypnogram to a given sampling frequency and fit the resulting hypnogram to corresponding EEG data, such that the hypnogram and EEG data have the exact same number of samples.

When self.start is set and data is a mne.io.BaseRaw with a valid meas_date, alignment uses absolute timestamps rather than sample count. See the Working with Hypnograms tutorial for a full description of all alignment scenarios and when to use start / tz.

Parameters:
dataarray_like or mne.io.BaseRaw

1D or 2D EEG data. Can also be a mne.io.BaseRaw, in which case data and sf will be automatically extracted.

sffloat

The sampling frequency of data, in Hz (e.g. 100 Hz, 256 Hz, …). Can be omitted if data is a mne.io.BaseRaw.

meas_date_is_localbool

If True (default), meas_date is treated as a local absolute timestamp, consistent with the EDF+ standard, which explicitly defines starttime as local time at the patient’s location. Set to False only if your EDF files genuinely store UTC in meas_date, in which case pass tz when constructing the Hypnogram so the two timestamps share a common reference frame.

verbosebool or str

Verbose level. Default (False) will only print warning and error messages. The logging levels are ‘debug’, ‘info’, ‘warning’, ‘error’, and ‘critical’. For most users the choice is between ‘info’ (or verbose=True) and warning (verbose=False).

Changed in version 0.8.0: The default is now False, as documented. Previously, the default was True.

Returns:
hypnonumpy.ndarray

The hypnogram values as a 1D integer array, upsampled to sf Hz and cropped/padded to max(data.shape) samples. For compatibility with most YASA functions, integer values are returned rather than a yasa.Hypnogram object.

Raises:
ValueError

Only when meas_date_is_local=False: raised if self.start is timezone-naive while raw.meas_date is timezone-aware (UTC). Fix by passing tz at construction: Hypnogram(..., tz='Europe/Paris'). This error cannot occur with the default meas_date_is_local=True.

Notes

If the hypnogram is shorter or longer than the data, it is padded or cropped and a warning is logged via the yasa logger (not a Python UserWarning). This message can be silenced by passing verbose='error'.

Examples

>>> import numpy as np
>>> from yasa import Hypnogram
>>> hyp = Hypnogram(["W", "W", "N1", "N2", "N2", "REM"], freq="30s")
>>> data = np.zeros((1, 18000))
>>> hypno = hyp.upsample_to_data(data, sf=100)
>>> hypno.shape
(18000,)
>>> np.unique(hypno)
array([0, 1, 2, 4], dtype=int16)
On this page