Getting started with read.gt3x
In read.gt3x: Parse 'ActiGraph' 'GT3X'/'GT3X+' 'Accelerometer' Data

knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>"
)

This document describes how the read.gt3x package can be used to read binary activity data into R. To access the read.gt3x package, use:

library(read.gt3x)

For source code and installation instructions, see the GitHub page.

Reading .gt3x data into R

The read.gt3x package includes two sample .gt3x files which I'll use to demonstrate reading the data. First we need the path to a single gt3x file. We will use data embedded in the package:

gt3xfile <-
  system.file(
    "extdata", "TAS1H30182785_2019-09-17.gt3x",
    package = "read.gt3x")

but longer and more extensive data can be downloaded via gt3x_datapath:

gt3xfile <- gt3x_datapath(1)

Method 1: Temporary unzip and read

The read.gt3x() function can take as input a path to a single .gt3x file and will then read activity samples as an R matrix.

X <- read.gt3x(gt3xfile)

head(X)

rm(X); gc(); gc()

Method 2: permanent unzip, then read

.gt3x files are actually zip archives which contain two files: log.bin and info.txt. log.bin is a binary file that contains the actual samples. It might make sense to store the data as unzipped folders containing these two files, because otherwise the read.gt3x() function will have to unzip each .gt3x archive to a temporary location, every time you need to access the data.

read.gt3x() also accepts paths to unzipped gt3x folders. To demonstrate the usage, we'll unzip the sample .gt3x files in the package, and then read them. The unzip.gt3x() helper function unzips all .gt3x files in a given directory. By default, the contents of a .gt3x file named "subject001.gt3x" are extracted to a folder named "subject001". unzip.gt3x() returns a vector of paths to the unzipped gt3x folders. The location argument can be used to choose where to locate those folders.

datadir <- dirname(gt3xfile) # location of .gt3x files
gt3xfolders <- unzip.gt3x(datadir, location = tempdir())

The read.gt3x() function accepts a path to an unzipped gt3x folder. It is a bit faster if the unzip step has already been performed.

gt3xfolder <- gt3xfolders[1]
X <- read.gt3x(gt3xfolder)

head(X)

Activity data matrix

Internally, the data matrix returned by read.gt3x() is a bit smarter than it looks, as it knows all the (relative) timestamps of the observations.

str(X)

time_index: Time passed since start
start_time: timestamp of first sample
sample_rate: Samples per second.

Converting to a data.frame

the read.gt3x package has an as.data.frame method for the activity matrix, which converts the matrix to a dataframe and adds a "time" column, which gives the timestamp of each sample. The timestamps are stored in R with the GMT timezone but note that this is misleading: in reality the timestamps correspond to the local time of the device!