yasa.Hypnogram.pad#

Hypnogram.pad(before=None, after=None, fill_value='UNS')[source]#

Extend the hypnogram by padding epochs before and/or after.

Parameters:
beforeint, str, or pandas.Timestamp, optional

Number of epochs to prepend (int ≥ 0), or a timestamp for the new start (must be strictly before start). Requires start to be set when a timestamp is given.

afterint, str, or pandas.Timestamp, optional

Number of epochs to append (int ≥ 0), or a timestamp for the new end (exclusive; must be strictly after end). Requires start to be set when a timestamp is given.

fill_valuestr or tuple of str, optional

Stage label(s) for the added epochs. Default is "UNS" (Unscored).

  • A single string applies the same fill to both ends. Use "edge" to repeat the first epoch for before and the last epoch for after, analogous to numpy.pad with mode="edge". Any valid stage label (see labels) is also accepted.

  • A 2-tuple (fill_before, fill_after) sets different values for each end, e.g. ("UNS", "WAKE") pads the start with Unscored epochs and the end with Wake epochs. Each element follows the same rules as the scalar form.

Returns:
hypHypnogram

A new Hypnogram with the requested padding. proba is not propagated.

Warns:
UserWarning

When a timestamp-based duration is not a perfect multiple of freq, the padding is floored to the nearest complete epoch count.

Examples

Epoch-based padding with the default fill value (UNS):

>>> from yasa import Hypnogram
>>> hyp = Hypnogram(["N2", "N2", "REM"], freq="30s")
>>> hyp.pad(before=2, after=1).hypno.to_list()
['UNS', 'UNS', 'N2', 'N2', 'REM', 'UNS']

Edge padding (repeat first/last epoch):

>>> hyp.pad(before=2, after=1, fill_value="edge").hypno.to_list()
['N2', 'N2', 'N2', 'N2', 'REM', 'REM']

Different fill values for each end — pad start with UNS and end with WAKE:

>>> hyp.pad(before=1, after=2, fill_value=("UNS", "WAKE")).hypno.to_list()
['UNS', 'N2', 'N2', 'REM', 'WAKE', 'WAKE']

Timestamp-based padding — extend to a fixed recording window. Here the hypnogram starts at 22:01:00 and ends at 22:02:30, so two 30-s UNS epochs are prepended to align it to 22:00:00, and one is appended to reach 22:03:00:

>>> hyp_ts = Hypnogram(["N2", "N2", "REM"], freq="30s", start="2023-01-01 22:01:00")
>>> padded = hyp_ts.pad(before="2023-01-01 22:00:00", after="2023-01-01 22:03:00")
>>> padded.n_epochs
6
>>> padded.start
Timestamp('2023-01-01 22:00:00')
>>> padded.end
Timestamp('2023-01-01 22:03:00')
>>> padded.hypno.to_list()
['UNS', 'UNS', 'N2', 'N2', 'REM', 'UNS']
On this page