Yasa

New Contributors
* sjg2203 made their first contribution in https://github.com/raphaelvallat/yasa/pull/154
* nabilalibou made their first contribution in https://github.com/raphaelvallat/yasa/pull/160
* larsoner made their first contribution in https://github.com/raphaelvallat/yasa/pull/171

**Full Changelog**: https://github.com/raphaelvallat/yasa/compare/v0.6.4...v0.6.5

Minor release with one bugfix and several other improvements:

- Fix MNE plot_topomap deprecation (119)
- Pass `relative_prominence` parameters in :py:func:`yasa.rem_detect` (151)
- Rename `yasa.simulate_hypno` function to `yasa.simulate_hypnogram`
- Add `Hypnogram` class in public API. `Hypnogram` will become the default method for manipulating hypnograms in YASA starting from [v0.7](https://raphaelvallat.com/yasa/build/html/changelog.html#v0-7-dev).
- Requires mne>=1.3, numpy>=1.18.1, numba>=0.57.1

This is a minor release with one bugfix and one new function. Big shoutout to remrama for his huge help on this new version!

**Bugfix**

Solved a bug in the spindles detection which resulted in no spindle being detected on some systems. See 107 and 115.

**New functions**

Added the `yasa.simulate_hypno` function to generate a simulated hypnogram, primarily for testing purposes and tutorials. The hypnogram is simulated as a Markov sequence based on sleep stage transition probabilities. Transition probabilities can be user-defined or will default to those published in Metzner et al., 2021, *Commun Biol* (see [Figure 5b](https://www.nature.com/articles/s42003-021-02912-6#Fig5)). See 109 and 110

**Improvements**

* Added the ``ax`` keyword-argument to `yasa.plot_hypnogram` and removed ``figsize``. Now select figure aesthetics (e.g., size, dpi) by opening a `matplotlib.axes.Axes` instance and passing to ``ax``. See PR 108
* `yasa.plot_hypnogram` now draws the hypnogram with`matplotlib.pyplot.stairs` instead of `matplotlib.pyplot.step`. See issue 106 and PR 108

New Contributors
* matiasandina made their first contribution in https://github.com/raphaelvallat/yasa/pull/75

This release fixes a CRITICAL BUG with the spindles detection. Specifically, the [yasa.spindles_detect()](https://raphaelvallat.com/yasa/build/html/generated/yasa.spindles_detect.html#yasa.spindles_detect) could return different results depending on the sampling rate of the data. For example, downsampling the data from 256 Hz to 128 Hz may have significantly reduced the number of detected spindles. As explained in [issue 54](https://github.com/raphaelvallat/yasa/issues/54), this bug was caused by a floating-point error in [numpy.convolve()](https://numpy.org/doc/stable/reference/generated/numpy.convolve.html#numpy.convolve) when calculating the soft spindle threshold. Tests seem to indicate that only certain sampling frequencies were impacted, such as 200 Hz, 256 Hz or 400 Hz. Other sampling frequencies such as 100 Hz and 500 Hz were seemingly not affected by this bug.


**We recommend all users to upgrade to this new version ASAP and check any results obtained with the [yasa.spindles_detect()](https://raphaelvallat.com/yasa/build/html/generated/yasa.spindles_detect.html#yasa.spindles_detect) function!**

This is a MAJOR release with several API-breaking changes, new functions, bugfixes and a new section in the documentation.

Slow oscillations—sigma coupling

IMPORTANT — The default behavior of coupling=True in [yasa.sw_detect()](https://raphaelvallat.com/yasa/build/html/generated/yasa.sw_detect.html#yasa.sw_detect) has been changed: YASA now uses a ± 1 second window around the negative peak of the slow-waves (2 sec total) to calculate the coupling, instead of a ± 2 sec window. Overall, this tends to increase the ndPAC values because of the higher temporal specificity. To keep a 4-sec window, use `coupling_params['time'] = 2`.

We’ve enabled the statistical thresholding in the ndPAC calculation. Practically, this means that events with a weak/unreliable coupling are assigned an ndPAC value of zero. Statistical thresholding can be disabled with `coupling_params['p'] = None`.

Because of these changes, **the coupling values are therefore not comparable with previous versions of YASA**. Please make sure to re-run your analyses with the new default parameters.

Events detection

- The [yasa.sw_detect()](https://raphaelvallat.com/yasa/build/html/generated/yasa.sw_detect.html#yasa.sw_detect) function now uses **more conservative amplitude thresholds**: the max PTP amplitude has been reduced from 500 to 350 uV, the max negative amplitude has been reduced from 300 to 200 uV, and the max positive amplitude has been reduced from 200 to 150 uV.
- Added [yasa.SWResults.find_cooccurring_spindles()](https://raphaelvallat.com/yasa/build/html/generated/yasa.SWResults.html#yasa.SWResults.find_cooccurring_spindles) to detect whether each slow-wave co-occurr with a sleep spindle.
- Added the as_dataframe parameter in [yasa.SWResults.get_sync_events()](https://raphaelvallat.com/yasa/build/html/generated/yasa.SWResults.html#yasa.SWResults.get_sync_events) and [yasa.SpindlesResults.get_sync_events()](https://raphaelvallat.com/yasa/build/html/generated/yasa.SpindlesResults.html#yasa.SpindlesResults.get_sync_events). If set to False, YASA will return the peak-locked data as a list (n_channels) of numpy arrays (n_events, n_times). This facilitates any analyses that requires access to event-locked data (e.g. time-frequency plot, or comodulogram).
- Added the mask parameter in [yasa.SWResults.summary()](https://raphaelvallat.com/yasa/build/html/generated/yasa.SWResults.html#yasa.SWResults.summary), [yasa.SWResults.get_sync_events()](https://raphaelvallat.com/yasa/build/html/generated/yasa.SWResults.html#yasa.SWResults.get_sync_events), and [yasa.SWResults.plot_average()](https://raphaelvallat.com/yasa/build/html/generated/yasa.SWResults.html#yasa.SWResults.plot_average). This allows users to only include selected events in the summary or plots (e.g. the slow-waves with the largest peak-to-peak amplitude, or strongest coupling).
- Added the mask parameter in [yasa.SpindlesResults.summary()](https://raphaelvallat.com/yasa/build/html/generated/yasa.SpindlesResults.html#yasa.SpindlesResults.summary), [yasa.SpindlesResults.get_sync_events()](https://raphaelvallat.com/yasa/build/html/generated/yasa.SpindlesResults.html#yasa.SpindlesResults.get_sync_events), and [yasa.SpindlesResults.plot_average()](https://raphaelvallat.com/yasa/build/html/generated/yasa.SpindlesResults.html#yasa.SpindlesResults.plot_average). This allows users to only include selected events in the summary or plots (e.g. the spindles with the largest amplitude).
- Added the mask parameter in [yasa.REMResults.summary()](https://raphaelvallat.com/yasa/build/html/generated/yasa.REMResults.html#yasa.REMResults.summary), [yasa.REMResults.get_sync_events()](https://raphaelvallat.com/yasa/build/html/generated/yasa.REMResults.html#yasa.REMResults.get_sync_events), and [yasa.REMResults.plot_average()](https://raphaelvallat.com/yasa/build/html/generated/yasa.REMResults.html#yasa.REMResults.plot_average).

Plotting

- Added the [yasa.plot_hypnogram()](https://raphaelvallat.com/yasa/build/html/generated/yasa.plot_hypnogram.html#yasa.plot_hypnogram) function to plot an hypnogram.

Documentation

- Added a [Quickstart](https://raphaelvallat.com/yasa/build/html/quickstart.html#quickstart) section to illustrate the main functions of YASA. Make sure to check it out!

Others

- [yasa.irasa()](https://raphaelvallat.com/yasa/build/html/generated/yasa.irasa.html#yasa.irasa) now informs about the maximum resampled fitting range, and raises a warning if parameters/frequencies are ill-specified. See https://github.com/raphaelvallat/yasa/pull/42 and associated paper: https://doi.org/10.1101/2021.10.15.464483
- Added a verbose parameter to [yasa.hypno_upsample_to_data()](https://raphaelvallat.com/yasa/build/html/generated/yasa.hypno_upsample_to_data.html#yasa.hypno_upsample_to_data) and [yasa.irasa()](https://raphaelvallat.com/yasa/build/html/generated/yasa.irasa.html#yasa.irasa).
- Remove Travis CI
- Remove CI testing for Python 3.6