Title: | Wearable Accelerometer Data File Readers |
---|---|
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>. |
Authors: | 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] |
Maintainer: | Vincent T van Hees <[email protected]> |
License: | Apache License (== 2.0) |
Version: | 1.0.2 |
Built: | 2024-10-26 03:30:32 UTC |
Source: | CRAN |
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.
Package: | GGIRread |
Type: | Package |
Version: | 1.0.2 |
Date: | 2024-10-25 |
License: | LGPL (>= 2.0, < 3) |
Vincent T van Hees <[email protected]> main creator and developer
Patrick Bos developed function GENEActivReader
Jing Hua Zhao <[email protected]> co-developed function readGenea
Evgeny Mirkes created function readAxivity
Dan Jackson helped improve function readAxivity
Function to read binary files as produced by the GENEActiv accelerometer by ActivInsights Ltd https://activinsights.com/
GENEActivReader(filename, start = 0L, end = 0L, progress_bar = FALSE)
GENEActivReader(filename, start = 0L, end = 0L, progress_bar = FALSE)
filename |
filename (required) |
start |
start page for reading data |
end |
end page for reading data |
progress_bar |
Boolean |
If only start
page is defined then all data is read beyond
start
until the end of the file is reached
info |
List with ReadOK (good=0 or error=1), ReadErrors (Count of pages with read errors), SampleRate (Hertz), numBlocksTotal |
time |
Numeric vector with time in miliseconds since start page |
x |
Numeric vector with x-axis acceleration in gravitational units |
y |
Numeric vector with y-axis acceleration in gravitational units |
z |
Numeric vector with z-axis acceleration in gravitational units |
temperature |
matrix with battery voltage and corresponding timestamps |
lux |
Numeric vector with lux values in Volts |
Patrick Bos <[email protected]> Vincent T van Hees <[email protected]>
Read and merge Fitbit json files into one data.frame, and give warning if time series do not intersect.
mergeFitbitData(filenames = NULL, desiredtz = "", configtz = NULL)
mergeFitbitData(filenames = NULL, desiredtz = "", configtz = NULL)
filenames |
Character vector, specifying the filenames (at least two) to be merged. |
desiredtz |
Character, timezone name where the accelerometer was worn. Timezone names are expected to be the timezone database names, e.g. Europe/London. See also: https://en.wikipedia.org/wiki/List_of_tz_database_time_zones |
configtz |
Character, timezone name where the accelerometer was configured. Leave NULL if equal to desiredtz. Timezones name are expected to be the timezone database names, e.g. Europe/London. See also: https://en.wikipedia.org/wiki/List_of_tz_database_time_zones |
Merged data from the two or more files.
Vincent T van Hees <[email protected]>
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.
mergePHBdata(filenames = NULL, timeformat = "%m/%d/%Y %H:%M:%S", desiredtz = "", configtz = NULL, timeformatName = "timeformat")
mergePHBdata(filenames = NULL, timeformat = "%m/%d/%Y %H:%M:%S", desiredtz = "", configtz = NULL, timeformatName = "timeformat")
filenames |
Character vector, specifying the two filenames to be merged. Assumption is that there is one file starting with "Datalist_" and one starting with "Sleep_Wake_". |
timeformat |
Character, timestemp format. |
desiredtz |
Character, timezone name where the accelerometer was worn. Timezone names are expected to be the timezone database names, e.g. Europe/London. See also: https://en.wikipedia.org/wiki/List_of_tz_database_time_zones |
configtz |
Character, timezone name where the accelerometer was configured. Leave NULL if equal to desiredtz. Timezones name are expected to be the timezone database names, e.g. Europe/London. See also: https://en.wikipedia.org/wiki/List_of_tz_database_time_zones |
timeformatName |
Character, name of timeformat variable to print in error message when timeformat is incorrect, of use to GGIR where argument names can differ. |
Merged data from the two files.
Vincent T van Hees <[email protected]>
Reads Actical Count data file.
readActicalCount(filename = NULL, timeformat = "%m/%d/%Y %H:%M:%S", desiredtz = "", configtz = NULL, timeformatName = "timeformat")
readActicalCount(filename = NULL, timeformat = "%m/%d/%Y %H:%M:%S", desiredtz = "", configtz = NULL, timeformatName = "timeformat")
filename |
filename (required) |
timeformat |
Character, timestemp format. |
desiredtz |
Character, timezone name where the accelerometer was worn. Timezone names are expected to be the timezone database names, e.g. Europe/London. See also: https://en.wikipedia.org/wiki/List_of_tz_database_time_zones |
configtz |
Character, timezone name where the accelerometer was configured. Leave NULL if equal to desiredtz. Timezones name are expected to be the timezone database names, e.g. Europe/London. See also: https://en.wikipedia.org/wiki/List_of_tz_database_time_zones |
timeformatName |
Character, name of timeformat variable to print in error message when timeformat is incorrect, of use to GGIR where argument names can differ. |
data |
Matrix with one or multiple columns |
epochSize |
epoch size in seconds of data |
startTime |
POSIXlt format timestamp on which recording starts |
Vincent T van Hees <[email protected]>
Reads ActiGraph Count data file. Currently a variety of csv format are facilitated.
readActiGraphCount(filename = NULL, timeformat = "%m/%d/%Y %H:%M:%S", desiredtz = "", configtz = NULL, timeformatName = "timeformat")
readActiGraphCount(filename = NULL, timeformat = "%m/%d/%Y %H:%M:%S", desiredtz = "", configtz = NULL, timeformatName = "timeformat")
filename |
filename (required) |
timeformat |
Character, timestemp format. |
desiredtz |
Character, timezone name where the accelerometer was worn. Timezone names are expected to be the timezone database names, e.g. Europe/London. See also: https://en.wikipedia.org/wiki/List_of_tz_database_time_zones |
configtz |
Character, timezone name where the accelerometer was configured. Leave NULL if equal to desiredtz. Timezones name are expected to be the timezone database names, e.g. Europe/London. See also: https://en.wikipedia.org/wiki/List_of_tz_database_time_zones |
timeformatName |
Character, name of timeformat variable to print in error message when timeformat is incorrect, of use to GGIR where argument names can differ. |
data |
Matrix with one or multiple columns |
epochSize |
epoch size in seconds of data |
startTime |
POSIXlt format timestamp on which recording starts |
deviceSerialNumber |
Device serial number if it could be extracted from the file header |
Vincent T van Hees <[email protected]>
Reads Actiwatch Count data file. Currently a variety of csv format are facilitated.
readActiwatchCount(filename = NULL, timeformat = "%m/%d/%Y %H:%M:%S", desiredtz = "", configtz = NULL, timeformatName = "timeformat")
readActiwatchCount(filename = NULL, timeformat = "%m/%d/%Y %H:%M:%S", desiredtz = "", configtz = NULL, timeformatName = "timeformat")
filename |
filename (required) |
timeformat |
Character, timestemp format. |
desiredtz |
Character, timezone name where the accelerometer was worn. Timezone names are expected to be the timezone database names, e.g. Europe/London. See also: https://en.wikipedia.org/wiki/List_of_tz_database_time_zones |
configtz |
Character, timezone name where the accelerometer was configured. Leave NULL if equal to desiredtz. Timezones name are expected to be the timezone database names, e.g. Europe/London. See also: https://en.wikipedia.org/wiki/List_of_tz_database_time_zones |
timeformatName |
Character, name of timeformat variable to print in error message when timeformat is incorrect, of use to GGIR where argument names can differ. |
data |
Matrix with one or multiple columns |
epochSize |
epoch size in seconds of data |
startTime |
POSIXlt format timestamp on which recording starts |
Vincent T van Hees <[email protected]>
For reading .cwa-format data with the Axivity AX3 and AX6 sensors.
readAxivity(filename, start = 0, end = 0, progressBar = FALSE, desiredtz = "", configtz = c(), interpolationType=1, loadbattery = FALSE, header = NULL, frequency_tol = 0.1, maxAllowedCorruptBlocks = 20)
readAxivity(filename, start = 0, end = 0, progressBar = FALSE, desiredtz = "", configtz = c(), interpolationType=1, loadbattery = FALSE, header = NULL, frequency_tol = 0.1, maxAllowedCorruptBlocks = 20)
filename |
filename (required) is name of cwa file to read |
start |
non-negative integer which is a cwa file block number. |
end |
non-negative integer which is a cwa file block number. End must be not be less than start. If end is less or equal to start, then there is no data read. |
progressBar |
Is trigger to switch on/off the text progress bar. If progressBar is TRUE then the function displays the progress bar but it works slightly slower |
desiredtz |
Desired timezone, a character with timezone database name. |
configtz |
Timezone in which the accelerometer was configured. Only use this argument if the timezone of configuration and timezone in which recording took place are different. |
interpolationType |
Integer to indicate type of interpolation to be used, 1=linear, 2=nearest neighbour. |
loadbattery |
Boolean to indicate whether battery voltage should be loaded |
header |
Header to be reused if it was extracted earlier |
frequency_tol |
Numeric value representing the tolerance for frequency bias expressed as a fraction of the expected sampling frequency. For example, 0.10 indicates that we accept the sampling frequency configured at 100 Hertz to vary between 90 and 110 Hertz. If this condition is not met the data will be imputed with a constant value and the start and end time will be logged in the QClog output object. Regardless of the setting the function will always log instances when frequency differs by more than 5%, but if this is less than frequency_tol the block will not be imputed. |
maxAllowedCorruptBlocks |
Max number of consecutive blocks with a failed checksum that we'll tolerate. |
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
Evgeny Mirkes <[email protected]> Lena Kushleyeva Vincent van Hees <[email protected]>
cwafile = system.file("testfiles/ax3_testfile.cwa", package = "GGIRread")[1] AX3 = readAxivity(filename = cwafile, desiredtz = "Europe/Berlin", start = 1, end = 2)
cwafile = system.file("testfiles/ax3_testfile.cwa", package = "GGIRread")[1] AX3 = readAxivity(filename = cwafile, desiredtz = "Europe/Berlin", start = 1, end = 2)
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.
readFitbit(filename = NULL, desiredtz = "", configtz = NULL)
readFitbit(filename = NULL, desiredtz = "", configtz = NULL)
filename |
Character, filename (required) of json file |
desiredtz |
Character, timezone name where the accelerometer was worn. Timezone names are expected to be the timezone database names, e.g. Europe/London. See also: https://en.wikipedia.org/wiki/List_of_tz_database_time_zones |
configtz |
Character, timezone name where the accelerometer was configured. Leave NULL if equal to desiredtz. Timezones name are expected to be the timezone database names, e.g. Europe/London. See also: https://en.wikipedia.org/wiki/List_of_tz_database_time_zones |
Data.frame with data converted to time series
Vincent T van Hees <[email protected]>
For reading the binary data as collected with a Genea accelerometer (Unilever Discover, UK). For reading GENEActive binary data, see package GENEAread.
readGenea(filename, start = 0, end = 0)
readGenea(filename, start = 0, end = 0)
filename |
filename (required) |
start |
start point for reading data, this can either be a timestamp in POSIXct format "year-month-day hr:min:sec" or a page number (optional) |
end |
end point for reading data, this can either be a timestamp in POSIXct format "year-month-day hr:min:sec" or a page number (optional) |
If only start
is defined then readGenea
will read all data beyond
start
until the end of the file is reached
rawxyz |
matrix with raw x, y, and, z acceleration values |
header |
file header |
timestamps1 |
timestamps for |
timestamps2 |
timestamps for |
batt.voltage |
matrix with battery voltage and corresponding timestamps |
Vincent T van Hees <[email protected]> Jing Hua Zhao <[email protected]>
geneafile = system.file("testfiles/genea_testfile.bin", package = "GGIRread")[1] GENEA = readGenea(filename = geneafile, start = 0, end = 2)
geneafile = system.file("testfiles/genea_testfile.bin", package = "GGIRread")[1] GENEA = readGenea(filename = geneafile, start = 0, end = 2)
R function wrapper around GENEActivReader to read binary files as produced by the GENEActiv accelerometer by ActivInsights Ltd https://activinsights.com/
readGENEActiv(filename, start = 0L, end = 0L, progress_bar = FALSE, desiredtz = "", configtz = NULL)
readGENEActiv(filename, start = 0L, end = 0L, progress_bar = FALSE, desiredtz = "", configtz = NULL)
filename |
filename (required) |
start |
start page for reading data |
end |
end page for reading data |
progress_bar |
Boolean |
desiredtz |
Character, timezone database name of the timezone where the accelerometer was worn. |
configtz |
Character, timezone database name of the timezone where the accelerometer was configured. Leave NULL if equal to timezone where experiment took place. |
If only start
page is defined then all data is read beyond
start
until the end of the file is reached
header:
serial_number |
Device serial number as extracted from file header |
firmware |
Firmware version |
tzone |
Time zone as extracted from file header |
ReadOK |
see GENEActivReader |
SampleRate |
matrix with battery voltage and corresponding timestamps |
ReadErrors |
matrix with battery voltage and corresponding timestamps |
numBlocksTotal |
matrix with battery voltage and corresponding timestamps |
StartTime |
Start time as extracted from file header |
data.out:
time |
Unix time in seconds with decimal places for miliseconds |
x |
see GENEActivReader |
y |
see GENEActivReader |
z |
see GENEActivReader |
light |
Ligth values express in lux units |
temperature |
Temperature in Celsius |
Patrick Bos <[email protected]> Vincent T van Hees <[email protected]>
binfile = system.file("testfiles/GENEActiv_testfile.bin", package = "GGIRread")[1] rdata = readGENEActiv(filename = binfile, start = 1, end = 1, desiredtz = "Europe/London")
binfile = system.file("testfiles/GENEActiv_testfile.bin", package = "GGIRread")[1] rdata = readGENEActiv(filename = binfile, start = 1, end = 1, desiredtz = "Europe/London")
Reads Philips Health Band (PHB) Count data file.
readPHBCount(filename = NULL, timeformat = "%m/%d/%Y %H:%M:%S", desiredtz = "", configtz = NULL, timeformatName = "timeformat")
readPHBCount(filename = NULL, timeformat = "%m/%d/%Y %H:%M:%S", desiredtz = "", configtz = NULL, timeformatName = "timeformat")
filename |
filename (required) |
timeformat |
Character, timestemp format. |
desiredtz |
Character, timezone name where the accelerometer was worn. Timezone names are expected to be the timezone database names, e.g. Europe/London. See also: https://en.wikipedia.org/wiki/List_of_tz_database_time_zones |
configtz |
Character, timezone name where the accelerometer was configured. Leave NULL if equal to desiredtz. Timezones name are expected to be the timezone database names, e.g. Europe/London. See also: https://en.wikipedia.org/wiki/List_of_tz_database_time_zones |
timeformatName |
Character, name of timeformat variable to print in error message when timeformat is incorrect, of use to GGIR where argument names can differ. |
Data.frame with time series, exact column names can vary between xlsx files.
Vincent T van Hees <[email protected]>
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.
readWav(filename, start = 1, end = 100,units="minutes")
readWav(filename, start = 1, end = 100,units="minutes")
filename |
filename (required) |
start |
start point for reading data, see also units |
end |
end point for reading data, see also units |
units |
units used for defining start and end |
If only start
is defined then g.binread
will read all data beyond
start
until the end of the file is reached
rawxyz |
matrix with raw x, y, and, z acceleration values |
header |
file header |
timestamps |
local timestamps for |
Vincent T van Hees <[email protected]>
Resample single- or multi-variate time series using linear or nearest neighbour interpolation
resample(raw, rawTime, time, stop, type = 1)
resample(raw, rawTime, time, stop, type = 1)
raw |
stop-by-3 matrix with raw values of x, y and z. |
rawTime |
vector with stop elements of raw time. |
time |
array with required time points. |
stop |
Number of rows in raw |
type |
integer to indicate type of interpolation, 1=linear, 2=nearest neighbour |
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)
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)