---
title: "4. From Raw Data to Acceleration Metrics"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{4. From Raw Data to Acceleration Metrics}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>"
)
```

## Why do we need to extract metrics

Wearable accelerometers are widely used in health research to study physical activity, sleep, and other behaviours.
Most modern accelerometers are able to collect and store at least 30 values per second expressed in units of gravitational acceleration (*g*).
Once the data is collected, health researchers typically want to derive from this data:

1.  Activity types and body postures like sleep, walking, running, sitting, etc.

2.  Energy expenditure or a measure of body acceleration that can act as a good proxy for energy expenditure.

3.  Various other outcomes, i.e. gait, balance, circadian rhythm analysis, and falls.

A critical step in going from the high-resolution data to the classification of activity type or energy expenditure is to calculate metrics, also known as signal features.
A metric allows us to extract information from the signal.
One approach is to calculate statistical properties of the data like the mean, standard deviation, entropy, and skewness.
Another approach is to design the data metrics with domain knowledge about the process that generated the data.
I personally prefer the domain knowledge-driven approach because it allows us to narrow down the search space for a successful metric and it aims at a good understanding of what we calculate.

In the domain-driven approach a distinction is made between three acceleration signal components:

1.  Acceleration related to gravitational acceleration and by that the orientation of the accelerometer relative to gravity.

2.  Accelerations and decelerations related to movement and by that a proxy of muscle contractions and the energy expenditure needed for them.

3.  Signal noise.

Finding a metric that can separate these three components will provide informative value in relation to posture and magnitude of acceleration as a proxy for muscle contraction related to body movement and associated energy expenditure.

## Metric aggregation per epoch

Although most metrics are calculated per time point, which reflect a tiny fraction of a second, GGIR then continues to aggregate these values per epoch (e.g., 5 seconds) for the following reasons:

-   Aggregation per epoch reduces value dependency on sampling frequency, which varies between studies, and by that eases comparisons across studies.

-   Evidence on the value of accelerometer data is based on epoch level aggregates, because reference values like Oxygen consumption or sleep cannot reliably be derived at sub-second resolution.

The epoch length is kept constant within GGIR to allow for consistent interpretation.
The epoch length is set with the first value of parameter `windowsizes` and used throughout all steps of GGIR, with the following exceptions:

-   In GGIR part 2, the time spent in MVPA variables (as discussed in a later chapter) is done with multiple epoch lengths, one for each output variable.
    However, per output variable the epoch length is held constant throughout the recording.
    GGIR never mixes epoch lengths.

-   In GGIR part 5, the user has the option to aggregate all epochs to 1 minute length with parameter `part5_agg2_60seconds`.
    For example, when using 5 second epochs in parts 1, 2, 3 and 4, it can be informative to run part 5 with 1 minute epoch length.

## Acceleration metrics available in GGIR

Below you will find a list of all metrics that GGIR can apply.
Multiple metrics can be derived in the same GGIR run.
All acceleration metrics are derived in GGIR function [`g.applymetrics`](https://github.com/wadpac/GGIR/blob/master/R/g.applymetrics.R).
Only for Neishabouri counts GGIR relies on R package `actifelifecounts`.
Please see code for exact calculations.
To use the metrics, add the parameters to your GGIR call, e.g.:

```         
GGIR(do.enmo = TRUE, do.mad = TRUE, do.bfen = TRUE, …)
```

| Metric name        | Description (see internal code for exact calculation)                                                                                                          | Collapse to epoch | Parameter to tell GGIR to derive this metric by setting it to TRUE or FALSE | Separation of gravity   |
|---------------|---------------|---------------|---------------|---------------|
| enmo               | Euclidean norm minus one with resulting negative values rounded to zero                                                                                        | Average           | do.enmo                                                                     | Magnitude               |
| lfenmo             | Same as enmo but with low-passed filtered signals as input                                                                                                     | Average           | do.lfenmo                                                                   | Magnitude               |
| enmoa              | Same as enmo but with rectified negative values instead of rounded to zero                                                                                     | Average           | do.enmoa                                                                    | Magnitude               |
| en                 | Euclidean norm (vector magnitude)                                                                                                                              | Average           | do.en                                                                       | Not attempted           |
| mad                | Absolute difference between Euclidean norm and epoch level average of the Euclidean norm                                                                       | Average           | do.mad                                                                      | Frequency               |
| anglex             | 5-second rolling median of a 10 Hertz version of the signals followed by atan(x / (sqrt(y^2^ + z^2^))) / (pi/180)                                              | Average           | do.anglex                                                                   | Frequency               |
| angley             | 5-second rolling median of a 10 Hertz version of the signals followed by atan(y / (sqrt(x^2^ + z^2^))) / (pi/180)                                              | Average           | do.angley                                                                   | Frequency               |
| anglez             | 5-second rolling median of a 10 Hertz version of the signals followed by atan(z/ (sqrt(x^2^ + y^2^))) / (pi/180)                                               | Average           | do.anglez                                                                   | Frequency               |
| roll_med_acc_x     | 5-second rolling median of a 10 Hertz version of x-axis                                                                                                        | Average           | do.roll_med_acc_x                                                           | Frequency               |
| roll_med_acc_y     | 5-second rolling median of a 10 Hertz version of y-axis                                                                                                        | Average           | do.roll_med_acc_y                                                           | Frequency               |
| roll_med_acc_z     | 5-second rolling median of a 10 Hertz version of z-axis                                                                                                        | Average           | do.roll_med_acc_z                                                           | Frequency               |
| dev_roll_med_acc_x | Absolute difference between x-axis and 5-second rolling median of a 10 Hertz version of x-axis                                                                 | Average           | do.dev_roll_med_acc_x                                                       | Frequency               |
| dev_roll_med_acc_y | Absolute difference between y-axis and 5-second rolling median of a 10 Hertz version of y-axis                                                                 | Average           | do.dev_roll_med_acc_y                                                       | Frequency               |
| dev_roll_med_acc_z | Absolute difference between z-axis and 5-second rolling median of a 10 Hertz version of z-axis                                                                 | Average           | do.dev_roll_med_acc_z                                                       | Frequency               |
| lfen               | Euclidean norm of low-pass filtered x, y and z axis                                                                                                            | Average           | do.lfen                                                                     | Not attempted           |
| hfx                | High-pass filtered x-axis                                                                                                                                      | Average           | do.hfx                                                                      | Frequency               |
| hfy                | High-pass filtered y-axis                                                                                                                                      | Average           | do.hfy                                                                      | Frequency               |
| hfz                | High-pass filtered z-axis                                                                                                                                      | Average           | do.hfz                                                                      | Frequency               |
| hfen               | Euclidean norm of high-pass filtered signals                                                                                                                   | Average           | do.hfen                                                                     | Frequency               |
| hfenplus           | Euclidean norm of low-pass filtered signals minus gravity plus Euclidean norm of the high-pass filtered signals with resulting negative values rounded to zero | Average           | do.hfenplus                                                                 | Frequency and magnitude |
| lfx                | Low-pass filtered x-axis                                                                                                                                       | Average           | do.lfx                                                                      | Not attempted           |
| lfy                | Low-pass filtered y-axis                                                                                                                                       | Average           | do.lfy                                                                      | Not attempted           |
| lfz                | Low-pass filtered z-axis                                                                                                                                       | Average           | do.lfz                                                                      | Not attempted           |
| bfx                | Band-pass filtered x-axis                                                                                                                                      | Average           | do.bfx                                                                      | Frequency               |
| bfy                | Band-pass filtered y-axis                                                                                                                                      | Average           | do.bfy                                                                      | Frequency               |
| bfen               | Euclidean norm of the band-pass filtered signals                                                                                                               | Average           | do.bfz                                                                      | Frequency               |
| zcx                | Zero crossing count x-axis                                                                                                                                     | Sum               | do.zcx                                                                      | Frequency               |
| zcy                | Zero crossing count y-axis                                                                                                                                     | Sum               | do.zcy                                                                      | Frequency               |
| zcz                | Zero crossing count z-axis                                                                                                                                     | Sum               | do.zcz                                                                      | Frequency               |
| neishabouricounts  | Counts as described by [Neishabouri et al. 2022](https://doi.org/10.1038/s41598-022-16003-x) as used in the ActiLife software for raw ActiGraph data           | Sum               | do.neishabouricounts                                                        | Frequency               |

### Approach to removing the gravitational signal component

The table above indicates the approach used to separate the gravitation component.
There are two approaches:

-   Magnitude, where the metric makes an assumption about the magnitude of the gravitational acceleration component.

-   Frequency, where the metric makes an assumption about the frequency content of the gravitational acceleration component.

Both assumptions are known to not hold true under all conditions, which is why no acceleration metric is perfect.

### Handling high frequency components in the signal

Some argue that high frequency components in the signal should be treated as noise and be removed.
However, more likely they represent the harmonics of low frequency movements and are by that part of the description of movement.
For a more elaborate reflection on this, please see [this blog post](https://www.accelting.com/updates/high-frequencies-in-an-acceleration-signal/).

All metrics that have the letter LF or BF in their name attempt to suppress the high frequency content of the signal.

### Why GGIR uses ENMO as a default.

Only one metric can be the default.
Acceleration metric ENMO (Euclidean Norm Minus One with negative values rounded to zero) has been the default metric since GGIR was created.
In 2013 we investigated different ways of summarising the raw acceleration data ([van Hees et al. PLoS ONE 2013](https://doi.org/10.1371/journal.pone.0061691)).
In short, different metrics exist and there is very little literature to support the superiority of any metric at the time.
As long as different studies use different metrics their findings will not be comparable.
Therefore, the choice for metric ENMO has been partially pragmatic.
GGIR uses ENMO as default because:

1\.
ENMO has demonstrated value in describing variance in daily energy expenditure, is correlated with questionnaire data, and able to describe patterns in physical activity.

2\.
ENMO is easy to describe mathematically and by that improves reproducibility across studies and software tools.

3\.
ENMO attempts to quantify the acceleration in universal units and does not collapse the signal to an abstract scale.

4\.
The 2013 paper showed that when ENMO is used in combination with auto-calibration it has similar validity to filter-based metrics like HFEN and BFEN, which are conceptually similar to metrics proposed later such as [MIMSunit](https://doi.org/10.1123/jmpb.2018-0068), [MAD](https://doi.org/10.1186/s13102-015-0010-0), [AI0](https://doi.org/10.1371/journal.pone.0160644).

5\.
Studies who have criticised ENMO consistently failed to apply auto-calibration, or attempted to apply auto-calibration in a lab setting, ignoring the fact that the auto-calibration is not designed for short lasting lab settings.
It needs free-living data to work properly.
Further, studies are often not clear about how the problematic zero imputation during the idle sleep mode in ActiGraph devices is dealt with.

## Embedding your own metrics

Some GGIR users may like to use a metric not covered by GGIR.
To facilitate this we allow for external function embedding as discussed in the vignette [Embedding external functions in GGIR](https://cran.r-project.org/package=GGIR/vignettes/ExternalFunction.pdf).
In fact, this allows you to include entire algorithms such as the [step detection](https://github.com/ShimmerEngineering/Verisense-Toolbox/tree/master/Verisense_step_algorithm) or a new sleep classification algorithm that you would like to test inside GGIR.

## Related output

-   In **GGIR part 2**, output is derived for each acceleration metric derived in GGIR part 1 except for metrics anglex, angley, and anglez.
-   In **GGIR part 4** output is derived from only the metrics used for the sleep detection, typically angle or count (Neishabouri counts or zero-crossing count).
-   In **GGIR part 5** output is derived for only the single metric specified with parameter `acc.metric`. The reason for this constraint is that part 5 produces many variables and creating all of them for multiple metrics would be computationally expensive and substantially increase the complexity of the underlying code.

## References

We are aware that this chapter could be made more informative if it had an even more detailed discussion on each of the metrics.
However, given that our focus is on GGIR we have a compiled a list of related articles you may find useful:

-   [Van Hees et al. 2011](https://doi.org/10.1371/journal.pone.0022922) Estimation of Daily Energy Expenditure in Pregnant and Non-Pregnant Women Using a Wrist-Worn Tri-Axial Accelerometer.

-   [van Hees et al. 2013](https://doi.org/10.1371/journal.pone.0061691) Separating Movement and Gravity Components in an Acceleration Signal and Implications for the Assessment of Human Daily Physical Activity.

-   [Migueles et al. 2019](https://doi.org/10.1038/s41598-019-54267-y) Comparability of accelerometer signal aggregation metrics across placements and dominant wrist cut points for the assessment of physical activity in adults.

-   [Aittasalo et al. 2015](https://doi.org/10.1186/s13102-015-0010-0) Mean amplitude deviation calculated from raw acceleration data: a novel method for classifying the intensity of adolescents’ physical activity irrespective of accelerometer brand.

-   [Neishabouri et al. 2022](https://doi.org/10.1038/s41598-022-16003-x) Quantification of acceleration as activity counts in ActiGraph.

-   [Karas et al. 2022](https://mhealth.jmir.org/2022/7/e38077/) Comparison of accelerometry-based measures of physical activity: retrospective observational data analysis study.

-   [van Hees 2019](https://medium.com/@vincentvanhees/ten-misunderstandings-surrounding-information-extraction-from-wearable-accelerometer-data-a4f767a865b6) Ten Misunderstandings surrounding Information Extraction from Wearable Accelerometer data.
