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

.. only:: html

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

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

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

.. _sphx_glr_auto_examples_cad__01_cad_from_ic.py:


Cadence from Initial Contacts
=============================

The most obvious way to calculate cadence is to use the detected initial contacts.
However, initial contact (IC) detection from a single lower back sensor is never perfect.
If we naively calculate cadence via a step time derived by "diffing" the initial contacts, missing ICs or
even actual breaks in the gait sequence will lead to wrong cadence values (likely underestimating the cadence).
We need to be robust to these types of errors.

On the other hand, for the cadence estimation it is less important that the position of the IC within the
stride is perfectly correct.
This means, different IC detection methods might be optimal for the cadence estimation than for the IC detection itself.

With these two things in mind, we implemented "Proxy" cadence algorithms that work on top of any IC detection method.
Two variants exist:

1. :class:`~mobgap.algorithm.CadFromIc` calculates the cadence directly from the provided ICs using step-to-step
   smoothing to deal with missing ICs and breaks in the gait sequence.
   This method should be used, if you want to use the same IC detection method for the cadence estimation than for the
   IC detection itself (i.e. we are not rerunning any calculations, we just use the provided ICs).
2. :class:`~mobgap.algorithm.CadFromIcDetector` is a proxy algorithm that wraps around any IC detection algorithm.
   Compared to the previous method, this method will ignore the provided ICs and run the IC detection algorithm it
   wraps (which can be different from the one used for the IC detection itself) to find new ICs that are only used
   for the Cadence estimation.

Both methods than use step-to-step smoothing to deal with missing ICs and breaks in the gait sequence and then
interpolate all step time values to seconds to provide an average cadence for each one second interval of the
recording.

Below we will demonstrate the usage of both methods. But first we load some data.

Example Data
------------
We load example data from the lab dataset together with the INDIP reference system.
We will use a single short-trail from the "HA" participant for this example, as it only contains a single gait sequence.
All the cadence algorithms are designed to work on a single gait sequence at a time.

.. GENERATED FROM PYTHON SOURCE LINES 40-48

.. code-block:: default


    from mobgap.data import LabExampleDataset

    lab_example_data = LabExampleDataset(reference_system="INDIP")
    short_trial: LabExampleDataset = lab_example_data.get_subset(
        cohort="HA", participant_id="001", test="Test5", trial="Trial2"
    )








.. GENERATED FROM PYTHON SOURCE LINES 49-53

CadFromIc
---------
To demonstrate the usage of :class:`~mobgap.algorithm.CadFromIc` we use the detected initial contacts from the
reference system as input.

.. GENERATED FROM PYTHON SOURCE LINES 53-56

.. code-block:: default

    reference_ic = short_trial.reference_parameters_relative_to_wb_.ic_list
    reference_ic






.. 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></th>
          <th>ic</th>
          <th>lr_label</th>
        </tr>
        <tr>
          <th>wb_id</th>
          <th>step_id</th>
          <th></th>
          <th></th>
        </tr>
      </thead>
      <tbody>
        <tr>
          <th rowspan="9" valign="top">1</th>
          <th>0</th>
          <td>0</td>
          <td>left</td>
        </tr>
        <tr>
          <th>1</th>
          <td>63</td>
          <td>right</td>
        </tr>
        <tr>
          <th>2</th>
          <td>118</td>
          <td>left</td>
        </tr>
        <tr>
          <th>3</th>
          <td>177</td>
          <td>right</td>
        </tr>
        <tr>
          <th>4</th>
          <td>230</td>
          <td>left</td>
        </tr>
        <tr>
          <th>5</th>
          <td>288</td>
          <td>right</td>
        </tr>
        <tr>
          <th>6</th>
          <td>345</td>
          <td>left</td>
        </tr>
        <tr>
          <th>7</th>
          <td>407</td>
          <td>right</td>
        </tr>
        <tr>
          <th>8</th>
          <td>469</td>
          <td>left</td>
        </tr>
      </tbody>
    </table>
    </div>
    </div>
    <br />
    <br />

.. GENERATED FROM PYTHON SOURCE LINES 57-60

.. code-block:: default

    reference_gs = short_trial.reference_parameters_relative_to_wb_.wb_list
    reference_gs






.. 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>start</th>
          <th>end</th>
          <th>n_strides</th>
          <th>duration_s</th>
          <th>length_m</th>
          <th>avg_speed_mps</th>
          <th>avg_cadence_spm</th>
          <th>avg_stride_length_m</th>
          <th>termination_reason</th>
        </tr>
        <tr>
          <th>wb_id</th>
          <th></th>
          <th></th>
          <th></th>
          <th></th>
          <th></th>
          <th></th>
          <th></th>
          <th></th>
          <th></th>
        </tr>
      </thead>
      <tbody>
        <tr>
          <th>1</th>
          <td>392</td>
          <td>862</td>
          <td>7</td>
          <td>4.69</td>
          <td>4.76565</td>
          <td>1.046655</td>
          <td>103.453056</td>
          <td>1.211187</td>
          <td>Pause</td>
        </tr>
      </tbody>
    </table>
    </div>
    </div>
    <br />
    <br />

.. GENERATED FROM PYTHON SOURCE LINES 61-64

Then we initialize the algorithm and call the ``calculate`` method.
Note that we use the ``sampling_rate_hz`` of the actual data and not the reference system.
This is because, the reference parameters are already converted to the data sampling rate.

.. GENERATED FROM PYTHON SOURCE LINES 64-74

.. code-block:: default

    from mobgap.cad import CadFromIc

    cad_from_ic = CadFromIc()

    gs_id = reference_gs.index[0]
    data_in_gs = short_trial.data["LowerBack"].iloc[reference_gs.start.iloc[0] : reference_gs.end.iloc[0]]
    ics_in_gs = reference_ic[["ic"]].loc[gs_id]

    cad_from_ic.calculate(data_in_gs, ics_in_gs, sampling_rate_hz=short_trial.sampling_rate_hz)





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

 .. code-block:: none

    /home/docs/checkouts/readthedocs.org/user_builds/mobgap/checkouts/v0.2.0/mobgap/cad/_cad_from_ic.py:183: UserWarning: Usually we assume that gait sequences are cut to the first and last detected initial contact. This is not the case for the passed initial contacts and might lead to unexpected results in the cadence calculation. Specifically, you will get NaN values at the start and the end of the output.
      initial_contacts = self._get_ics(data, initial_contacts, sampling_rate_hz)["ic"]

    CadFromIc(max_interpolation_gap_s=3, step_time_smoothing=HampelFilter(half_window_size=2, n_sigmas=3.0))



.. GENERATED FROM PYTHON SOURCE LINES 75-77

We get an output that contains the cadence for each second of the gaits sequence.
The index represents the sample of the center of the second the cadence value belongs to.

.. GENERATED FROM PYTHON SOURCE LINES 77-79

.. code-block:: default

    cad_from_ic.cad_per_sec_






.. 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>cad_spm</th>
        </tr>
        <tr>
          <th>sec_center_samples</th>
          <th></th>
        </tr>
      </thead>
      <tbody>
        <tr>
          <th>50</th>
          <td>101.694915</td>
        </tr>
        <tr>
          <th>150</th>
          <td>107.142857</td>
        </tr>
        <tr>
          <th>250</th>
          <td>104.347826</td>
        </tr>
        <tr>
          <th>350</th>
          <td>96.774194</td>
        </tr>
      </tbody>
    </table>
    </div>
    </div>
    <br />
    <br />

.. GENERATED FROM PYTHON SOURCE LINES 80-82

To show that the approach results in roughly the "correct" cadence value, we can compare the average cadence to the
reference system.

.. GENERATED FROM PYTHON SOURCE LINES 82-87

.. code-block:: default

    reference_cad = reference_gs["avg_cadence_spm"].loc[gs_id]
    cad_from_ic_avg_cad = cad_from_ic.cad_per_sec_["cad_spm"].mean()
    print(f"Average stride cadence from reference: {reference_cad:.2f} steps/min")
    print(f"Calculated average per-sec cadence: {cad_from_ic_avg_cad:.2f} steps/min")





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

 .. code-block:: none

    Average stride cadence from reference: 103.45 steps/min
    Calculated average per-sec cadence: 102.49 steps/min




.. GENERATED FROM PYTHON SOURCE LINES 88-97

Note that if we would have breaks in the gait sequence, the method would try to interpolate the cadence values for
short breaks, but would provide NaNs for longer breaks.
This is controlled by the ``max_interpolation_gap_s`` parameter.

CadFromIcDetector
-----------------
For the :class:`~mobgap.cad.CadFromIcDetector` we need to supply an IC detection algorithm.
In this case we use the :class:`~mobgap.icd.IcdShinImproved` algorithm.
We could also use any other IC detection algorithm or adapt the parameters of the IC detection algorithm.

.. GENERATED FROM PYTHON SOURCE LINES 97-102

.. code-block:: default

    from mobgap.cad import CadFromIcDetector
    from mobgap.icd import IcdShinImproved

    cad_from_ic_detector = CadFromIcDetector(IcdShinImproved())








.. GENERATED FROM PYTHON SOURCE LINES 103-107

Now we can call the ``calculate`` method with the same data as before.
Note, that we are still passing the initial contacts from the "previous" calculation step to fulfill the API.
However, internally the algorithm will ignore the provided ICs and rerun the IC detection using the provided IC
detector.

.. GENERATED FROM PYTHON SOURCE LINES 107-109

.. code-block:: default

    cad_from_ic_detector.calculate(data_in_gs, initial_contacts=ics_in_gs, sampling_rate_hz=short_trial.sampling_rate_hz)





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

 .. code-block:: none

    /home/docs/checkouts/readthedocs.org/user_builds/mobgap/checkouts/v0.2.0/examples/cad/_01_cad_from_ic.py:107: UserWarning: This method ignores the passed initial contacts and recalculates them from the data. This way you can use a different IC detector for the cadence calculation than for the IC detection. If you don't want this, you should use the `CadFromIc` class instead.

    This warning is just a information to make sure you are fully aware of this. If you want to silence this warning, you can pass ``silence_ic_warning=True`` during the initialization of this class.
      cad_from_ic_detector.calculate(data_in_gs, initial_contacts=ics_in_gs, sampling_rate_hz=short_trial.sampling_rate_hz)

    CadFromIcDetector(ic_detector=IcdShinImproved(axis='norm'), max_interpolation_gap_s=3, silence_ic_warning=False, step_time_smoothing=HampelFilter(half_window_size=2, n_sigmas=3.0))



.. GENERATED FROM PYTHON SOURCE LINES 110-117

.. note:: By default the ``CadFromIcDetector`` will raise a warning to inform the user that the passed ICs are
          ignored.
          This is intentionally, as we assume first time users might be confused by that fact.
          If you are aware of this and want to get rid of the warning, you can set ``silence_ic_warning`` to
          True on the ``CadFromIcDetector`` object.

We get the same output structure as before.

.. GENERATED FROM PYTHON SOURCE LINES 117-119

.. code-block:: default

    cad_from_ic_detector.cad_per_sec_






.. 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>cad_spm</th>
        </tr>
        <tr>
          <th>sec_center_samples</th>
          <th></th>
        </tr>
      </thead>
      <tbody>
        <tr>
          <th>50</th>
          <td>101.694915</td>
        </tr>
        <tr>
          <th>150</th>
          <td>106.194690</td>
        </tr>
        <tr>
          <th>250</th>
          <td>104.347826</td>
        </tr>
        <tr>
          <th>350</th>
          <td>97.560976</td>
        </tr>
      </tbody>
    </table>
    </div>
    </div>
    <br />
    <br />

.. GENERATED FROM PYTHON SOURCE LINES 120-121

But we can also access the detected initial contacts.

.. GENERATED FROM PYTHON SOURCE LINES 121-123

.. code-block:: default

    cad_from_ic_detector.internal_ic_list_






.. 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>ic</th>
        </tr>
        <tr>
          <th>step_id</th>
          <th></th>
        </tr>
      </thead>
      <tbody>
        <tr>
          <th>0</th>
          <td>52</td>
        </tr>
        <tr>
          <th>1</th>
          <td>111</td>
        </tr>
        <tr>
          <th>2</th>
          <td>167</td>
        </tr>
        <tr>
          <th>3</th>
          <td>224</td>
        </tr>
        <tr>
          <th>4</th>
          <td>279</td>
        </tr>
        <tr>
          <th>5</th>
          <td>339</td>
        </tr>
        <tr>
          <th>6</th>
          <td>399</td>
        </tr>
        <tr>
          <th>7</th>
          <td>462</td>
        </tr>
      </tbody>
    </table>
    </div>
    </div>
    <br />
    <br />

.. GENERATED FROM PYTHON SOURCE LINES 124-125

Or the entire detector object.

.. GENERATED FROM PYTHON SOURCE LINES 125-127

.. code-block:: default

    cad_from_ic_detector.ic_detector_





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

 .. code-block:: none


    IcdShinImproved(axis='norm')



.. GENERATED FROM PYTHON SOURCE LINES 128-133

To show that the approach results in roughly the "correct" cadence value, we can compare the average cadence to the
reference system.

.. note:: Compared to the previous method, the cadence value are more different, as we actually run a IC
         detection algorithm to find the ICs and not just used the values provided by the reference.

.. GENERATED FROM PYTHON SOURCE LINES 133-137

.. code-block:: default

    cad_from_ic_detector_avg_cad = cad_from_ic_detector.cad_per_sec_["cad_spm"].mean()
    print(f"Average stride cadence from reference: {reference_cad:.2f} steps/min")
    print(f"Calculated average per-sec cadence (CadFromIC): {cad_from_ic_avg_cad:.2f} steps/min")
    print(f"Calculated average per-sec cadence (CadFromIcDetector): {cad_from_ic_detector_avg_cad:.2f} steps/min")




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

 .. code-block:: none

    Average stride cadence from reference: 103.45 steps/min
    Calculated average per-sec cadence (CadFromIC): 102.49 steps/min
    Calculated average per-sec cadence (CadFromIcDetector): 102.45 steps/min





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

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

**Estimated memory usage:**  13 MB


.. _sphx_glr_download_auto_examples_cad__01_cad_from_ic.py:

.. only:: html

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




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

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

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

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


.. only:: html

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

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