Package {GGIRread}

Type:	Package
Title:	Wearable Accelerometer Data File Readers
Version:	1.2.0
Date:	2026-10-28
Maintainer:	Vincent T van Hees <v.vanhees@accelting.com>
Description:	Reads data collected from wearable acceleratometers as used in sleep and physical activity research. Currently supports file formats: binary data from 'GENEActiv' https://activinsights.com/, .bin-format from GENEA devices (not for sale), and .cwa-format from 'Axivity' https://axivity.com. Further, it has functions for reading text files with epoch level aggregates from 'Actical', 'Fitbit', 'Actiwatch', 'ActiGraph', and 'PhilipsHealthBand'. Primarily designed to complement R package GGIR https://CRAN.R-project.org/package=GGIR.
URL:	https://github.com/wadpac/GGIRread/
BugReports:	https://github.com/wadpac/GGIRread/issues
License:	Apache License (== 2.0)
Suggests:	testthat
Imports:	matlab, bitops, Rcpp (≥ 1.0.10), data.table, readxl, jsonlite, digest
Depends:	stats, utils, R (≥ 3.5.0)
NeedsCompilation:	yes
LinkingTo:	Rcpp (≥ 1.0.10)
ByteCompile:	yes
Packaged:	2026-10-28 10:32:00 UTC; vvanh
Author:	Vincent T van Hees [aut, cre], Patrick Bos [aut], Lena Kushleyeva [ctb], Jing Hua Zhao [ctb], Evgeny Mirkes [ctb], Dan Jackson [ctb], Jairo H Migueles [ctb], John Muschelli [ctb], Jia Ying Chua [ctb], Medical Research Council UK [cph, fnd], Accelting [cph, fnd]
Repository:	CRAN
Date/Publication:	2026-10-28 11:40:22 UTC

A package to read data files from wearable accelerometers

Description

This package offers a collection of functions to read data files from wearable accelerometers. Some functions were migrated from R package GGIR to make GGIR more modular and to reduce it's complexity, while other functions such as readGENEActiv (R) and GENEActivReader (C++) are newly written.

Details

Author(s)

• Vincent T van Hees <v.vanhees@accelting.com> main creator and developer

• Patrick Bos developed function GENEActivReader

• Jing Hua Zhao <jinghua.zhao@mrc-epid.cam.ac.uk> co-developed function readGenea

• Evgeny Mirkes created function readAxivity

• Dan Jackson helped improve function readAxivity

Function (C++) to read binary files as produced by the GENEActiv accelerometer

Description

Function to read binary files as produced by the GENEActiv accelerometer by ActivInsights Ltd https://activinsights.com/

Usage

  GENEActivReader(filename, start = 0L, end = 0L, progress_bar = FALSE)

Arguments

Details

If only start page is defined then all data is read beyond start until the end of the file is reached

Value

Author(s)

Patrick Bos <egpbos@gmail.com> Vincent T van Hees <v.vanhees@accelting.com>

Check timestamp format

Description

Helper function used internally. Generate informative error message if timestamp could not be recognisede.

Usage

  checkTimeFormat(timestamp_POSIX, rawValue = " ?? ", timeformat = " ?? ",
                           timeformatName = NULL)

Arguments

Value

No output value is generated, only an error message if timestamp could not be recognised.

Author(s)

Vincent T van Hees <v.vanhees@accelting.com>

Detect quote

Description

Helper function used internally, used to find out what value should be used for argument quote in function fread.

Usage

  detectQuote(filename, skip)

Arguments

Value

Character with quote object to be used for fread

Author(s)

Vincent T van Hees <v.vanhees@accelting.com>

Find start of data inside text file.

Description

Helper function used internally. Finds variables start of the data in Actiwatch and Actical data.

Usage

  findStartData(filename, quote, startindex, blockname = NULL)

Arguments

Value

Start index

Author(s)

Vincent T van Hees <v.vanhees@accelting.com>

Get File Extension

Description

Helper function used internally to get file extension.

Usage

  getExtension(filename)

Arguments

Value

Character with file extension

Author(s)

Vincent T van Hees <v.vanhees@accelting.com>

Merge Fitbit json files into one data.frame

Description

Read and merge Fitbit json files into one data.frame, and give warning if time series do not intersect.

Usage

  mergeFitbitData(filenames = NULL,
                    desiredtz = "", configtz = NULL)

Arguments

Value

Merged data from the two or more files.

Author(s)

Vincent T van Hees <v.vanhees@accelting.com>

Merge Philips Health Band xlsx file pairs into one csv file

Description

Read, merge, and save Philips Health Band xlsx file pairs to csv. If the pair is incomplete the function will still convert the available xlsx file to csv.

Usage

  mergePHBdata(filenames = NULL,
                    timeformat = "%m/%d/%Y %H:%M:%S",
                    desiredtz = "", configtz = NULL,
                    timeformatName = "timeformat")

Arguments

Value

Merged data from the two files.

Author(s)

Vincent T van Hees <v.vanhees@accelting.com>

Read ActiGraph Count data files (csv)

Description

Reads ActiGraph Count data file. Currently a variety of csv format are facilitated.

Usage

  readActiGraphCount(filename = NULL, 
                            timeformat = "%m/%d/%Y %H:%M:%S",
                            desiredtz = "", configtz = NULL,
                            timeformatName = "timeformat")

Arguments

Value

Author(s)

Vincent T van Hees <v.vanhees@accelting.com>

Read Actical Count data files (csv)

Description

Reads Actical Count data file.

Usage

  readActicalCount(filename = NULL,
                            timeformat = "%m/%d/%Y %H:%M:%S",
                            desiredtz = "", configtz = NULL,
                            timeformatName = "timeformat")

Arguments

Value

Author(s)

Vincent T van Hees <v.vanhees@accelting.com>

Read Actiwatch Count data files (csv)

Description

Reads Actiwatch Count data file. Currently a variety of csv format are facilitated.

Usage

  readActiwatchCount(filename = NULL,
                            timeformat = "%m/%d/%Y %H:%M:%S",
                            desiredtz = "", configtz = NULL,
                            timeformatName = "timeformat")

Arguments

Value

Author(s)

Vincent T van Hees <v.vanhees@accelting.com>

Function to read .cwa-format files as produced by the accelerometer named 'Axivity'

Description

For reading .cwa-format data with the Axivity AX3 and AX6 sensors.

Usage

  readAxivity(filename, start = 0, end = 0, progressBar = FALSE, 
    desiredtz = "", configtz = c(), interpolationType=1, loadbattery = FALSE,
    header = NULL, frequency_tol = 0.1, maxAllowedCorruptBlocks = 20)

Arguments

Details

Only complete 512-byte data packets are decoded. An incomplete final packet is excluded with a warning when reading the header. An error is raised when no complete data packets remain. Corrupt packets at the start or end of a requested interval are skipped up to maxAllowedCorruptBlocks; internal corruption can cause the intervening interval to be imputed.

Acceleration is interpolated using the selected method. Rejected intervals are filled with the preceding acceleration orientation normalised to 1 g when its magnitude lies between 0.8 and 1.2 g, otherwise with c(0, 0, 1). Gyroscope channels are filled with zero during imputation.

For failed-checksum rows in QClog, the packet's contents cannot be trusted: block IDs are inferred from file positions and timing and frequency fields are zero. Such rows have imputed = FALSE; a separate row records any imputation between the surrounding valid packets.

Value

• data dataframe with data from start inclusive till end exclusive. If start == end then data section of final structure is empty.

  • time numeric timestamp in seconds since the Unix epoch

  • gx gyroscope x-axis in degrees per second (AX6 with gyroscope enabled)

  • gy gyroscope y-axis in degrees per second (AX6 with gyroscope enabled)

  • gz gyroscope z-axis in degrees per second (AX6 with gyroscope enabled)

  • x accelerometer x-axis in g

  • y accelerometer y-axis in g

  • z accelerometer z-axis in g

  • temp temperature in Celsius (recorded once per block)

  • battery voltage in volts (recorded once per block), or zero when loadbattery = FALSE

  • light raw light sensor value (recorded once per block), without conversion to lux

• header file header. list of header information:

  • uniqueSerialCode is the device serial code

  • frequency is the nominal measurement frequency in Hz, including fractional rates such as 12.5 Hz. All data are resampled at this frequency

  • start is a POSIXct timestamp for the first valid data block, displayed in desiredtz

  • device is "Axivity"

  • firmwareVersion

  • blocks is the number of complete data blocks, including corrupt blocks

  • accrange is the accelerometer range in g (for example, 8 denotes +/-8 g)

  • hardwareType is "AX3" or "AX6"

  • blockLength is the sample count of the first valid data block, typically 40, 80 or 120 depending on the sensor configuration

• QClog dataframe logging failed checksums, imputed intervals and frequency deviations above 5%; NULL when there are no such events. It is omitted for header-only reads. Columns are:

  • checksum_pass Boolean to indicate whether checksum was zero.

  • blockID_current ID of the block whose interval is being checked

  • blockID_next ID of the following block

  • start numeric start time of the checked interval, in seconds since the Unix epoch

  • end numeric end time of the checked interval, in seconds since the Unix epoch

  • blockLengthSeconds duration of the interval in seconds

  • frequency_blockheader frequency derived from block header

  • frequency_observed frequency as observed

  • imputed Boolean indicating whether the interval was imputed

Author(s)

Evgeny Mirkes <em322@leicester.ac.uk> Lena Kushleyeva Vincent van Hees <v.vanhees@accelting.com>

Examples

  
    cwafile  = system.file("testfiles/ax3_testfile.cwa", package = "GGIRread")[1]
    AX3 = readAxivity(filename = cwafile, desiredtz = "Europe/Berlin", start = 1, end = 2)
  

Read Fitbit data files (json)

Description

Reads Fitbit data file (json) with sleep, steps or calories. Steps and calories are converted to 30 second resolution to match resolution of sleep data.

Usage

  readFitbit(filename = NULL, desiredtz = "", configtz = NULL)

Arguments

Value

Data.frame with data converted to time series

Author(s)

Vincent T van Hees <v.vanhees@accelting.com>

Function (R) to read binary files as produced by the GENEActiv accelerometer

Description

R function wrapper around GENEActivReader to read binary files as produced by the GENEActiv accelerometer by ActivInsights Ltd https://activinsights.com/

Usage

  readGENEActiv(filename, start = 0L, end = 0L, progress_bar = FALSE,
                desiredtz = "", configtz = NULL)

Arguments

Details

If only start page is defined then all data is read beyond start until the end of the file is reached.

GENEActiv light measurements are calibrated according to the device model. For GENEActiv 1.1, the existing light calibration is applied. For GENEActiv 1.2 and above, an additional correction is applied to account for the light sensor's non-linear scaling with graded resolution. This provides greater accuracy at low light levels while supporting a higher range. This correction was provided by ActivInsights Ltd, the manufacturer of GENEActiv devices.

Value

header:

data.out:

Author(s)

Patrick Bos <egpbos@gmail.com> Vincent T van Hees <v.vanhees@accelting.com>

Examples

  binfile  = system.file("testfiles/GENEActiv_testfile.bin", package = "GGIRread")[1]
  rdata = readGENEActiv(filename = binfile, start = 1, end = 1, desiredtz = "Europe/London")

Function to read binary files as produced by the accelerometer named 'Genea', not to be confused with the 'GENEActiv' (see package GENEAread for this)

Description

For reading the binary data as collected with a Genea accelerometer (Unilever Discover, UK). For reading GENEActive binary data, see package GENEAread.

Usage

  readGenea(filename, start = 0, end = 0)

Arguments

Details

If only start is defined then readGenea will read all data beyond start until the end of the file is reached

Value

Author(s)

Vincent T van Hees <v.vanhees@accelting.com> Jing Hua Zhao <jinghua.zhao@mrc-epid.cam.ac.uk>

Examples

  geneafile  = system.file("testfiles/genea_testfile.bin", package = "GGIRread")[1]
  GENEA = readGenea(filename = geneafile, start = 0, end = 2)

Read PHB Count data files (xlsx)

Description

Reads Philips Health Band (PHB) Count data file.

Usage

  readPHBCount(filename = NULL,
                timeformat = "%m/%d/%Y %H:%M:%S",
                desiredtz = "", configtz = NULL,
                timeformatName = "timeformat")
    

Arguments

Value

Data.frame with time series, exact column names can vary between xlsx files.

Author(s)

Vincent T van Hees <v.vanhees@accelting.com>

Read and Process Binary Data from Matrix Devices

Description

Reads a binary file generated by Parmay Tech Matrix devices, processes its header and packet data, validates data integrity using CRC32 checksums, and outputs structured sensor data and quality check information.

Usage

  readParmayMatrix(filename, output = c("all", "sf", "dynrange")[1], 
                   start = 1, end = NULL,
                   desiredtz = "", configtz = NULL, interpolationType = 1,
                   read_acc = TRUE, read_gyro = FALSE, 
                   read_temp = TRUE, read_heart = FALSE)

Arguments

Details

Matrix devices store binary data in packets, with varying lengths depending on the number of sensor recordings in each packet. The function processes the file's header to extract metadata such as the total number of packets and sensor ranges, validates data integrity using CRC32 checksums, and interpolates data to a consistent sampling frequency.

Header Information:

• Remarks: Bytes 1-512.

• Header string: Bytes 513-516. If not "MDTC", the file is considered corrupt.

• Total packets: Bytes 517-520.

• Accelerometer dynamic range: Bytes 521-522.

• Gyroscope range: Bytes 523-524.

Packet Structure:

Each packet contains accelerometer, gyroscope, temperature, and heart rate data.

• 8-byte package header.

• 4-byte CRC32 indicator.

• 4-byte start timestamp.

• 4-byte end timestamp.

• 4-byte number of accelerometer recordings in packet.

• 4-byte number of gyroscope recordings in packet.

• 4-byte number of temperature recordings in packet.

• 4-byte number of heart rate recordings in packet.

• Sensor data for accelerometer, gyroscope, temperature, and heart rate.

Value

A list containing the following elements (when output = "all"):

• QClog: A data frame with quality control information, including checksum validation and data gaps.

• output: A data frame with resampled sensor data, including:

  time

  Timestamps of the recordings.

  acc_x, acc_y, acc_z

  Resampled accelerometer data.

  gyro_x, gyro_y, gyro_z

  Resampled gyroscope data.

  bodySurface_temp, ambient_temp

  Resampled temperature data.

  hr_raw, hr

  Resampled heart rate data.

  remarks

  Remarks extracted from the file header.

• header: A list with the following elements:

  sf

  Sampling frequency of the accelerometer data.

  acc_dynrange

  Dynamic range of the accelerometer.

  starttime

  Start time of the first packet in POSIXct format.

• lastchunk: Logical, indicating if the processed data includes the last packet in the file.

If output = "sf", the function returns only the sampling frequency.

If output = "dynrange", it returns the dynamic range of the accelerometer.

Author(s)

Jairo H Migueles <jairo@jhmigueles.com>

References

For more details on Matrix devices', see: https://www.matrixwearable.net/ For additional details on Matrix BIN files structure, please contact manufacturer: https://www.matrixwearable.net/#!/contact

See Also

resample for resampling sensor data.

Examples

  ## Not run: 
  # Example usage:
  binfile  = system.file("testfiles/mtx_12.5Hz_acc.BIN", package = "GGIRread")
  # Read full data and process all packets
  result <- readParmayMatrix(binfile)
  
  # Get sampling frequency only
  sf <- readParmayMatrix(binfile, output = "sf")
  
  # Get accelerometer dynamic range
  dynrange <- readParmayMatrix(binfile, output = "dynrange")
  
  # Process a subset of packets
  result_subset <- readParmayMatrix(binfile, start = 10, end = 20)
  
## End(Not run)

Deprecated function to read .wav files as can be stored with OMGUI software by Axivity Ltd

Description

Originally designed to read the wav accelerometer data format as stored with the OMGUI software by Axivity Ltd and documented here.

This function has been deprecated as wav files are hardly used, their formatting is not consistent causing ongoing challenges, and the wav format is not well facilitated for AX6 recordings.

Usage

  readWav(filename, start = 1, end = 100,units="minutes")

Arguments

Details

If only start is defined then g.binread will read all data beyond start until the end of the file is reached

Value

Author(s)

Vincent T van Hees <v.vanhees@accelting.com>

Resample timeseries

Description

Resample single- or multi-variate time series using linear or nearest neighbour interpolation

Usage

  resample(raw, rawTime, time, stop, type = 1)	

Arguments

Examples

  raw = cbind(1:10, 1:10, 1:10)
  rawTime = seq(0.1, 1, by = 0.1)
  time = seq(0.15001, 1.05001, by = 0.1)
  stop = 10
  dat_lin = resample(raw, rawTime, time, stop, type = 1)