actiwrite

actiwrite writes epoch-level actigraphy counts to ActiGraph .agd files. It complements the Activerse workflow: use actiread to import raw accelerometer data and actimetrics to derive activity counts, then use actiwrite to make an AGD file that can be opened in compatible tools.

Installation

You can install actiwrite from GitHub with:

# install.packages("remotes")
remotes::install_github("jhuwit/actiwrite")

From raw GT3X data to an AGD file

This example reads the GT3X file bundled with actiread, calculates 60-second ActiGraph-style activity counts with actimetrics, and writes the three axes to an AGD file. Substitute the path to your own .gt3x file for acti_example_gt3x().

# Read raw triaxial acceleration data.
raw_data <- actiread::acti_read_gt3x(
  actiread::acti_example_gt3x(),
  verbose = FALSE
)

# Convert the raw signal to 60-second counts.
counts_60s <- actimetrics::acti_calculate_counts(
  raw_data,
  epoch = 60L,
  verbose = FALSE
)

# Write the timestamp and axis1--axis3 count columns to an AGD file.
agd_file <- tempfile(fileext = ".agd")
acti_write_agd(
  counts_60s,
  file = agd_file,
  epoch_length = 60L,
  original_sample_rate = attr(raw_data, "sample_rate")
)

agd_file

acti_write_agd() accepts either axis1, axis2, and axis3 columns (as created above) or X, Y, and Z columns. It infers the epoch length from timestamps when epoch_length is omitted; setting it explicitly is useful when the data contain only one epoch.

Validate the round trip

Use actigraph.sleepr::read_agd_raw() to inspect the values stored in the AGD database and actigraph.sleepr::read_agd() to read the decoded count data and timestamps. The checks below confirm that the three count axes and timestamps are unchanged after writing and reading the file.

axis_names <- paste0("axis", 1:3)
input_axes <- as.data.frame(counts_60s[axis_names])

agd_raw <- actigraph.sleepr::read_agd_raw(agd_file)
stopifnot(isTRUE(all.equal(
  agd_raw$data[axis_names], input_axes, check.attributes = FALSE
)))

agd_counts <- actigraph.sleepr::read_agd(agd_file)
stopifnot(
  isTRUE(all.equal(as.numeric(agd_counts$timestamp), as.numeric(counts_60s$time))),
  isTRUE(all.equal(
    as.data.frame(agd_counts[axis_names]), input_axes, check.attributes = FALSE
  ))
)

For a fuller walkthrough, see vignette("actiread-to-agd", package = "actiwrite").

Funding

This work was supported by NIH P30AG021334 and the Johns Hopkins Older Americans Independence Center (OAIC) Pepper Center grant.