Add utilities for generating sleep windows from predicted onsets and offsets

[clane9]

This adds utilities for generating and filtering sleep windows from model predicted onset and offset events.

• generate_sleep_windows: generates all sleep windows longer than a given duration from all pairs of onset and offsets
• filter_non_sleep_windows: removes windows that contain non-sleep periods, based on an instantaneous (per timestep) sleep score.
• nms_windows: apply non-maximum suppression to de-duplicate overlapping windows.

[Asanto32]

I assume this is specifically for the onset/offset (I thought our preferred nomenclature was onset/wakeup?) sleep detection algorithm from kaggle-14 that Reinder is working on implementing? I guess that model outputs some scores that we need to filter? I will let Reinder decide if he wants to merge it into his branch as I am not 100% aware of the state of that implementation

[Asanto32]

Also it has a big red X so I don't need to look at it , right? (or that's what I pretend anyway :P)

[codecov]

Codecov Report

All modified and coverable lines are covered by tests ✅

Please upload report for BASE (feature/kaggle-14@87dafe9). Learn more about missing BASE report.

Additional details and impacted files

@@                 Coverage Diff                  @@
##             feature/kaggle-14     #112   +/-   ##
====================================================
  Coverage                     ?   99.35%           
====================================================
  Files                        ?        8           
  Lines                        ?      463           
  Branches                     ?        0           
====================================================
  Hits                         ?      460           
  Misses                       ?        3           
  Partials                     ?        0           

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

[clane9]

Ok fixed most checks except for a ruff complaint in a different file.

The offsets term I took from here, but yeah I can change that if wakeups is preferred, np.

For context, the model predicts unpaired onset and offset events, but what we need are sleep windows. So basically here I am adding utilities to generate candidate windows from the onset/offset events, and then filter out invalid ones.

One question is whether there is a smarter way to generate candidate windows than just taking all possible onset/offset pairs.

[ReinderVosDeWael]

Since we only have event scores, what would we use for instantaneous sleep scores in the filter function?

[clane9]

I was thinking we could use the current heuristic GGIR-style sleep scores. Just need something to be able to eliminate windows that clearly contain non-sleep.

This is necessary because for example if you have two sleep periods in a night [(onset_1, offset_1), (onset_2, offset_2)], the generate_sleep_windows function will also produce (onset_1, offset_2), which we don't want.

[ReinderVosDeWael]

Gotcha - I'm thinking it'll probably be easier for me to merge this straight into my branch and run into issues when using it, rather than trying to get out ahead of any potential issues in the PR. So I'll merge it and let you know when something comes up :)

[Asanto32]

I was thinking we could use the current heuristic GGIR-style sleep scores. Just need something to be able to eliminate windows that clearly contain non-sleep.

This is necessary because for example if you have two sleep periods in a night [(onset_1, offset_1), (onset_2, offset_2)], the generate_sleep_windows function will also produce (onset_1, offset_2), which we don't want.

Just one thing to keep in mind, is that in certain cases those two sleep windows should be merged into one. I believe the clinical suggestion is if the awake time is less than one hour to consider it one sleep period. Currently this is how it is set, but it is a variable that can be set in

wristpy/src/wristpy/processing/analytics.py

Line 145 in bb3eb39

sleep_idx_array_filled = self._fill_false_blocks(

But also note that we keep the 'sib_periods', that represent sustained inactivity bouts aka actual sleeping time, separate from the onset/wakeup times.