README.Rmd

---
title: "Interpreting cut-point-free accelerometer data using interpretablePA"
output: 
  github_document:
        toc: true
        toc_depth: 3
---

```{r setup, include=FALSE}
knitr::opts_chunk$set(echo = TRUE)
```

<p align="right">

<img src="inst/img/app_logo.png" align="right" width="120"/>

</p>

[![DOI](https://img.shields.io/badge/DOI-10.1101%2023.04.19.23288786-orange)](https://doi.org/10.1101/2023.04.19.23288786)

## Project description

### Target audience

`interpretablePA` was created for researchers and clinicians interested in measuring human movement using raw-acceleration accelerometers in various populations or individuals.

### Practical application

This package supports the use of cut-point-free accelerometer metrics, namely daily average acceleration (AvAcc) and intensity gradient (IG), to assess physical activity. AvAcc and IG have been shown to be a viable alternative to traditional metrics and are strongly related to various health outcomes.

### Reference populations

The package provides:

-   A Shiny application for interpreting adult data, based on reference values from a Swiss population (ages 20–89)

-   A function for interpreting children’s data, using reference values from an English youth cohort

`interpretablePA` requires data processed using the R-package GGIR in a similar manner. GGIR supports the processing of multi-day raw accelerometer data for physical activity and sleep research. See the GGIR package [vignette](https://cran.r-project.org/web/packages/GGIR/vignettes/GGIR.html) for further information.

## Installation

You can install the package from GitHub by typing the following:

```{r installation, message = FALSE, warning = FALSE, echo = TRUE, eval = FALSE}
install.packages("remotes")

remotes::install_github("FSchwendinger/interpretablePA")

```

## Applications and Usage

### 1. `interpret.pa()` – Shiny app for adult data

The main entry point is the `interpret.pa()` function, which launches a Shiny application to interactively interpret accelerometer data in adults.

Typical use:

```{r, eval = FALSE}
interpretablePA::interpret.pa()
```

### Examples

The below images will give you some insights into the package. A typical workflow could be:

1.  The user run installs and loads `interpretablePA` and runs `interpret.pa()`. This starts the application.

2.  The user decides what data format they want to enter (data of an individual, pooled means/medians of a whole study cohort that are stratified by sex or not, or data of several individuals with sample size = N) and selects the respective option under panel "*1) User data*".

3.  Assuming the user decides to enter data of one individual (see Figure 1), they would fill in all the fields, i.e. sex, age, height, body weight, average acceleration, and intensity gradient; then press "Calculate".

    **Figure 1.** One of three data entry options the user can utilize.

    ![](images/interpretablePA_1.png "Individual-level data entry option.")

4.  Panels "2) View results" (see Figure 2) and "3) Translation of results" (see Figure 3) are now accessible.

5.  The user can find out the exact percentile the individual is on compared to our reference values and download centile plots.

    **Figure 2.** Example of graphical output. Green dots are the data entered by the user.

    ![](images/interpretablePA_2.png)

6.  In panel "3) Translation of results", the user is provided with information on a) what is necessary for the individual to reach the 50th percentile or increase their physical activity by 5%, b) which changes would be needed to achieve a clinically relevant improvement in cardiorespiratory fitness, and c) how much more physical activity would need to be performed to reduce the risk of death and disease.

**Figure 3.** Example of the translation of results.

![](images/interpretablePA_3.png)

### 2. `interpret.pa.centiles()` – Batch centile interpretation

This function integrates subject demographic data with GGIR part 2 summary output,  
and predicts age- and sex-specific centiles for:

- **Average acceleration (AvAcc)**  
- **Intensity gradient (IG)**  

using internal reference datasets included in the package.

The merged data is written to the specified output path, and four high-resolution PNG plots (400 DPI) are generated:

1. AvAcc centile distribution  
2. IG centile distribution  
3. AvAcc centile vs. age  
4. IG centile vs. age  

#### How it works

Centiles are computed by comparing each participant’s AvAcc and IG values against  
reference distributions derived from large population datasets. Interpolation is  
used to estimate the centile rank for a given value at the participant’s age and sex.  

If a participant’s age is outside the valid age range for the selected reference set,  
centile values are marked accordingly and set to `NA` for plotting purposes.

#### Supported reference datasets

- **Fairclough et al. (2023)** – Children / adolescents (England, ages 5–15)  
- **Rowlands et al. (2025)** – Adults (UK Biobank, ages 40–80)  
- **Schwendinger et al. (2025)** – Adults (NHANES, ages 20–90) 

#### Key arguments

| Argument | Description |
|-----------------|-------------------------------------------------------|
| `dat_path` | Path to subject characteristics (CSV/Excel). If `NULL`, values are taken from `part2_path`. |
| `part2_path` | Path to the GGIR `part2_summary.csv` file (required). |
| `output_path` | Path to save the merged results (CSV). If `NULL`, saved next to `part2_path`. |
| `reference_set` | Reference dataset: `"fairclough"`, `"rowlands"`, or `"nhanes"`. |
| `col_id` | Column name for participant ID. |
| `col_sex` | Column name for sex. |
| `col_age` | Column name for age. |
| `sex_code_male` | Encoding used for male participants (e.g., `"0"` or `"m"`). |
| `sex_code_female` | Encoding used for female participants (e.g., `"1"` or `"f"`). |
| `col_avacc` | Column name for daily average acceleration (default: `AD_mean_ENMO_mg_0.24hr`). |
| `col_ig` | Column name for intensity gradient (default: `AD_ig_gradient_ENMO_0.24hr`). |

```{r, eval=FALSE}
interpretablePA::interpret.pa.centiles(
  part2_path = "part2_summary.csv",
  col_id = "ID",
  col_sex = "sex",
  col_age = "age",
  sex_code_male = "0",
  sex_code_female = "1",
  reference_set = "nhanes",
  col_avacc = "AD_mean_ENMO_mg_0.24hr",
  col_ig = "AD_ig_gradient_ENMO_0.24hr"
)

```

The function produces:

-   a CSV file with centile estimates, and

-   four PNG plots (centile distributions + centile vs age plots).

## References

Please cite the appropriate reference depending on which part of the package you use:

-   If you use the **Shiny application** for **adult reference values** (`interpret.pa()`), cite:

> **Schwendinger F., Wagner J., Knaier R., Infanger D., Rowlands A.V., Hinrichs T., & Schmidt-Trucksaess A. (2024).**\
> *Accelerometer Metrics: Healthy Adult Reference Values, Associations with Cardiorespiratory Fitness, and Clinical Implications.*\
> Medicine and Science in Sports and Exercise, 56(2), 170–180.\
> <https://doi.org/10.1249/MSS.0000000000003299>

-   If you use the **batch interpretation function** (`interpret.pa.centiles()`), please cite the appropriate reference depending on the selected dataset:

    -   **Children / Adolescents (ages 5–15, England):**

        > **Fairclough S.J., Rowlands A.V., del Pozo Cruz B., Crotti M., Foweather L., Graves L.E.F., Hurter L., Jones O., MacDonald M., McCann D.A., Miller C., Noonan R.J., Owen M.B., Rudd J.R., Taylor S.L., Tyler R., Boddy L.M. (2023).**\
        > *Reference values for wrist-worn accelerometer physical activity metrics in English children and adolescents.*\
        > *International Journal of Behavioral Nutrition and Physical Activity*, 20(1), 35.\
        > <https://doi.org/10.1186/s12966-023-01435-z>

    -   **Adults (ages 40–80, UK Biobank):**

        > **Rowlands A.V., Kingsnorth A.P., Hansen B.H., Fairclough S.J., Boddy L.M., Maylor B.D., Eckmann H.R., del Pozo Cruz B., Dawkins N.P., Razieh C., Khunti K., Zaccardi F., Yates T. (2025).**\
        > *Enhancing clinical and public health interpretation of accelerometer-assessed physical activity with age-referenced values based on UK Biobank data.*\
        > *Journal of Sport and Health Science*, 14, 100977.\
        > <https://doi.org/10.1016/j.jshs.2024.100977>

    -   **Adults (ages 20–90, NHANES):**

        > **Schwendinger F., Infanger D., Lichtenstein E., Hinrichs T., Knaier R., Rowlands A.V., Schmidt-Trucksäss A. (2025).**\
        > *Intensity or volume: the role of physical activity in longevity.*\
        > *European Journal of Preventive Cardiology*, 32(1), 10–19.\
        > <https://doi.org/10.1093/eurjpc/zwae295>

## Contact

If you are interested in contributing or have any queries regarding this package, feel free to reach out to:

[Fabian Schwendinger](https://dsbg.unibas.ch/de/personen/fabian-schwendinger/)

## Session info

```{r session_info, include=TRUE, echo=FALSE}
sessionInfo()
```

## License

[![License: GPL v3](https://img.shields.io/badge/License-GPL%20v3-orange.svg)](https://www.gnu.org/licenses/gpl-3.0)