forked from THLfi/read.gt3x
-
Notifications
You must be signed in to change notification settings - Fork 0
/
README.Rmd
98 lines (67 loc) · 4.12 KB
/
README.Rmd
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
---
output: github_document
---
<!-- README.md is generated from README.Rmd. Please edit that file -->
```{r, include = FALSE}
knitr::opts_chunk$set(
collapse = TRUE,
comment = "#>",
fig.path = "man/figures/README-",
out.width = "100%"
)
```
# read.gt3x
<!-- badges: start -->
[](https://github.com/THLfi/read.gt3x/actions)
[](https://CRAN.R-project.org/package=read.gt3x)
[](https://r-pkg.org/pkg/read.gt3x)
<!-- badges: end -->
The `read.gt3x` R package implements a high performance C++ parser for ActiGraph's `.gt3x` data format. Read the binary accelerometer data (.gt3x) into an R data frame in a few seconds.
## ActiGraph accelerometers
ActiGraph's wearable [accelerometer devices](https://en.wikipedia.org/wiki/Accelerometer) (e.g. GT9X Link) are used by both individuals and researchers to track movement. The devices measures [proper acceleration](https://en.wikipedia.org/wiki/Proper_acceleration) in three directions: X (right-left), Y (forward-backward), Z (up-down). The measurement unit is the gravitational unit, $g = 9.81 m / s^2$
Data from the wearable ActiGraph devices is usually extracted and analyzed via a software called *ActiLife*. When data is extracted from the wearable ActiGraph device, it is saved as a .gt3x file. A gt3x file is a zip archive with two files:
- info.txt
- log.bin
The log.bin file is a binary file which includes the raw activity samples, written to the wearable device during usage. The format of the binary file is described in detail in the [GT3X github repository](https://github.com/actigraph/GT3X-File-Format). info.txt is a simple text file with meta information related to the device.
## Motivation for the package
ActiLife software provides a "Raw to Raw" import option, which reads the activity samples from a .gt3x file and writes them to a .csv file. However, this can be slow and the csv files can be large compared to the binary .gt3x format. Also, according to ActiGraph's customer support, "A raw file exported via ActiLife is run through a proprietary band pass filter that will exclude movement considered outside of the human spectrum", which might not be desirable for a researcher.
This package makes it easier and faster to read the raw accelerometer samples into R after extracting the data from the wearable device. No modification is done to the raw data. The package implements an efficient C++ parser which reads activity samples directly from the binary log.bin file inside the .gt3x archive. This allows for
- Storing of the data in original binary format to reserve space
- Fast access to the accelerometer's measurements
- Circumvent ActiLife's filtering algorithms
## Installation
You can install the read.gt3x package from GitHub, using the `remotes` package (available in CRAN).
```r
remotes::install_github("THLfi/read.gt3x")
```
## Basic usage
The read.gt3x package includes two sample .gt3x files which can be used to demonstrate reading the data.
```{r}
library(read.gt3x)
```
First we need the path to a single gt3x file. We have one file included in the package:
```{r embedded}
gt3xfile <-
system.file(
"extdata", "TAS1H30182785_2019-09-17.gt3x",
package = "read.gt3x")
```
And you can download larger and more extensive `gt3x` files if desired:
```{r download, eval = FALSE}
gt3xfile <- gt3x_datapath(1)
```
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 with three columns: X,Y,Z.
```{r read_in}
X <- read.gt3x(gt3xfile)
head(X)
head(attributes(X)$time_index)
attributes(X)[setdiff(names(attributes(X)), c("dim", "dimnames", "time_index"))]
```
You can also convert the matrix to a data.frame with 4 columns: X,Y,Z,time
```{r make_data_frame}
df <- as.data.frame(X)
head(df)
attributes(df)[setdiff(names(attributes(df)), c("names", "row.names"))]
```
## Documentation
[Documentation](https://thlfi.github.io/read.gt3x/), hosted by GitHub pages.