.. DO NOT EDIT.
.. THIS FILE WAS AUTOMATICALLY GENERATED BY SPHINX-GALLERY.
.. TO MAKE CHANGES, EDIT THE SOURCE PYTHON FILE:
.. "auto_examples/aggregation/_01_mobilised_aggregator.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_aggregation__01_mobilised_aggregator.py>`
        to download the full example code

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

.. _sphx_glr_auto_examples_aggregation__01_mobilised_aggregator.py:


.. _mobilised_aggregator_example:

Mobilised Aggregator
====================

This example shows how to use the :class:`.MobilisedAggregator` class to aggregate DMOs over multiple walking bouts.

.. GENERATED FROM PYTHON SOURCE LINES 12-19

Loading some example data
-------------------------
.. note :: This data is randomly generated and not physiologically meaningful. However, it has the same structure as
   any other typical input dataset for the :class:`.MobilisedAggregator`.

The input data for the aggregator is a :class:`pandas.DataFrame` with one row for every walking bout.
The columns contain the DMO parameters estimated for each walking bout, such as duration, stride length, etc.

.. GENERATED FROM PYTHON SOURCE LINES 19-33

.. code-block:: default


    import pandas as pd
    from mobgap import PACKAGE_ROOT
    from mobgap.aggregation import MobilisedAggregator

    DATA_PATH = (
        PACKAGE_ROOT.parent / "example_data/original_results/mobilised_aggregator"
    )

    data = pd.read_csv(
        DATA_PATH / "aggregation_test_input.csv", index_col=0
    ).set_index(["visit_type", "participant_id", "measurement_date", "wb_id"])
    data.head()






.. 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></th>
          <th></th>
          <th>duration_s</th>
          <th>n_steps</th>
          <th>cadence_spm</th>
          <th>walking_speed_mps</th>
          <th>stride_length_m</th>
          <th>stride_duration_s</th>
          <th>n_turns</th>
        </tr>
        <tr>
          <th>visit_type</th>
          <th>participant_id</th>
          <th>measurement_date</th>
          <th>wb_id</th>
          <th></th>
          <th></th>
          <th></th>
          <th></th>
          <th></th>
          <th></th>
          <th></th>
        </tr>
      </thead>
      <tbody>
        <tr>
          <th rowspan="5" valign="top">T1</th>
          <th rowspan="5" valign="top">12345</th>
          <th rowspan="5" valign="top">2023-01-01</th>
          <th>0</th>
          <td>4.74702</td>
          <td>8</td>
          <td>99.82188</td>
          <td>1.16079</td>
          <td>2.51885</td>
          <td>1.58675</td>
          <td>0</td>
        </tr>
        <tr>
          <th>1</th>
          <td>5.13150</td>
          <td>7</td>
          <td>101.16429</td>
          <td>2.57881</td>
          <td>1.57243</td>
          <td>1.46537</td>
          <td>0</td>
        </tr>
        <tr>
          <th>2</th>
          <td>8.52727</td>
          <td>12</td>
          <td>86.53527</td>
          <td>1.60044</td>
          <td>1.66305</td>
          <td>2.56092</td>
          <td>2</td>
        </tr>
        <tr>
          <th>3</th>
          <td>16.24554</td>
          <td>27</td>
          <td>91.49977</td>
          <td>0.95558</td>
          <td>0.88961</td>
          <td>3.14549</td>
          <td>1</td>
        </tr>
        <tr>
          <th>4</th>
          <td>6.09907</td>
          <td>8</td>
          <td>93.69895</td>
          <td>2.33230</td>
          <td>1.95969</td>
          <td>2.35295</td>
          <td>0</td>
        </tr>
      </tbody>
    </table>
    </div>
    </div>
    <br />
    <br />

.. GENERATED FROM PYTHON SOURCE LINES 34-46

Furthermore, the aggregator allows to provide a data mask, which is a boolean :class:`pandas.DataFrame` with the same
dimensions as the input data.
The data mask indicates which DMOs of the input data should be used for the aggregation (marked as True) and which
should be ignored (marked as False).

For this example, we create this mask by applying the "standard" thresholds from Mobilise-D to the data.
To learn more about this see the example :ref:`threshold_check example <threshold_check_example>`.

.. note :: It is only possible to use the ``apply_thresholds`` function here, as all the example data is from the same
   participant.
   As some thresholds are cohort or height specific, you would have to apply the thresholds for each participant data
   separately.

.. GENERATED FROM PYTHON SOURCE LINES 46-58

.. code-block:: default

    from mobgap.aggregation import apply_thresholds, get_mobilised_dmo_thresholds

    thresholds = get_mobilised_dmo_thresholds()
    # Note: The height is "artificially" set to 1.75m, as the example data does not contain this information.
    data_mask = apply_thresholds(
        data,
        thresholds,
        cohort="HA",
        height_m=1.75,
        measurement_condition="free_living",
    )








.. GENERATED FROM PYTHON SOURCE LINES 59-65

Performing the aggregation
--------------------------
The :class:`.MobilisedAggregator` is now used to aggregate the input data over several walking bouts, e.g., over all
walking bouts from one participant, or over all walking bouts per participant and day, week, or other criteria.
The data is grouped using additional columns in the input data, which are not used for the aggregation itself.
In this example, the data is grouped by participant (`subject_code`) and day (`visit_date`).

.. GENERATED FROM PYTHON SOURCE LINES 65-73

.. code-block:: default

    agg = MobilisedAggregator(
        **dict(
            MobilisedAggregator.PredefinedParameters.cvs_dmo_data,
            use_original_names=False,
        )
    )
    agg.aggregate(data, wb_dmos_mask=data_mask)





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

 .. code-block:: none


    MobilisedAggregator(groupby=['visit_type', 'participant_id', 'measurement_date'], unique_wb_id_column='wb_id', use_original_names=False)



.. GENERATED FROM PYTHON SOURCE LINES 74-76

The resulting :class:`pandas.DataFrame` containing the aggregated data contains one row for every group.
In this case, there is only one participant and day, so the resulting dataframe contains only one row.

.. GENERATED FROM PYTHON SOURCE LINES 76-79

.. code-block:: default

    agg_data = agg.aggregated_data_
    agg_data






.. 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></th>
          <th>wb_all__count</th>
          <th>total_walking_duration_h</th>
          <th>wb_all__n_steps__sum</th>
          <th>wb_all__n_turns__sum</th>
          <th>wb_all__duration_s__avg</th>
          <th>wb_all__duration_s__max</th>
          <th>wb_all__duration_s__var</th>
          <th>wb_all__cadence_spm__avg</th>
          <th>wb_all__stride_duration_s__avg</th>
          <th>wb_all__cadence_spm__var</th>
          <th>wb_all__stride_duration_s__var</th>
          <th>wb_10_30__count</th>
          <th>wb_10_30__walking_speed_mps__avg</th>
          <th>wb_10_30__stride_length_m__avg</th>
          <th>wb_10__count</th>
          <th>wb_10__walking_speed_mps__max</th>
          <th>wb_30__count</th>
          <th>wb_30__walking_speed_mps__avg</th>
          <th>wb_30__stride_length_m__avg</th>
          <th>wb_30__cadence_spm__avg</th>
          <th>wb_30__stride_duration_s__avg</th>
          <th>wb_30__walking_speed_mps__max</th>
          <th>wb_30__cadence_spm__max</th>
          <th>wb_30__walking_speed_mps__var</th>
          <th>wb_30__stride_length_m__var</th>
          <th>wb_60__count</th>
        </tr>
        <tr>
          <th>visit_type</th>
          <th>participant_id</th>
          <th>measurement_date</th>
          <th></th>
          <th></th>
          <th></th>
          <th></th>
          <th></th>
          <th></th>
          <th></th>
          <th></th>
          <th></th>
          <th></th>
          <th></th>
          <th></th>
          <th></th>
          <th></th>
          <th></th>
          <th></th>
          <th></th>
          <th></th>
          <th></th>
          <th></th>
          <th></th>
          <th></th>
          <th></th>
          <th></th>
          <th></th>
          <th></th>
        </tr>
      </thead>
      <tbody>
        <tr>
          <th>T1</th>
          <th>12345</th>
          <th>2023-01-01</th>
          <td>2378</td>
          <td>10.534135</td>
          <td>59320</td>
          <td>3012</td>
          <td>8.85868</td>
          <td>26.926738</td>
          <td>2.27456</td>
          <td>94.673461</td>
          <td>2.212942</td>
          <td>0.127248</td>
          <td>0.261023</td>
          <td>844</td>
          <td>1.496715</td>
          <td>1.86458</td>
          <td>1029</td>
          <td>2.096355</td>
          <td>185</td>
          <td>1.619353</td>
          <td>1.975227</td>
          <td>102.806937</td>
          <td>2.100595</td>
          <td>2.12756</td>
          <td>115.174986</td>
          <td>0.240867</td>
          <td>0.252349</td>
          <td>62</td>
        </tr>
      </tbody>
    </table>
    </div>
    </div>
    <br />
    <br />

.. GENERATED FROM PYTHON SOURCE LINES 80-97

.. warning:: To exactly match the expected output of the original Mobilise-D R-Script, the two stride length
             parameters would need to be converted to cm and all values rounded to 3 decimals.
             This is not done in the Python implementation to be consistent with the units across the entire package.

Comparison with R aggregation script
------------------------------------
The outputs of this aggregation algorithm are analogous to the outputs of the original Mobilise-D R-Script, using
the same duration filters and aggregation metrics.
However, there can be small differences in the second/third decimal place range in the results. This is due to
different outputs of the quantile function in Python and R.
Furthermore, the parameter "strlen_30_var" is converted to cm for consistency, while it is in m in the original
R-Script.
By grouping the data by participant and day, the results the Daily Aggregations of the original R-Script are
retrieved.
To get the Weekly Aggregations, the Daily results are averaged over all recording days per participant and rounded
depending on the aggregation metric. Obviously, in this example, the results are identical to the Daily Aggregations,
as there is only data from one day contained.

.. GENERATED FROM PYTHON SOURCE LINES 97-133

.. code-block:: default

    weekly_agg = (
        agg.aggregated_data_.groupby("participant_id")
        .mean(numeric_only=True)
        .reset_index()
    )
    round_to_int_original_cols = [
        "steps_all_sum",
        "turns_all_sum",
        "wb_all_sum",
        "wb_10_sum",
        "wb_30_sum",
        "wb_60_sum",
    ]
    round_to_int_new_cols = [
        "wb_all__n_steps__sum",
        "wb_all__n_turns__sum",
        "wb_all__count",
        "wb_10__count",
        "wb_30__count",
        "wb_60__count",
    ]

    round_to_int = (
        round_to_int_original_cols
        if agg.use_original_names
        else round_to_int_new_cols
    )

    round_to_three_decimals = weekly_agg.columns[
        ~weekly_agg.columns.isin(round_to_int)
    ]
    weekly_agg[round_to_int] = weekly_agg[round_to_int].round()
    weekly_agg[round_to_three_decimals] = weekly_agg[round_to_three_decimals].round(
        3
    )
    weekly_agg





.. 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>participant_id</th>
          <th>wb_all__count</th>
          <th>total_walking_duration_h</th>
          <th>wb_all__n_steps__sum</th>
          <th>wb_all__n_turns__sum</th>
          <th>wb_all__duration_s__avg</th>
          <th>wb_all__duration_s__max</th>
          <th>wb_all__duration_s__var</th>
          <th>wb_all__cadence_spm__avg</th>
          <th>wb_all__stride_duration_s__avg</th>
          <th>wb_all__cadence_spm__var</th>
          <th>wb_all__stride_duration_s__var</th>
          <th>wb_10_30__count</th>
          <th>wb_10_30__walking_speed_mps__avg</th>
          <th>wb_10_30__stride_length_m__avg</th>
          <th>wb_10__count</th>
          <th>wb_10__walking_speed_mps__max</th>
          <th>wb_30__count</th>
          <th>wb_30__walking_speed_mps__avg</th>
          <th>wb_30__stride_length_m__avg</th>
          <th>wb_30__cadence_spm__avg</th>
          <th>wb_30__stride_duration_s__avg</th>
          <th>wb_30__walking_speed_mps__max</th>
          <th>wb_30__cadence_spm__max</th>
          <th>wb_30__walking_speed_mps__var</th>
          <th>wb_30__stride_length_m__var</th>
          <th>wb_60__count</th>
        </tr>
      </thead>
      <tbody>
        <tr>
          <th>0</th>
          <td>12345</td>
          <td>2378.0</td>
          <td>10.534</td>
          <td>59320.0</td>
          <td>3012.0</td>
          <td>8.859</td>
          <td>26.927</td>
          <td>2.275</td>
          <td>94.673</td>
          <td>2.213</td>
          <td>0.127</td>
          <td>0.261</td>
          <td>844.0</td>
          <td>1.497</td>
          <td>1.865</td>
          <td>1029.0</td>
          <td>2.096</td>
          <td>185.0</td>
          <td>1.619</td>
          <td>1.975</td>
          <td>102.807</td>
          <td>2.101</td>
          <td>2.128</td>
          <td>115.175</td>
          <td>0.241</td>
          <td>0.252</td>
          <td>62.0</td>
        </tr>
      </tbody>
    </table>
    </div>
    </div>
    <br />
    <br />


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

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

**Estimated memory usage:**  9 MB


.. _sphx_glr_download_auto_examples_aggregation__01_mobilised_aggregator.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_mobilised_aggregator.py <_01_mobilised_aggregator.py>`

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

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


.. only:: html

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

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