Skip to content

Commit

Permalink
Updated doc, notebook, and hypno example
Browse files Browse the repository at this point in the history
  • Loading branch information
@raphaelvallat
raphaelvallat committed Aug 14, 2019
1 parent df828b5 commit 71a905c
Show file tree
Hide file tree
Showing 11 changed files with 913 additions and 22,211 deletions.
6 changes: 5 additions & 1 deletion README.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -75,7 +75,7 @@ In order to use YASA, you need:
- Some basic knowledge of Python and especially the `NumPy <https://docs.scipy.org/doc/numpy/user/quickstart.html>`_, `Pandas <https://pandas.pydata.org/pandas-docs/stable/getting_started/10min.html>`_ and `MNE <https://martinos.org/mne/stable/index.html>`_ libraries.
- A Python editor: YASA works best with `Jupyter Lab <https://jupyterlab.readthedocs.io/en/stable/index.html>`_, a web-based interactive user interface.
- Some sleep EEG data, either as a NumPy array, or as a raw MNE object (for instance, using the `mne.io.read_raw_edf <https://mne-tools.github.io/stable/generated/mne.io.read_raw_edf.html>`_ function for EDF file). The units of the data MUST be uV.
- Optionally, a sleep staging vector (= hypnogram) to run the detections on specific sleep stages. YASA requires that the data and hypnogram have the same sampling frequency.
- Optionally, a sleep staging vector (= hypnogram) to run the detections on specific sleep stages. To facilitate masking and selection operations, YASA requires that the data and hypnogram have the same sampling frequency and shape. If not, YASA provide some `convenient functions <https://htmlpreview.github.io/?https://raw.githubusercontent.com/raphaelvallat/yasa/master/html/hypno.html>`_ to load and upsample hypnogram data to the desired shape.

Examples
~~~~~~~~
Expand Down Expand Up @@ -108,6 +108,10 @@ The examples Jupyter notebooks are really what make YASA great! In addition to s

9. `notebooks/09_REMs_detection.ipynb <notebooks/09_REMs_detection.ipynb>`_: REMs detection.

**Bandpower**

10. `notebooks/10_bandpower.ipynb <notebooks/10_bandpower.ipynb>`_: bandpower per channel and per sleep stage.

Typical uses
------------

Expand Down
97 changes: 4 additions & 93 deletions html/hypno.html
View file
Original file line number Diff line number Diff line change
Expand Up @@ -95,7 +95,7 @@ <h1 class="title">Module <code>yasa.hypno</code></h1>
import pandas as pd

__all__ = [&#39;hypno_str_to_int&#39;, &#39;hypno_int_to_str&#39;, &#39;hypno_upsample_to_sf&#39;,
&#39;hypno_fit_to_data&#39;, &#39;hypno_upsample_to_data&#39;]
&#39;hypno_upsample_to_data&#39;]


#############################################################################
Expand Down Expand Up @@ -186,8 +186,9 @@ <h1 class="title">Module <code>yasa.hypno</code></h1>
def hypno_fit_to_data(hypno, data, sf=None):
&#34;&#34;&#34;Crop or pad the hypnogram to fit the length of data.

Hypnogram and data MUST have the SAME sampling frequency. If not,
please use the ``hypno_upsample_to_sf`` function before.
Hypnogram and data MUST have the SAME sampling frequency.

This is an internal function.

Parameters
----------
Expand Down Expand Up @@ -245,9 +246,6 @@ <h1 class="title">Module <code>yasa.hypno</code></h1>
resulting hypnogram to corresponding EEG data, such that the hypnogram
and EEG data have the exact same number of samples.

This function is a shortcut to
``hypno = hypno_fit_to_data(hypno_upsample_to_sf(...), ...)``.

Parameters
----------
hypno : array_like
Expand Down Expand Up @@ -284,87 +282,6 @@ <h1 class="title">Module <code>yasa.hypno</code></h1>
<section>
<h2 class="section-title" id="header-functions">Functions</h2>
<dl>
<dt id="yasa.hypno.hypno_fit_to_data"><code class="name flex">
<span>def <span class="ident">hypno_fit_to_data</span></span>(<span>hypno, data, sf=None)</span>
</code></dt>
<dd>
<section class="desc"><p>Crop or pad the hypnogram to fit the length of data.</p>
<p>Hypnogram and data MUST have the SAME sampling frequency. If not,
please use the <code>&lt;a title="yasa.hypno.hypno_upsample_to_sf" href="#yasa.hypno.hypno_upsample_to_sf"&gt;</code>hypno_upsample_to_sf()<code>&lt;/a&gt;</code> function before.</p>
<h2 id="parameters">Parameters</h2>
<dl>
<dt><strong><code>hypno</code></strong> :&ensp;<code>array_like</code></dt>
<dd>The sleep staging (hypnogram) 1D array.</dd>
<dt><strong><code>data</code></strong> :&ensp;<code>np.array_like</code> or <code>mne.io.Raw</code></dt>
<dd>1D or 2D EEG data. Can also be a MNE Raw object, in which case data and
sf will be automatically extracted.</dd>
<dt><strong><code>sf</code></strong> :&ensp;<code>float</code>, optional</dt>
<dd>The sampling frequency of data AND the hypnogram.</dd>
</dl>
<h2 id="returns">Returns</h2>
<dl>
<dt><strong><code>hypno</code></strong> :&ensp;<code>array_like</code></dt>
<dd>Hypnogram, with the same number of samples as data.</dd>
</dl></section>
<details class="source">
<summary>Source code</summary>
<pre><code class="python">def hypno_fit_to_data(hypno, data, sf=None):
&#34;&#34;&#34;Crop or pad the hypnogram to fit the length of data.

Hypnogram and data MUST have the SAME sampling frequency. If not,
please use the ``hypno_upsample_to_sf`` function before.

Parameters
----------
hypno : array_like
The sleep staging (hypnogram) 1D array.
data : np.array_like or mne.io.Raw
1D or 2D EEG data. Can also be a MNE Raw object, in which case data and
sf will be automatically extracted.
sf : float, optional
The sampling frequency of data AND the hypnogram.

Returns
-------
hypno : array_like
Hypnogram, with the same number of samples as data.
&#34;&#34;&#34;
# Check if data is an MNE raw object
if isinstance(data, mne.io.BaseRaw):
sf = data.info[&#39;sfreq&#39;]
data = data.times # 1D array and does not require to preload data
data = np.asarray(data)
hypno = np.asarray(hypno)
assert hypno.ndim == 1, &#39;Hypno must be 1D.&#39;
npts_hyp = hypno.size
npts_data = max(data.shape) # Support for 2D data
if npts_hyp &lt; npts_data:
# Hypnogram is shorter than data
npts_diff = npts_data - npts_hyp
if sf is not None:
dur_diff = npts_diff / sf
warnings.warn(&#39;Hypnogram is SHORTER then data by %.2f seconds. &#39;
&#39;Padding hypnogram (with last value) to match &#39;
&#39;data.size.&#39; % dur_diff)
else:
warnings.warn(&#39;Hypnogram is SHORTER then data by %i samples. &#39;
&#39;Padding hypnogram (with last value) to match &#39;
&#39;data.size.&#39; % npts_diff)
hypno = np.pad(hypno, (0, npts_diff), mode=&#39;edge&#39;)
elif npts_hyp &gt; npts_data:
# Hypnogram is longer than data
npts_diff = npts_hyp - npts_data
if sf is not None:
dur_diff = npts_diff / sf
warnings.warn(&#39;Hypnogram is LONGER then data by %.2f seconds. &#39;
&#39;Cropping hypnogram to match data.size.&#39; % dur_diff)
else:
warnings.warn(&#39;Hypnogram is LONGER then data by %i samples. &#39;
&#39;Cropping hypnogram to match data.size.&#39; % npts_diff)
hypno = hypno[0:npts_data]
return hypno</code></pre>
</details>
</dd>
<dt id="yasa.hypno.hypno_int_to_str"><code class="name flex">
<span>def <span class="ident">hypno_int_to_str</span></span>(<span>hypno, mapping_dict={0: 'W', 1: 'N1', 2: 'N2', 3: 'N3', 4: 'R', -1: 'Art'})</span>
</code></dt>
Expand Down Expand Up @@ -467,8 +384,6 @@ <h2 id="returns">Returns</h2>
<section class="desc"><p>Upsample an 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.</p>
<p>This function is a shortcut to
<code>hypno = hypno_fit_to_data(hypno_upsample_to_sf(...), ...)</code>.</p>
<h2 id="parameters">Parameters</h2>
<dl>
<dt><strong><code>hypno</code></strong> :&ensp;<code>array_like</code></dt>
Expand Down Expand Up @@ -497,9 +412,6 @@ <h2 id="returns">Returns</h2>
resulting hypnogram to corresponding EEG data, such that the hypnogram
and EEG data have the exact same number of samples.

This function is a shortcut to
``hypno = hypno_fit_to_data(hypno_upsample_to_sf(...), ...)``.

Parameters
----------
hypno : array_like
Expand Down Expand Up @@ -598,7 +510,6 @@ <h1>Index</h1>
</li>
<li><h3><a href="#header-functions">Functions</a></h3>
<ul class="">
<li><code><a title="yasa.hypno.hypno_fit_to_data" href="#yasa.hypno.hypno_fit_to_data">hypno_fit_to_data</a></code></li>
<li><code><a title="yasa.hypno.hypno_int_to_str" href="#yasa.hypno.hypno_int_to_str">hypno_int_to_str</a></code></li>
<li><code><a title="yasa.hypno.hypno_str_to_int" href="#yasa.hypno.hypno_str_to_int">hypno_str_to_int</a></code></li>
<li><code><a title="yasa.hypno.hypno_upsample_to_data" href="#yasa.hypno.hypno_upsample_to_data">hypno_upsample_to_data</a></code></li>
Expand Down
54 changes: 27 additions & 27 deletions html/main.html
View file
Original file line number Diff line number Diff line change
Expand Up @@ -548,9 +548,9 @@ <h1 class="title">Module <code>yasa.main</code></h1>
detection will only be applied to the value defined in
``include`` (default = N1 + N2 + N3 sleep). ``hypno`` MUST be a 1D
array of integers with the same size as data and where -1 = Artefact,
0 = Wake, 1 = N1, 2 = N2, 3 = N3, 4 = REM. If you need help loading
your hypnogram vector, please read the Visbrain documentation at
http://visbrain.org/sleep.
0 = Wake, 1 = N1, 2 = N2, 3 = N3, 4 = REM. YASA provides several
convenient functions to load and upsample hypnogram data:
https://htmlpreview.github.io/?https://raw.githubusercontent.com/raphaelvallat/yasa/master/html/hypno.html
include : tuple, list or int
Values in ``hypno`` that will be included in the mask. The default is
(1, 2, 3), meaning that the detection is applied on N1, N2 and N3
Expand Down Expand Up @@ -965,9 +965,9 @@ <h1 class="title">Module <code>yasa.main</code></h1>
detection will only be applied to the value defined in
``include`` (default = N2 + N3 sleep). ``hypno`` MUST be a 1D array of
integers with the same size as data and where -1 = Artefact, 0 = Wake,
1 = N1, 2 = N2, 3 = N3, 4 = REM. If you need help loading your
hypnogram vector, please read the Visbrain documentation at
http://visbrain.org/sleep.
1 = N1, 2 = N2, 3 = N3, 4 = REM. YASA provides several
convenient functions to load and upsample hypnogram data:
https://htmlpreview.github.io/?https://raw.githubusercontent.com/raphaelvallat/yasa/master/html/hypno.html
include : tuple, list or int
Values in ``hypno`` that will be included in the mask. The default is
(2, 3), meaning that the detection is applied only on N2 and N3 sleep.
Expand Down Expand Up @@ -1339,9 +1339,9 @@ <h1 class="title">Module <code>yasa.main</code></h1>
detection will only be applied to the value defined in
``include`` (default = REM sleep). ``hypno`` MUST be a 1D array of
integers with the same size as data and where -1 = Artefact, 0 = Wake,
1 = N1, 2 = N2, 3 = N3, 4 = REM. If you need help loading your
hypnogram vector, please read the Visbrain documentation at
http://visbrain.org/sleep.
1 = N1, 2 = N2, 3 = N3, 4 = REM. YASA provides several
convenient functions to load and upsample hypnogram data:
https://htmlpreview.github.io/?https://raw.githubusercontent.com/raphaelvallat/yasa/master/html/hypno.html
include : tuple, list or int
Values in ``hypno`` that will be included in the mask. The default is
(4), meaning that the detection is applied only on REM sleep.
Expand Down Expand Up @@ -1972,9 +1972,9 @@ <h2 id="parameters">Parameters</h2>
detection will only be applied to the value defined in
<code>include</code> (default = REM sleep). <code>hypno</code> MUST be a 1D array of
integers with the same size as data and where -1 = Artefact, 0 = Wake,
1 = N1, 2 = N2, 3 = N3, 4 = REM. If you need help loading your
hypnogram vector, please read the Visbrain documentation at
<a href="http://visbrain.org/sleep.">http://visbrain.org/sleep.</a></dd>
1 = N1, 2 = N2, 3 = N3, 4 = REM. YASA provides several
convenient functions to load and upsample hypnogram data:
<a href="https://htmlpreview.github.io/?https://raw.githubusercontent.com/raphaelvallat/yasa/master/html/hypno.html">https://htmlpreview.github.io/?https://raw.githubusercontent.com/raphaelvallat/yasa/master/html/hypno.html</a></dd>
<dt><strong><code>include</code></strong> :&ensp;<code>tuple</code>, <code>list</code> or <code>int</code></dt>
<dd>Values in <code>hypno</code> that will be included in the mask. The default is
(4), meaning that the detection is applied only on REM sleep.
Expand Down Expand Up @@ -2057,9 +2057,9 @@ <h2 id="references">References</h2>
detection will only be applied to the value defined in
``include`` (default = REM sleep). ``hypno`` MUST be a 1D array of
integers with the same size as data and where -1 = Artefact, 0 = Wake,
1 = N1, 2 = N2, 3 = N3, 4 = REM. If you need help loading your
hypnogram vector, please read the Visbrain documentation at
http://visbrain.org/sleep.
1 = N1, 2 = N2, 3 = N3, 4 = REM. YASA provides several
convenient functions to load and upsample hypnogram data:
https://htmlpreview.github.io/?https://raw.githubusercontent.com/raphaelvallat/yasa/master/html/hypno.html
include : tuple, list or int
Values in ``hypno`` that will be included in the mask. The default is
(4), meaning that the detection is applied only on REM sleep.
Expand Down Expand Up @@ -2302,9 +2302,9 @@ <h2 id="parameters">Parameters</h2>
detection will only be applied to the value defined in
<code>include</code> (default = N1 + N2 + N3 sleep). <code>hypno</code> MUST be a 1D
array of integers with the same size as data and where -1 = Artefact,
0 = Wake, 1 = N1, 2 = N2, 3 = N3, 4 = REM. If you need help loading
your hypnogram vector, please read the Visbrain documentation at
<a href="http://visbrain.org/sleep.">http://visbrain.org/sleep.</a></dd>
0 = Wake, 1 = N1, 2 = N2, 3 = N3, 4 = REM. YASA provides several
convenient functions to load and upsample hypnogram data:
<a href="https://htmlpreview.github.io/?https://raw.githubusercontent.com/raphaelvallat/yasa/master/html/hypno.html">https://htmlpreview.github.io/?https://raw.githubusercontent.com/raphaelvallat/yasa/master/html/hypno.html</a></dd>
<dt><strong><code>include</code></strong> :&ensp;<code>tuple</code>, <code>list</code> or <code>int</code></dt>
<dd>Values in <code>hypno</code> that will be included in the mask. The default is
(1, 2, 3), meaning that the detection is applied on N1, N2 and N3
Expand Down Expand Up @@ -2380,9 +2380,9 @@ <h2 id="notes">Notes</h2>
detection will only be applied to the value defined in
``include`` (default = N1 + N2 + N3 sleep). ``hypno`` MUST be a 1D
array of integers with the same size as data and where -1 = Artefact,
0 = Wake, 1 = N1, 2 = N2, 3 = N3, 4 = REM. If you need help loading
your hypnogram vector, please read the Visbrain documentation at
http://visbrain.org/sleep.
0 = Wake, 1 = N1, 2 = N2, 3 = N3, 4 = REM. YASA provides several
convenient functions to load and upsample hypnogram data:
https://htmlpreview.github.io/?https://raw.githubusercontent.com/raphaelvallat/yasa/master/html/hypno.html
include : tuple, list or int
Values in ``hypno`` that will be included in the mask. The default is
(1, 2, 3), meaning that the detection is applied on N1, N2 and N3
Expand Down Expand Up @@ -2836,9 +2836,9 @@ <h2 id="parameters">Parameters</h2>
detection will only be applied to the value defined in
<code>include</code> (default = N2 + N3 sleep). <code>hypno</code> MUST be a 1D array of
integers with the same size as data and where -1 = Artefact, 0 = Wake,
1 = N1, 2 = N2, 3 = N3, 4 = REM. If you need help loading your
hypnogram vector, please read the Visbrain documentation at
<a href="http://visbrain.org/sleep.">http://visbrain.org/sleep.</a></dd>
1 = N1, 2 = N2, 3 = N3, 4 = REM. YASA provides several
convenient functions to load and upsample hypnogram data:
<a href="https://htmlpreview.github.io/?https://raw.githubusercontent.com/raphaelvallat/yasa/master/html/hypno.html">https://htmlpreview.github.io/?https://raw.githubusercontent.com/raphaelvallat/yasa/master/html/hypno.html</a></dd>
<dt><strong><code>include</code></strong> :&ensp;<code>tuple</code>, <code>list</code> or <code>int</code></dt>
<dd>Values in <code>hypno</code> that will be included in the mask. The default is
(2, 3), meaning that the detection is applied only on N2 and N3 sleep.
Expand Down Expand Up @@ -2917,9 +2917,9 @@ <h2 id="notes">Notes</h2>
detection will only be applied to the value defined in
``include`` (default = N2 + N3 sleep). ``hypno`` MUST be a 1D array of
integers with the same size as data and where -1 = Artefact, 0 = Wake,
1 = N1, 2 = N2, 3 = N3, 4 = REM. If you need help loading your
hypnogram vector, please read the Visbrain documentation at
http://visbrain.org/sleep.
1 = N1, 2 = N2, 3 = N3, 4 = REM. YASA provides several
convenient functions to load and upsample hypnogram data:
https://htmlpreview.github.io/?https://raw.githubusercontent.com/raphaelvallat/yasa/master/html/hypno.html
include : tuple, list or int
Values in ``hypno`` that will be included in the mask. The default is
(2, 3), meaning that the detection is applied only on N2 and N3 sleep.
Expand Down
Loading

0 comments on commit 71a905c

Please sign in to comment.