.. DO NOT EDIT.
.. THIS FILE WAS AUTOMATICALLY GENERATED BY SPHINX-GALLERY.
.. TO MAKE CHANGES, EDIT THE SOURCE PYTHON FILE:
.. "examples/example_01_getting_started.py"
.. LINE NUMBERS ARE GIVEN BELOW.

.. only:: html

    .. note::
        :class: sphx-glr-download-link-note

        :ref:`Go to the end <sphx_glr_download_examples_example_01_getting_started.py>`
        to download the full example code.

.. rst-class:: sphx-glr-example-title

.. _sphx_glr_examples_example_01_getting_started.py:


Getting started tutorial
========================

Here is a quick overview of :py:mod:`physio`

.. GENERATED FROM PYTHON SOURCE LINES 7-13

.. code-block:: Python


    import numpy as np
    import matplotlib.pyplot as plt
    from pathlib import Path
    import physio








.. GENERATED FROM PYTHON SOURCE LINES 14-33

Reading data
------------

:py:mod:`physio` aims to process physiological signals in NumPy format.
Therefore, the first step is to load your data into a NumPy array.
:py:mod:`physio` provides utility functions for reading certain formats, such as:

   * micromed
   * brainvision

For example, cardiac activity recorded by a BrainVision system with the channel name "ECG" can be read using
:py:func:`~physio.read_one_channel` by specifying: 

   * the path to the file ("/path/to/the/file.vhdr")
   * the format ("brainvision")
   * the channel name ("ECG").

For this tutorial, we will use internal files already stored in NumPy format for demonstration purposes. 
Let's load them and plot a sample.

.. GENERATED FROM PYTHON SOURCE LINES 34-60

.. code-block:: Python



    raw_resp = np.load('resp1_airflow.npy') # load respi
    raw_ecg = np.load('ecg1.npy') # load ecg
    srate = 1000. # our example signals have been recorded at 1000 Hz

    times = np.arange(raw_resp.size) / srate # build time vector

    linewidth = 0.8
    fig, axs = plt.subplots(nrows=2, sharex=True)
    ax = axs[0]
    ax.plot(times, raw_resp, lw = linewidth)
    ax.set_title('Raw respiratory airflow signal')
    ax.set_ylabel('Amplitude (AU)')
    ax.set_ylim(-1750, -1500)

    ax = axs[1]
    ax.plot(times, raw_ecg, lw = linewidth)
    ax.set_title('Raw ECG (electrocardiogram)')
    ax.set_ylabel('Amplitude (V)')
    ax.set_ylim(0.012, 0.015)

    ax.set_xlabel('Time (s)')
    ax.set_xlim(185, 225)





.. image-sg:: /examples/images/sphx_glr_example_01_getting_started_001.png
   :alt: Raw respiratory airflow signal, Raw ECG (electrocardiogram)
   :srcset: /examples/images/sphx_glr_example_01_getting_started_001.png
   :class: sphx-glr-single-img


.. rst-class:: sphx-glr-script-out

 .. code-block:: none


    (185.0, 225.0)



.. GENERATED FROM PYTHON SOURCE LINES 61-80

Analyze respiration
-------------------

:py:func:`~physio.compute_respiration` is a high-level wrapper function that simplifies respiratory signal analysis.
To use this function, you must provide:

   * `raw_resp` : the raw respiratory signal as a NumPy array.
   * `srate` : the sampling rate of the respiratory signal
   * `parameter_preset` : a string specifying the type of respiratory data, which determines the set of parameters used for processing. Can be one of: `human_airflow`, `human_co2`, `human_belt`,  `rat_plethysmo`, or `rat_etisens_belt`.

When called, :py:func:`~physio.compute_respiration` performs the following:

   * Preprocesses the respiratory signal (returns a NumPy array: `resp`)
   * Computes cycle-by-cycle features (returns a pd.DataFrame: `resp_cycles`)

**Warning:** The orientation of the `raw_resp` trace is important (multiply it by -1 for reversing it if necessary). 
Inspiration must point downward for `human_airflow` or `human_co2`, 
because downward deflections are interpreted by :py:func:`~physio.compute_respiration` as inspiration. 
For `rat_plethysmo` or `rat_etisens_belt`, the inspiration–expiration transition must point upward.

.. GENERATED FROM PYTHON SOURCE LINES 81-98

.. code-block:: Python





    resp, resp_cycles = physio.compute_respiration(raw_resp, srate, parameter_preset = 'human_airflow') # set 'human_airflow' as preset because example resp is an airflow from humans

    linewidth = 0.9
    fig, ax = plt.subplots()
    ax.plot(times, raw_resp, lw = linewidth, label = 'raw resp signal')
    ax.plot(times, resp, lw = linewidth, label = 'preprocessed resp signal')
    ax.set_ylabel('Amplitude (AU)')
    ax.set_ylim(-1750, -1500)
    ax.set_xlim(185, 225)
    ax.set_xlabel('Time (s)')
    ax.set_title('From raw to preprocessed respiratory airflow signal')
    ax.legend(loc = 'upper right')




.. image-sg:: /examples/images/sphx_glr_example_01_getting_started_002.png
   :alt: From raw to preprocessed respiratory airflow signal
   :srcset: /examples/images/sphx_glr_example_01_getting_started_002.png
   :class: sphx-glr-single-img


.. rst-class:: sphx-glr-script-out

 .. code-block:: none


    <matplotlib.legend.Legend object at 0x70afab407690>



.. GENERATED FROM PYTHON SOURCE LINES 99-105

Respiration cycles and features
-------------------------------

`resp_cycles` is a pd.DataFrame where each row corresponds to a respiratory cycle.
Columns contain cycle-specific features such as duration, amplitude, volume, etc ... 
See :ref:`sphx_glr_examples_example_02_respiration.py` for a complete description of the columns.

.. GENERATED FROM PYTHON SOURCE LINES 106-127

.. code-block:: Python


    print(resp_cycles.shape)
    print(resp_cycles.columns)

    columns = ['cycle_duration', 'inspi_volume', 'expi_volume', 'total_amplitude'] # selection of some columns / metrics
    colors = ['tab:blue','darkorange','green','red'] # set colors
    units = ['s','AU','AU','AU'] # set units

    fig, axs = plt.subplots(nrows=2, ncols=2, figsize=(8, 6))
    fig.suptitle(f'Distribution of some metrics from N = {resp_cycles.shape[0]} detected cycles')
    for ax, col, color, unit in zip(axs.flatten(), columns, colors, units):
        ax.hist(resp_cycles[col], bins=30, color=color, edgecolor = 'k') 
        ax.set_title(col)
        ax.set_xlabel(f'{col} ({unit})')
        ax.set_ylabel("Count")

    fig.tight_layout()

    resp_cycles





.. image-sg:: /examples/images/sphx_glr_example_01_getting_started_003.png
   :alt: Distribution of some metrics from N = 30 detected cycles, cycle_duration, inspi_volume, expi_volume, total_amplitude
   :srcset: /examples/images/sphx_glr_example_01_getting_started_003.png
   :class: sphx-glr-single-img


.. rst-class:: sphx-glr-script-out

 .. code-block:: none

    (30, 21)
    Index(['inspi_index', 'expi_index', 'next_inspi_index', 'inspi_time',
           'expi_time', 'next_inspi_time', 'cycle_duration', 'inspi_duration',
           'expi_duration', 'cycle_freq', 'cycle_ratio', 'inspi_volume',
           'expi_volume', 'total_amplitude', 'inspi_amplitude', 'expi_amplitude',
           'inspi_peak_index', 'expi_peak_index', 'inspi_peak_time',
           'expi_peak_time', 'total_volume'],
          dtype='str')


.. raw:: html

    <div class="output_subarea output_html rendered_html output_result">
    <div>
    <style scoped>
        .dataframe tbody tr th:only-of-type {
            vertical-align: middle;
        }

        .dataframe tbody tr th {
            vertical-align: top;
        }

        .dataframe thead th {
            text-align: right;
        }
    </style>
    <table border="1" class="dataframe">
      <thead>
        <tr style="text-align: right;">
          <th></th>
          <th>inspi_index</th>
          <th>expi_index</th>
          <th>next_inspi_index</th>
          <th>inspi_time</th>
          <th>expi_time</th>
          <th>next_inspi_time</th>
          <th>cycle_duration</th>
          <th>inspi_duration</th>
          <th>expi_duration</th>
          <th>cycle_freq</th>
          <th>cycle_ratio</th>
          <th>inspi_volume</th>
          <th>expi_volume</th>
          <th>total_amplitude</th>
          <th>inspi_amplitude</th>
          <th>expi_amplitude</th>
          <th>inspi_peak_index</th>
          <th>expi_peak_index</th>
          <th>inspi_peak_time</th>
          <th>expi_peak_time</th>
          <th>total_volume</th>
        </tr>
      </thead>
      <tbody>
        <tr>
          <th>0</th>
          <td>963</td>
          <td>3849</td>
          <td>8755</td>
          <td>0.963</td>
          <td>3.849</td>
          <td>8.755</td>
          <td>7.792</td>
          <td>2.886</td>
          <td>4.906</td>
          <td>0.128337</td>
          <td>0.370380</td>
          <td>163.426788</td>
          <td>127.997642</td>
          <td>195.890794</td>
          <td>93.101770</td>
          <td>102.789023</td>
          <td>2993</td>
          <td>4969</td>
          <td>2.993</td>
          <td>4.969</td>
          <td>291.424431</td>
        </tr>
        <tr>
          <th>1</th>
          <td>8755</td>
          <td>12470</td>
          <td>16629</td>
          <td>8.755</td>
          <td>12.470</td>
          <td>16.629</td>
          <td>7.874</td>
          <td>3.715</td>
          <td>4.159</td>
          <td>0.127000</td>
          <td>0.471806</td>
          <td>127.912620</td>
          <td>120.766841</td>
          <td>204.261166</td>
          <td>111.836892</td>
          <td>92.424274</td>
          <td>9640</td>
          <td>13479</td>
          <td>9.640</td>
          <td>13.479</td>
          <td>248.679461</td>
        </tr>
        <tr>
          <th>2</th>
          <td>16629</td>
          <td>20085</td>
          <td>25589</td>
          <td>16.629</td>
          <td>20.085</td>
          <td>25.589</td>
          <td>8.960</td>
          <td>3.456</td>
          <td>5.504</td>
          <td>0.111607</td>
          <td>0.385714</td>
          <td>117.322121</td>
          <td>108.021751</td>
          <td>178.600929</td>
          <td>64.548937</td>
          <td>114.051992</td>
          <td>18014</td>
          <td>20995</td>
          <td>18.014</td>
          <td>20.995</td>
          <td>225.343872</td>
        </tr>
        <tr>
          <th>3</th>
          <td>25589</td>
          <td>28826</td>
          <td>35467</td>
          <td>25.589</td>
          <td>28.826</td>
          <td>35.467</td>
          <td>9.878</td>
          <td>3.237</td>
          <td>6.641</td>
          <td>0.101235</td>
          <td>0.327698</td>
          <td>82.220884</td>
          <td>98.005772</td>
          <td>125.979297</td>
          <td>46.007447</td>
          <td>79.971850</td>
          <td>26607</td>
          <td>30576</td>
          <td>26.607</td>
          <td>30.576</td>
          <td>180.226656</td>
        </tr>
        <tr>
          <th>4</th>
          <td>35467</td>
          <td>39250</td>
          <td>45631</td>
          <td>35.467</td>
          <td>39.250</td>
          <td>45.631</td>
          <td>10.164</td>
          <td>3.783</td>
          <td>6.381</td>
          <td>0.098386</td>
          <td>0.372196</td>
          <td>101.588255</td>
          <td>117.184560</td>
          <td>127.910587</td>
          <td>47.063516</td>
          <td>80.847071</td>
          <td>37283</td>
          <td>41144</td>
          <td>37.283</td>
          <td>41.144</td>
          <td>218.772816</td>
        </tr>
        <tr>
          <th>5</th>
          <td>45631</td>
          <td>48992</td>
          <td>55914</td>
          <td>45.631</td>
          <td>48.992</td>
          <td>55.914</td>
          <td>10.283</td>
          <td>3.361</td>
          <td>6.922</td>
          <td>0.097248</td>
          <td>0.326850</td>
          <td>82.862181</td>
          <td>102.441040</td>
          <td>132.522182</td>
          <td>44.166802</td>
          <td>88.355380</td>
          <td>46392</td>
          <td>50698</td>
          <td>46.392</td>
          <td>50.698</td>
          <td>185.303221</td>
        </tr>
        <tr>
          <th>6</th>
          <td>55914</td>
          <td>59772</td>
          <td>67325</td>
          <td>55.914</td>
          <td>59.772</td>
          <td>67.325</td>
          <td>11.411</td>
          <td>3.858</td>
          <td>7.553</td>
          <td>0.087635</td>
          <td>0.338095</td>
          <td>120.667807</td>
          <td>102.270537</td>
          <td>138.805077</td>
          <td>58.638983</td>
          <td>80.166094</td>
          <td>57002</td>
          <td>61809</td>
          <td>57.002</td>
          <td>61.809</td>
          <td>222.938344</td>
        </tr>
        <tr>
          <th>7</th>
          <td>67325</td>
          <td>70801</td>
          <td>78023</td>
          <td>67.325</td>
          <td>70.801</td>
          <td>78.023</td>
          <td>10.698</td>
          <td>3.476</td>
          <td>7.222</td>
          <td>0.093475</td>
          <td>0.324921</td>
          <td>79.043735</td>
          <td>94.684808</td>
          <td>123.666977</td>
          <td>45.443175</td>
          <td>78.223802</td>
          <td>68674</td>
          <td>72750</td>
          <td>68.674</td>
          <td>72.750</td>
          <td>173.728543</td>
        </tr>
        <tr>
          <th>8</th>
          <td>78023</td>
          <td>81420</td>
          <td>86030</td>
          <td>78.023</td>
          <td>81.420</td>
          <td>86.030</td>
          <td>8.007</td>
          <td>3.397</td>
          <td>4.610</td>
          <td>0.124891</td>
          <td>0.424254</td>
          <td>106.575911</td>
          <td>134.553459</td>
          <td>183.326805</td>
          <td>61.358012</td>
          <td>121.968793</td>
          <td>78917</td>
          <td>82834</td>
          <td>78.917</td>
          <td>82.834</td>
          <td>241.129370</td>
        </tr>
        <tr>
          <th>9</th>
          <td>86030</td>
          <td>89213</td>
          <td>94623</td>
          <td>86.030</td>
          <td>89.213</td>
          <td>94.623</td>
          <td>8.593</td>
          <td>3.183</td>
          <td>5.410</td>
          <td>0.116374</td>
          <td>0.370418</td>
          <td>72.404075</td>
          <td>89.801492</td>
          <td>153.248258</td>
          <td>44.234641</td>
          <td>109.013617</td>
          <td>86990</td>
          <td>90996</td>
          <td>86.990</td>
          <td>90.996</td>
          <td>162.205566</td>
        </tr>
        <tr>
          <th>10</th>
          <td>94623</td>
          <td>97972</td>
          <td>104423</td>
          <td>94.623</td>
          <td>97.972</td>
          <td>104.423</td>
          <td>9.800</td>
          <td>3.349</td>
          <td>6.451</td>
          <td>0.102041</td>
          <td>0.341735</td>
          <td>636.536901</td>
          <td>447.267064</td>
          <td>485.434574</td>
          <td>308.901992</td>
          <td>176.532582</td>
          <td>96491</td>
          <td>100891</td>
          <td>96.491</td>
          <td>100.891</td>
          <td>1083.803965</td>
        </tr>
        <tr>
          <th>11</th>
          <td>104423</td>
          <td>108683</td>
          <td>114252</td>
          <td>104.423</td>
          <td>108.683</td>
          <td>114.252</td>
          <td>9.829</td>
          <td>4.260</td>
          <td>5.569</td>
          <td>0.101740</td>
          <td>0.433411</td>
          <td>111.393347</td>
          <td>125.823770</td>
          <td>173.558532</td>
          <td>61.310891</td>
          <td>112.247642</td>
          <td>105392</td>
          <td>110518</td>
          <td>105.392</td>
          <td>110.518</td>
          <td>237.217117</td>
        </tr>
        <tr>
          <th>12</th>
          <td>114252</td>
          <td>117877</td>
          <td>124700</td>
          <td>114.252</td>
          <td>117.877</td>
          <td>124.700</td>
          <td>10.448</td>
          <td>3.625</td>
          <td>6.823</td>
          <td>0.095712</td>
          <td>0.346956</td>
          <td>85.802485</td>
          <td>130.310932</td>
          <td>176.487994</td>
          <td>42.373720</td>
          <td>134.114274</td>
          <td>115469</td>
          <td>119319</td>
          <td>115.469</td>
          <td>119.319</td>
          <td>216.113417</td>
        </tr>
        <tr>
          <th>13</th>
          <td>124700</td>
          <td>127879</td>
          <td>134461</td>
          <td>124.700</td>
          <td>127.879</td>
          <td>134.461</td>
          <td>9.761</td>
          <td>3.179</td>
          <td>6.582</td>
          <td>0.102449</td>
          <td>0.325684</td>
          <td>99.368718</td>
          <td>127.697288</td>
          <td>180.930699</td>
          <td>59.422501</td>
          <td>121.508199</td>
          <td>125935</td>
          <td>129999</td>
          <td>125.935</td>
          <td>129.999</td>
          <td>227.066006</td>
        </tr>
        <tr>
          <th>14</th>
          <td>134461</td>
          <td>138178</td>
          <td>145780</td>
          <td>134.461</td>
          <td>138.178</td>
          <td>145.780</td>
          <td>11.319</td>
          <td>3.717</td>
          <td>7.602</td>
          <td>0.088347</td>
          <td>0.328386</td>
          <td>91.107038</td>
          <td>105.601792</td>
          <td>120.530583</td>
          <td>46.826341</td>
          <td>73.704242</td>
          <td>135851</td>
          <td>140396</td>
          <td>135.851</td>
          <td>140.396</td>
          <td>196.708830</td>
        </tr>
        <tr>
          <th>15</th>
          <td>145780</td>
          <td>149124</td>
          <td>156359</td>
          <td>145.780</td>
          <td>149.124</td>
          <td>156.359</td>
          <td>10.579</td>
          <td>3.344</td>
          <td>7.235</td>
          <td>0.094527</td>
          <td>0.316098</td>
          <td>54.976681</td>
          <td>90.049016</td>
          <td>107.621249</td>
          <td>29.892126</td>
          <td>77.729124</td>
          <td>146325</td>
          <td>151674</td>
          <td>146.325</td>
          <td>151.674</td>
          <td>145.025697</td>
        </tr>
        <tr>
          <th>16</th>
          <td>156359</td>
          <td>159809</td>
          <td>165930</td>
          <td>156.359</td>
          <td>159.809</td>
          <td>165.930</td>
          <td>9.571</td>
          <td>3.450</td>
          <td>6.121</td>
          <td>0.104482</td>
          <td>0.360464</td>
          <td>81.043434</td>
          <td>92.559758</td>
          <td>111.249025</td>
          <td>46.559908</td>
          <td>64.689117</td>
          <td>157165</td>
          <td>161764</td>
          <td>157.165</td>
          <td>161.764</td>
          <td>173.603192</td>
        </tr>
        <tr>
          <th>17</th>
          <td>165930</td>
          <td>169247</td>
          <td>175415</td>
          <td>165.930</td>
          <td>169.247</td>
          <td>175.415</td>
          <td>9.485</td>
          <td>3.317</td>
          <td>6.168</td>
          <td>0.105430</td>
          <td>0.349710</td>
          <td>87.795188</td>
          <td>92.158942</td>
          <td>116.860425</td>
          <td>48.317537</td>
          <td>68.542888</td>
          <td>166838</td>
          <td>171542</td>
          <td>166.838</td>
          <td>171.542</td>
          <td>179.954129</td>
        </tr>
        <tr>
          <th>18</th>
          <td>175415</td>
          <td>178225</td>
          <td>184867</td>
          <td>175.415</td>
          <td>178.225</td>
          <td>184.867</td>
          <td>9.452</td>
          <td>2.810</td>
          <td>6.642</td>
          <td>0.105798</td>
          <td>0.297292</td>
          <td>56.670496</td>
          <td>73.249906</td>
          <td>98.581205</td>
          <td>33.366724</td>
          <td>65.214481</td>
          <td>175990</td>
          <td>180364</td>
          <td>175.990</td>
          <td>180.364</td>
          <td>129.920402</td>
        </tr>
        <tr>
          <th>19</th>
          <td>184867</td>
          <td>188712</td>
          <td>195179</td>
          <td>184.867</td>
          <td>188.712</td>
          <td>195.179</td>
          <td>10.312</td>
          <td>3.845</td>
          <td>6.467</td>
          <td>0.096974</td>
          <td>0.372867</td>
          <td>68.358008</td>
          <td>104.624509</td>
          <td>131.036618</td>
          <td>40.379954</td>
          <td>90.656664</td>
          <td>185838</td>
          <td>190757</td>
          <td>185.838</td>
          <td>190.757</td>
          <td>172.982517</td>
        </tr>
        <tr>
          <th>20</th>
          <td>195179</td>
          <td>199483</td>
          <td>205152</td>
          <td>195.179</td>
          <td>199.483</td>
          <td>205.152</td>
          <td>9.973</td>
          <td>4.304</td>
          <td>5.669</td>
          <td>0.100271</td>
          <td>0.431565</td>
          <td>81.222469</td>
          <td>105.898526</td>
          <td>108.186857</td>
          <td>51.809933</td>
          <td>56.376923</td>
          <td>196397</td>
          <td>201509</td>
          <td>196.397</td>
          <td>201.509</td>
          <td>187.120995</td>
        </tr>
        <tr>
          <th>21</th>
          <td>205152</td>
          <td>209074</td>
          <td>214162</td>
          <td>205.152</td>
          <td>209.074</td>
          <td>214.162</td>
          <td>9.010</td>
          <td>3.922</td>
          <td>5.088</td>
          <td>0.110988</td>
          <td>0.435294</td>
          <td>106.968152</td>
          <td>111.748564</td>
          <td>110.797636</td>
          <td>47.691581</td>
          <td>63.106055</td>
          <td>206634</td>
          <td>210793</td>
          <td>206.634</td>
          <td>210.793</td>
          <td>218.716716</td>
        </tr>
        <tr>
          <th>22</th>
          <td>214162</td>
          <td>217778</td>
          <td>223497</td>
          <td>214.162</td>
          <td>217.778</td>
          <td>223.497</td>
          <td>9.335</td>
          <td>3.616</td>
          <td>5.719</td>
          <td>0.107124</td>
          <td>0.387359</td>
          <td>96.273488</td>
          <td>110.557056</td>
          <td>131.741321</td>
          <td>55.426862</td>
          <td>76.314458</td>
          <td>215470</td>
          <td>220553</td>
          <td>215.470</td>
          <td>220.553</td>
          <td>206.830544</td>
        </tr>
        <tr>
          <th>23</th>
          <td>223497</td>
          <td>227737</td>
          <td>233353</td>
          <td>223.497</td>
          <td>227.737</td>
          <td>233.353</td>
          <td>9.856</td>
          <td>4.240</td>
          <td>5.616</td>
          <td>0.101461</td>
          <td>0.430195</td>
          <td>101.875446</td>
          <td>120.943199</td>
          <td>124.177712</td>
          <td>57.961557</td>
          <td>66.216154</td>
          <td>224499</td>
          <td>229680</td>
          <td>224.499</td>
          <td>229.680</td>
          <td>222.818645</td>
        </tr>
        <tr>
          <th>24</th>
          <td>233353</td>
          <td>237747</td>
          <td>242949</td>
          <td>233.353</td>
          <td>237.747</td>
          <td>242.949</td>
          <td>9.596</td>
          <td>4.394</td>
          <td>5.202</td>
          <td>0.104210</td>
          <td>0.457899</td>
          <td>111.570671</td>
          <td>142.748661</td>
          <td>151.433624</td>
          <td>55.897519</td>
          <td>95.536105</td>
          <td>234310</td>
          <td>239786</td>
          <td>234.310</td>
          <td>239.786</td>
          <td>254.319332</td>
        </tr>
        <tr>
          <th>25</th>
          <td>242949</td>
          <td>247667</td>
          <td>253240</td>
          <td>242.949</td>
          <td>247.667</td>
          <td>253.240</td>
          <td>10.291</td>
          <td>4.718</td>
          <td>5.573</td>
          <td>0.097172</td>
          <td>0.458459</td>
          <td>147.507051</td>
          <td>171.319857</td>
          <td>165.743584</td>
          <td>72.974277</td>
          <td>92.769307</td>
          <td>243912</td>
          <td>249696</td>
          <td>243.912</td>
          <td>249.696</td>
          <td>318.826908</td>
        </tr>
        <tr>
          <th>26</th>
          <td>253240</td>
          <td>257182</td>
          <td>263116</td>
          <td>253.240</td>
          <td>257.182</td>
          <td>263.116</td>
          <td>9.876</td>
          <td>3.942</td>
          <td>5.934</td>
          <td>0.101256</td>
          <td>0.399149</td>
          <td>125.281328</td>
          <td>132.788731</td>
          <td>138.701424</td>
          <td>61.828053</td>
          <td>76.873371</td>
          <td>254007</td>
          <td>259468</td>
          <td>254.007</td>
          <td>259.468</td>
          <td>258.070059</td>
        </tr>
        <tr>
          <th>27</th>
          <td>263116</td>
          <td>266749</td>
          <td>273102</td>
          <td>263.116</td>
          <td>266.749</td>
          <td>273.102</td>
          <td>9.986</td>
          <td>3.633</td>
          <td>6.353</td>
          <td>0.100140</td>
          <td>0.363809</td>
          <td>92.320485</td>
          <td>112.500656</td>
          <td>142.799229</td>
          <td>61.377405</td>
          <td>81.421824</td>
          <td>263675</td>
          <td>269279</td>
          <td>263.675</td>
          <td>269.279</td>
          <td>204.821141</td>
        </tr>
        <tr>
          <th>28</th>
          <td>273102</td>
          <td>277759</td>
          <td>284946</td>
          <td>273.102</td>
          <td>277.759</td>
          <td>284.946</td>
          <td>11.844</td>
          <td>4.657</td>
          <td>7.187</td>
          <td>0.084431</td>
          <td>0.393195</td>
          <td>106.627863</td>
          <td>137.735911</td>
          <td>122.342380</td>
          <td>45.115735</td>
          <td>77.226645</td>
          <td>274201</td>
          <td>279953</td>
          <td>274.201</td>
          <td>279.953</td>
          <td>244.363774</td>
        </tr>
        <tr>
          <th>29</th>
          <td>284946</td>
          <td>288731</td>
          <td>295014</td>
          <td>284.946</td>
          <td>288.731</td>
          <td>295.014</td>
          <td>10.068</td>
          <td>3.785</td>
          <td>6.283</td>
          <td>0.099325</td>
          <td>0.375944</td>
          <td>81.769137</td>
          <td>107.776736</td>
          <td>118.126812</td>
          <td>41.632810</td>
          <td>76.494002</td>
          <td>285985</td>
          <td>291162</td>
          <td>285.985</td>
          <td>291.162</td>
          <td>189.545873</td>
        </tr>
      </tbody>
    </table>
    </div>
    </div>
    <br />
    <br />

.. GENERATED FROM PYTHON SOURCE LINES 128-129

All these metrics highly depend on the quality of detection of the start points of inspiration and expiration, which can be verified by visual inspection: 

.. GENERATED FROM PYTHON SOURCE LINES 129-146

.. code-block:: Python


    inspi_ind = resp_cycles['inspi_index'].values # get index of inspiration start points
    expi_ind = resp_cycles['expi_index'].values # get index of expiration start points

    fig, ax = plt.subplots()
    ax.plot(times, resp)
    ax.scatter(times[inspi_ind], resp[inspi_ind], color='green', label = 'inspiration start')
    ax.scatter(times[expi_ind], resp[expi_ind], color='red', label = 'expiration start')
    ax.set_xlim(185, 225)
    ax.set_xlabel('Time (s)')
    ax.set_ylabel('Amplitude (AU)')
    ax.set_ylim(-1750, -1500)
    ax.set_title('Visual inspection of resp cycle detection')
    ax.legend(loc = 'upper right')






.. image-sg:: /examples/images/sphx_glr_example_01_getting_started_004.png
   :alt: Visual inspection of resp cycle detection
   :srcset: /examples/images/sphx_glr_example_01_getting_started_004.png
   :class: sphx-glr-single-img


.. rst-class:: sphx-glr-script-out

 .. code-block:: none


    <matplotlib.legend.Legend object at 0x70afaaf71790>



.. GENERATED FROM PYTHON SOURCE LINES 147-166

Analyze ECG
-----------

:py:func:`~physio.compute_ecg` is a high-level wrapper function that simplifies ECG signal analysis.
To use this function, you must provide:

   * `raw_ecg` : the raw ECG signal as a NumPy array
   * `srate` : the sampling rate of the ECG signal
   * `parameter_preset` : a string specifying the type of ECG data, which determines the set of parameters used for processing. Can be one of: `human_ecg` or `rat_ecg`.

When called, :py:func:`~physio.compute_ecg` performs the following:

   * Preprocesses the ECG signal (returns a NumPy array: `ecg`). By default, `ecg` is normalized.
   * Detects R peaks (returns a pd.DataFrame: `ecg_peaks`)

**Warning:** The orientation of the `raw_ecg` trace is important (multiply it by -1 for reversing it if necessary). 
R peaks must point upward for the highest probability of detection by :py:func:`~physio.compute_ecg`. 
Sometimes the R and S peaks of the QRS complex are equivalent, so orientation does not matter, 
because either the R or S peak will be detected and used to mark heartbeats.

.. GENERATED FROM PYTHON SOURCE LINES 167-194

.. code-block:: Python



    ecg, ecg_peaks = physio.compute_ecg(raw_ecg, srate, parameter_preset = 'human_ecg') # set 'human_ecg' as preset because example ecg is from human

    r_peak_ind = ecg_peaks['peak_index'].values # get index of R peaks

    linewidth = 0.8
    fig, axs = plt.subplots(nrows=2, sharex=True)
    ax = axs[0]
    ax.plot(times, raw_ecg, lw = linewidth)
    ax.scatter(times[r_peak_ind], raw_ecg[r_peak_ind], color="#C3CB22", label = 'R peak')
    ax.set_ylim(0.012, 0.015)
    ax.set_ylabel('Amplitude (V)')
    ax.set_title('R peak detection, plotted on raw ECG')
    ax.legend(loc = 'upper right')

    ax = axs[1]
    ax.plot(times, ecg, lw = linewidth)
    ax.scatter(times[r_peak_ind], ecg[r_peak_ind], color='#A8AE27', label = 'R peak')
    ax.set_xlim(185, 225)
    ax.set_ylim(-35, 50)
    ax.set_ylabel('Amplitude (AU)')
    ax.set_title('R peak detection, plotted on preprocessed ECG')
    ax.legend(loc = 'upper right')

    ax.set_xlabel('Time (s)')




.. image-sg:: /examples/images/sphx_glr_example_01_getting_started_005.png
   :alt: R peak detection, plotted on raw ECG, R peak detection, plotted on preprocessed ECG
   :srcset: /examples/images/sphx_glr_example_01_getting_started_005.png
   :class: sphx-glr-single-img


.. rst-class:: sphx-glr-script-out

 .. code-block:: none


    Text(0.5, 23.52222222222222, 'Time (s)')



.. GENERATED FROM PYTHON SOURCE LINES 195-204

Heart Rate Variability metrics (time-domain)
---------------------------------------------

:py:func:`~physio.compute_ecg_metrics`  is a high-level wrapper function that computes time-domain Heart Rate Variability (HRV) metrics from previously detected R peaks (`ecg_peaks`).
To use this function, you must provide the previously detected R peaks, `ecg_peaks`:

   * `ecg_peaks` : pd.DataFrame, output of the function :py:func:`~physio.compute_ecg`

We can visualize these metrics and the RR interval distribution. See :ref:`sphx_glr_examples_example_03_ecg.py` for a complete description of the metrics.

.. GENERATED FROM PYTHON SOURCE LINES 205-225

.. code-block:: Python


    ecg_metrics = physio.compute_ecg_metrics(ecg_peaks) # ecg_metrics = a pd.Series containing HRV time domain results

    peak_times = ecg_peaks['peak_time'].values # get R peak times of detection
    rri_s = np.diff(peak_times) # compute RR intervals in seconds
    rri_ms = rri_s * 1000 # seconds to milliseconds

    fig, ax = plt.subplots()
    ax.hist(rri_ms, bins=np.arange(500, 1400, 25), edgecolor = 'k') # plot distribution of RR intervals
    ax.axvline(ecg_metrics['HRV_Mean'], color='orange', label='Mean RRi') # vertical line at the mean RRi
    ax.axvline(ecg_metrics['HRV_Median'], color='violet', label='Median RRi') # vertical line at the median RRi
    ax.axvspan(ecg_metrics['HRV_Median'] - 2*ecg_metrics['HRV_Mad'], ecg_metrics['HRV_Median'] + 2*ecg_metrics['HRV_Mad'], color = 'orange', alpha = 0.1, label = 'Median +/- 2 * Median Absolute Deviation') # vertical span at the med + 2*mad
    ax.axvspan(ecg_metrics['HRV_Mean'] - 2*ecg_metrics['HRV_SD'], ecg_metrics['HRV_Mean'] + 2*ecg_metrics['HRV_SD'], color = 'violet', alpha = 0.1, label = 'Mean +/- 2 * Standard-Deviation') # vertical span at the mean + 2*sd
    ax.set_xlabel('RR interval (ms)')
    ax.set_ylabel('Count')
    ax.set_ylim(-5, 90)
    ax.legend(loc = 'upper center', ncols = 2)
    ax.set_title('Distribution or RR intervals + Heart Rate Variability metrics')
    print(ecg_metrics)




.. image-sg:: /examples/images/sphx_glr_example_01_getting_started_006.png
   :alt: Distribution or RR intervals + Heart Rate Variability metrics
   :srcset: /examples/images/sphx_glr_example_01_getting_started_006.png
   :class: sphx-glr-single-img


.. rst-class:: sphx-glr-script-out

 .. code-block:: none

    HRV_Mean         734.444717
    HRV_SD           145.936125
    HRV_Median       678.000000
    HRV_Mad          115.642973
    HRV_CV             0.198703
    HRV_MCV            0.170565
    HRV_Asymmetry    -56.444717
    HRV_RMSSD        103.553299
    dtype: float64




.. GENERATED FROM PYTHON SOURCE LINES 226-241

Heart Rate Variability metrics (frequency-domain)
-------------------------------------------------

:py:func:`~physio.compute_hrv_psd`  is a high-level wrapper function that computes frequency-domain Heart Rate Variability (HRV) metrics from previously detected R peaks (`ecg_peaks`).
To use this function, you must provide the previously detected R peaks, `ecg_peaks`:

   * `ecg_peaks` : pd.DataFrame, output of the function :py:func:`~physio.compute_ecg`

Many others parameters can be set for this function (frequency bands, size of the Welch's window, etc...). See :ref:`sphx_glr_examples_example_03_ecg.py` for more information about these.
When called, :py:func:`~physio.compute_hrv_psd` performs the following:

   * Compute an instantaneous heart rate vector from ecg peaks and compute a Fourier transform using Welch method (returns two NumPy arrays: `psd_freqs` and `psd` giving frequency vector and power vector, respectively).
   * Compute HRV frequency metrics by getting power for each frequency band using trapezoïdal rule (returns a pd.Series: `psd_metrics`)

We can visualize these metrics and the RR interval distribution. See :ref:`sphx_glr_examples_example_03_ecg.py` for a complete description of the metrics.

.. GENERATED FROM PYTHON SOURCE LINES 242-260

.. code-block:: Python


    frequency_bands = {'lf': (0.04, .15), 'hf' : (0.15, .4)} # set classical cutoffs of low and high frequency bands, in a dictionnary
    psd_freqs, psd, psd_metrics = physio.compute_hrv_psd(ecg_peaks=ecg_peaks, frequency_bands=frequency_bands)

    print(psd_metrics)
    fig, ax = plt.subplots()
    ax.plot(psd_freqs, psd)
    colors = {'lf': '#B8860B', 'hf' : '#D2691E'}
    for name, freq_band in frequency_bands.items():
        ax.axvspan(*freq_band, alpha=0.1, color=colors[name], label=f'{name} : {round(psd_metrics[name], 2)}') # plot one vertical span for each frequency band
    ax.set_xlim(0, 0.6)
    ax.set_xlabel('Frequency (Hz)')
    ax.set_ylabel('Power Spectral Density')
    ax.legend(loc = 'upper right')
    ax.set_title('HRV Power Spectral Density\n-> Frequency-Domain metrics')






.. image-sg:: /examples/images/sphx_glr_example_01_getting_started_007.png
   :alt: HRV Power Spectral Density -> Frequency-Domain metrics
   :srcset: /examples/images/sphx_glr_example_01_getting_started_007.png
   :class: sphx-glr-single-img


.. rst-class:: sphx-glr-script-out

 .. code-block:: none

    lf    189.890278
    hf     33.775978
    dtype: float64

    Text(0.5, 1.0, 'HRV Power Spectral Density\n-> Frequency-Domain metrics')



.. GENERATED FROM PYTHON SOURCE LINES 261-276

Cyclic deformation
------------------

:py:func:`~physio.deform_traces_to_cycle_template` is a tool used to deform traces to a cycle template.
It works by stretching a trace using linear resampling based on a fixed number of points per cycle.
This is helpful to explore if features of a signal are driven by a cyclic phenomenon like respiration.

To use this function, you must provide:

   * `data` : nd.array. Axis of the time must always be 0, meaning of shape (n_times,...).
   * `times` : np.array. Time vector of the data. Shape = (n_times,)
   * `cycle_times` : nd.array with shape (n_cycles, n_segments + 1). Typically, for respiration, `cycle_times` is an array with 3 columns (inspi_time + expi_time + next_inspi_time) that will make deformation with 2 segments. If cycle_times is 1D, then it is converted to shape (size-1, 2). The end of every cycles must match the start of the next cycle.
   * `points_per_cycle` : Number of phase points per cycle
   * `segment_ratios` : None or float or list of float. None if 1 segment. Float or list of float if 2 segments. List of floats if > 2 segments. This is a ratio between 0 and 1 where cycle is divided.
   * `output_mode` : 'stacked' / 'unstacked' / 'unstacked_full'. Format of the outputs. Stacked -> 2D matrix : cycles / points per cycle. Unstacked -> 1D matrix : flattened version of the stacked. Unstacked_full returns extra-outputs.

.. GENERATED FROM PYTHON SOURCE LINES 276-324

.. code-block:: Python


    # Here, we deform the respiratory trace by "itself": the respiratory cycle.
    # This leads to an average respiratory template. Importantly, this can be done using one or several segments inside the cycle.

    # here we have 3 times per cycle so 2 segments : 
    # segment 1: inspiration to expiration
    # segment 2: expiration to next inspiration

    cycle_times = resp_cycles[['inspi_time', 'expi_time', 'next_inspi_time']].values # get 3 timepoints per cycle, dividing each cycle in 2 segments

    segment_ratios = 0.4 # ratio between 0 and 1 where cycle is divided into 2 segments
    deformed_resp_2seg = physio.deform_traces_to_cycle_template(resp, # resp trace to deform
                                                                times, # time vector of resp trace to deform
                                                                 cycle_times,  # times of resp cycles, used to strech
                                                                 points_per_cycle=40,  # number of points per cycle used for linear resampling
                                                                 segment_ratios=segment_ratios, # ratio between 0 and 1 where cycle is divided into 2 segments
                                                                 output_mode='stacked' # choose a stacked version of the returned matrix (see docstrings)
                                                                 )
    print(deformed_resp_2seg.shape, cycle_times.shape)

    # here we have 2 times per cycle so 1 segment:
    # segment 1: inspiration to next inspiration

    cycle_times = resp_cycles[['inspi_time', 'next_inspi_time']].values # get 2 timepoints per cycle, dividing each cycle in 1 segment (so not dividing)
    deformed_resp_1seg = physio.deform_traces_to_cycle_template(resp, # resp trace to deform
                                                                times, # time vector of resp trace to deform
                                                                 cycle_times,  # times of resp cycles, used to strech
                                                                 points_per_cycle=40,  # number of points per cycle used for linear resampling
                                                                 segment_ratios=None, # ratio between 0 and 1 where cycle is divided into 2 segments. None in this case because 1 segment
                                                                 output_mode='stacked' # choose a stacked version of the returned matrix (see docstrings)
                                                                 )
    print(deformed_resp_1seg.shape, cycle_times.shape)

    fig, axs = plt.subplots(ncols=2, sharey=True, figsize = (8,4))

    ax = axs[0]
    physio.plot_cyclic_deformation(deformed_resp_2seg, segment_ratios=0.4, two_cycles=False, ax=ax) # using function physio.plot_cyclic_deformation to plot
    ax.set_title('Deformation: 2 segments')
    ax.set_ylabel('Resp Amplitude (AU)')

    ax = axs[1]
    physio.plot_cyclic_deformation(deformed_resp_1seg, segment_ratios=None, two_cycles=False, ax=ax) # using function physio.plot_cyclic_deformation to plot
    ax.set_title('Deformation: 1 segment')

    for ax in axs:
        ax.set_xlabel('Points per cycle (= respiratory phase)')





.. image-sg:: /examples/images/sphx_glr_example_01_getting_started_008.png
   :alt: Deformation: 2 segments, Deformation: 1 segment
   :srcset: /examples/images/sphx_glr_example_01_getting_started_008.png
   :class: sphx-glr-single-img


.. rst-class:: sphx-glr-script-out

 .. code-block:: none

    (30, 40) (30, 3)
    (30, 40) (30, 2)




.. GENERATED FROM PYTHON SOURCE LINES 325-330

Cyclic deformation on ECG
-------------------------

Let's use the same :py:func:`~physio.deform_traces_to_cycle_template` tool for ECG trace.
We can use a simple time vector: the R peak times. In this case, the ECG trace is converted as a 1-segment.

.. GENERATED FROM PYTHON SOURCE LINES 331-349

.. code-block:: Python



    cycle_times = ecg_peaks['peak_time'].values # one cycle = R to R -> one segment by R to R period
    deformed_ecg = physio.deform_traces_to_cycle_template(ecg, # ecg trace to deform
                                                          times, # time vector of ecg trace to deform
                                                          cycle_times, # times of ecg cycles = R to R periods, used to strech
                                                          points_per_cycle=300, # number of points per cycle used for linear resampling (more than for resp because ecg trace has faster dynamics)
                                                          segment_ratios=None, # 1 segment so None
                                                          output_mode='stacked'
                                                          )
    print(deformed_ecg.shape, cycle_times.shape)

    fig, ax = plt.subplots()
    physio.plot_cyclic_deformation(deformed_ecg, two_cycles=True, ax=ax) # set two_cycles = True to see a concatenation of two cyclical deformations, so that we can see the whole PQRST complex
    ax.set_title('Two ECG cyclical deformations concatenated:\nnormalized view of the whole PQRST complex')
    ax.set_ylabel('Amplitude (AU)')
    ax.set_xlabel('Points per cycle * 2')




.. image-sg:: /examples/images/sphx_glr_example_01_getting_started_009.png
   :alt: Two ECG cyclical deformations concatenated: normalized view of the whole PQRST complex
   :srcset: /examples/images/sphx_glr_example_01_getting_started_009.png
   :class: sphx-glr-single-img


.. rst-class:: sphx-glr-script-out

 .. code-block:: none

    (407, 300) (408,)

    Text(0.5, 23.52222222222222, 'Points per cycle * 2')




.. rst-class:: sphx-glr-timing

   **Total running time of the script:** (0 minutes 1.306 seconds)


.. _sphx_glr_download_examples_example_01_getting_started.py:

.. only:: html

  .. container:: sphx-glr-footer sphx-glr-footer-example

    .. container:: sphx-glr-download sphx-glr-download-jupyter

      :download:`Download Jupyter notebook: example_01_getting_started.ipynb <example_01_getting_started.ipynb>`

    .. container:: sphx-glr-download sphx-glr-download-python

      :download:`Download Python source code: example_01_getting_started.py <example_01_getting_started.py>`

    .. container:: sphx-glr-download sphx-glr-download-zip

      :download:`Download zipped: example_01_getting_started.zip <example_01_getting_started.zip>`


.. only:: html

 .. rst-class:: sphx-glr-signature

    `Gallery generated by Sphinx-Gallery <https://sphinx-gallery.github.io>`_