Type:	Package
Title:	Wearable Accelerometer Data File Readers
Version:	1.0.5
Date:	2025-05-09
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 (≥ 0.12.10), data.table, readxl, jsonlite, digest
Depends:	stats, utils, R (≥ 3.5.0)
NeedsCompilation:	yes
LinkingTo:	Rcpp
ByteCompile:	yes
Packaged:	2025-05-09 11:58:57 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], Medical Research Council UK [cph, fnd], Accelting [cph, fnd]
Repository:	CRAN
Date/Publication:	2025-05-09 14:50:13 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)

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

Value

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

  • timestamp in numeric format

  • gx gyroscope x-axis (only available in AX6)

  • gy gyroscope y-axis (only available in AX6)

  • gz gyroscope z-axis (only available in AX6)

  • x accelerometer x-axis

  • y accelerometer y-axis

  • z accelerometer z-axis

  • temperature in Celsius (only recorded once per block)

  • battery one value per block (only recorded once per block)

  • light in LUX on (only recorded once per block)

• header file header. list of header information:

  • uniqueSerialCode is unque serial code of used device

  • frequency is measurement frequency. All data will be resampled for this frequency

  • start is timestamp in numeric form. To get text representation it is enough to use as.POSIXct(start, origin = "1970-01-01", tz=desiredtz)

  • device is "Axivity"

  • firmwareVersion

  • blocks is number of datablocks with 80 or 120 raw observations in each.

• QClog dataframe with log of integrity checks on each block including:

  • checksum_pass Boolean to indicate whether checksum was zero.

  • blockID_previous ID for previous block

  • blockID_current ID for current block

  • start_previous numeric start time of previous block

  • start_current numeric start time of current block

  • blockLengthSeconds length of previous block

  • frequency_blockheader frequency derived from block header

  • frequency_observed frequency as observed

  • imputed Boolean to indicate whether this block was inputed

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

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.

• Total packets: Bytes 513-516.

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

• 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.parmaytech.com/devices/en-matrix For additional details on Matrix bin/BIN files structure, please contact manufacturer: https://www.parmaytech.com/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)