In catcrumpet/accelR: Accelerometer Data Analysis in R (experimental)

knitr::opts_chunk$set(echo = TRUE)

The goal of accelR is to provide a simple and easy interface to processing accelerometer data for physical activity analyses.

Currently, only Actigraph data files are supported. These data files can be *.agd or *.csv files and they must be generated by Actigraph software.

Everything is still being developed so anything can change at anytime. In fact, things are changing all the time.

Installation

Installation requires the devtools package, install it with:

install.packages("devtools")

Then install accelR:

devtools::install_github("catcrumpet/accelR")

A short and painful tutorial

Load the package.

library(accelR)

Read in accelerometer data from an ActiGraph (*.agd) file

In this case, the data was collected in Los Angeles, so the locale/timezone is set appropriately.

good_data <- read_agd("./inst/extdata/catcrumpet_data.agd", tz = "America/Los_Angeles")
good_data

The print out displays how many observations/epochs there are (r nrow(good_data)) and the counts for the three axes (axis1, axis2, and axis3). Not all ActiGraph accelerometers collect data on three axes. Also, we can see the timezone/locale (r get_timezone(good_data)) and the epoch length (r get_epochlength(good_data) seconds).

Data need to pass several checks:

1. The data is ordered by timestamp (earliest to latest).
2. Each observation is regularly spaced by a constant time period (i.e., the epoch length).
3. No observations are duplicates.
4. The data spans the entire specified data collection time period.
5. The data contains no gaps in observations.
6. The epoch length of the data must an exact divisor of multiple of 60.

For better display of the following operations, we will remove the unnecessary columns, preserving only the accelerometer counts columns.

# method 1, using base R
good_data <- good_data[, c("timestamp", "axis1", "axis2", "axis3")]

# method 2, using dplyr
good_data <- dplyr::select(good_data, timestamp, axis1, axis2, axis3)

# result
good_data

Accelerometer-based calculations

All accelerometer-based calculations or methods do not assume which column of data contains the count data to be processed. Most Actigraph accelerometers capture count data in three axes: axis1, axis2, and axis3. In order for most, if not all, of the following calculations to work, the proper axis (or magnitude column) must be provided.

Add a column for nonwear

The default approach for nonwear detection is the Troiano approach. We will use a modified Troiano approach that is more strict with no spikes. This can be done by setting the argument spike_tolerance = 0.

better_data <- add_nonwear(good_data, counts = axis1, algorithm = nonwear_troiano, spike_tolerance = 0)
better_data

The first argument is the data that is being worked on, good_data. The counts argument is the column in good_data to calculate nonwear on. In this case it is set to axis1 and is unquoted (i.e., it is axis1 and not "axis1"). The algorithm used is nonwear_troiano and is unquoted as it is a nonwear function in the accelR package. The last argument is an additional nonwear algorithm specification. In this case, spike_tolerance is set to 0 so that the algorithm looks for spans of 0s with no breaks. By default, the new column for nonwear values is named "nonwear" but this can be changed by setting the nonwear argument to some other string like nonwear = "hello".

This approach, which we (the lab I work in) refer to as the "modified Troiano" approach is so commonly used that there is a separate algorithm for it included in the package. The following should provide the same results.

better_data_alternate <- add_nonwear(good_data, counts = axis1, algorithm = nonwear_troiano_modified)
# test for equality (should be TRUE)
all(better_data$nonwear == better_data_alternate$nonwear)

The name for the new nonwear column can be customized by setting the nonwear argument.

Add a column for physical activity category

The default is to use Troiano age-based cutpoints. In this case, the person is 12 years old and the appropriate age-based cutpoints are chosen automatically. Again, note that the counts argument is the unquoted name of the column we want to categorize physical activity. By default, the new physical activity column is named "pa". This can be changed using the pa argument.

best_data <- add_pa(better_data, counts = axis1, age = 12)
best_data

Accelerometer summaries

Summarizing accelerometer data is such an important feature that it deserves its own section. The accelR package contains two functions for summarizing accelerometer data: summarise_day and summarise_window.

Note that these functions use the British/European spelling ("summarise") and not the American spelling ("summarize"). This is to somewhat follow the naming convention of dplyr functions (e.g., summarise).

Add a column data validity

Before data can be summarized, it must have a column for physical activity (generated by add_pa) and a column of logical values for whether the data is valid. For this example, we will define validity as fulfilling all of the following criteria:

1. The participant must be wearing the device (!nonwear).
2. The physical activity values must be within valid ranges (for the included Troiano cutpoints, this means pa != "ext").

These criteria are used to create a new column, valid.

# method 1, using base R
bestest_data <- best_data
bestest_data$valid <- !bestest_data$nonwear & bestest_data$pa != "ext"

# method 2, using base R
bestest_data <- best_data
bestest_data$valid <- with(bestest_data, !nonwear & pa != "ext")

# method 3, using dplyr
bestest_data <- dplyr::mutate(best_data, valid = !nonwear & pa != "ext")

# result
bestest_data

Summarize by day

The simplest summary to perform is on the day level.

day_summary <- summarise_day(bestest_data, counts = axis1, pa = pa, valid = valid)
day_summary

This summary provides total minutes for each category (*_m) of physical activity as well as an aggregate sum of activity counts by category (*_c) of physical activity.

Summarize by time window

Summarizing around a given time is more advanced but is useful when trying to integrate accelerometer data with data from ecological momentary assessment (EMA) studies. Data in EMA studies is typically organized around a timestamp for when a survey is administered. Summarizing accelerometer data in a specified window around this timestamp can provide a metric of activity that occurred around the time at survey.

The summarise_window uses two parameters to determine the window:

1. An anchor time, which acts as the zero point (position 0).
2. One or two numeric values to signify the relative window position (more details following).

The window values can take one or two positive or negative numeric values. If one value is provided, then the window assumes that one of the boundaries is the zero point. The following shows different window parameters using different input values (input_value).

suppressPackageStartupMessages(require(dplyr))
tibble(input_value = c(-30, -20, -10, 10, 20, 30)) %>%
  dplyr::mutate(window = purrr::map(input_value, accelR:::convert_window_)) %>%
  tidyr::unnest(window)

Using two values allow specification of both left and right window positions.

tibble(input_value = list(c(-10, 10),  c(-20, 20), c(-30, 30), c(-60, -30), c(30, 60))) %>%
  dplyr::mutate(window = purrr::map(input_value, accelR:::convert_window_)) %>%
  tidyr::unnest(window) %>%
  dplyr::mutate(input_value = purrr::map_chr(input_value, ~capture.output(dput(.x))))

Typically many timestamps are processed, so the summarise_window function can process multiple anchor times and windows at once. The same set of windows is reused for each anchor time.

# anchor time will use lubridate to convert a timestamp string to a datetime object
anchor_timestamps <- 
  lubridate::ymd_hms(c("2017-11-30 10:00:00", 
                       "2017-11-30 13:00:00"),
                     tz = "America/Los_Angeles")

windows_boundaries <- list(-30, -10, 10, 30, c(-15, 15), c(30, 60))

summarise_window(bestest_data, 
                 anchor_times = anchor_timestamps, 
                 windows = windows_boundaries,
                 counts = axis1, 
                 pa = pa, 
                 valid = valid)

catcrumpet/accelR documentation built on June 28, 2020, 11:48 p.m.