See also complementary vignettes on: General introduction to GGIR, Cut-points, Day segment analyses, GGIR parameters, and Embedding external functions (pdf).
GGIR can automatically read data from the most-frequently used accelerometer brands in the field:
However, the accelerometer manufacturers are proliferating with an
increasing number of brands in the market. For such reason, GGIR
read.myacc.csv function, which is able to read
accelerometer raw triaxial data stored in csv files, independently of
the brand. This vignette provides a general introduction on how to use
GGIR to read accelerometer raw data stored in csv files.
How it works:
Internally GGIR loads csv files with accelerometer data and standardises the output format to make the data compatible with other GGIR functions. Data format standardisation includes unit of measurement, timestamp, header format, and column locations.
As for the rest of GGIR functions,
intended to be used within function
GGIR. All the arguments
read.myacc.csv can be easily recognized as they all
start by “rmc”. The GGIR function checks whether the argument
rmc.firstrow.acc is provided by the user; in such case, GGIR will derive
the reading of the data to the
read.myacc.csv function tries to read csv files
with a wide variety of formats, the key arguments to specify depend on
the characteristics of the csv file to process. Overall, if an argument
is not relevant, it should be left in default setting (e.g., if the csv
file does not contain temperature data, the arguments related to
temperature settings should be left in default values).
Below we present a summary of the available input arguments. Please
see the parameters
vignette for a more elaborate description of these input arguments.
Further, the arguments are also covered by the function documentation
rmc.file- Filename of file to be read if it is in the working directory, or full path to the file otherwise.
rmc.nrow- Number of rows to read, same as nrow argument in and nrows in . The whole file is read by default (i.e., rmc.nrow = Inf).
rmc.skip- Number of rows to skip, same as skip argument in and in .
rmc.dec- Decimal separator used for numbers, same as dec argument in and in data.table::. If not “.” (default) then usually “,”.
rmc.firstrow.acc- First row (number) of the acceleration data.
rmc.unit.acc- Character with unit of acceleration values: “g”, “mg”, or “bit”.
rmc.desiredtz- Timezone in which device was worn.
rmc.confgitz- Timezone in which device was configured.
rmc.sf- Sample rate in Hertz, if this is stored in the file header then that will be used instead.
rmc.firstrow.header- First row (number) of the header. Leave blank (default) if the file does not have a header.
rmc.header.length- If file has header, specify header length (numeric).
rmc.headername.sf- If file has a header, row name (character) under which the sample frequency can be found.
rmc.headername.sn- If file has a header, row name (character) under which the serial number can be found.
rmc.headername.recordingid- If file has a header, row name (character) under which the recording ID can be found.
rmc.header.structure- Character used to split the header name from the header value, e.g. “:” or ” “.
rmc.col.time- Scalar with column (number) in which the timestamps are stored. Leave in default setting if timestamps are not stored.
rmc.unit.time- Character with unit of timestamps: “POSIX”, “UNIXsec” (seconds since origin, see argument rmc.origin), “character”, or “ActivPAL” (exotic timestamp format only used in the ActivPAL activity monitor).
rmc.format.time- Character string giving a date-time format as used by . Only used for rmc.unit.time: character and POSIX.
rmc.origin- Origin of time when unit of time is UNIXsec, e.g. 1970-1-1.
rmc.bitrate- Numeric: If unit of acceleration is a bit then provide bit rate, e.g. 12 bit.
rmc.dynamic_range- Numeric, if unit of acceleration is a bit then provide dynamic range deviation in g from zero, e.g. +/-6g would mean this argument needs to be 6. If you give this argument a character value the code will search the file header for elements with a name equal to the character value and use the corresponding numeric value next to it as dynamic range.
rmc.unsignedbit- Boolean, if unsignedbit = TRUE means that bits are only positive numbers. If unsignedbit = FALSE then bits are both positive and negative.
rmc.col.temp- Scalar with column (number) in which the temperature is stored. Leave in default setting if no temperature is avaible. The temperature will be used by .
rmc.unit.temp- Character with unit of temperature values: (K)elvin, (C)elsius, or (F)ahrenheit.
rmc.col.wear- If external wear detection outcome is stored as part of the data then this can be used by GGIR. This argument specifies the column in which the wear detection (Boolean) is stored.
rmc.check4timegaps- Boolean to indicate whether gaps in time should be imputed with zeros.
rmc.doresample- Boolean to indicate whether to resample the data based on the available timestamps and extracted sample rate from the file header
interpolationType- Integer to indicate type of interpolation to be used when resampling time series (mainly relevant for Axivity sensors), 1=linear, 2=nearest neighbour.
This section shows an example real case in which the read.myacc.csv function can be used. The csv file to be read has the following structure:
This file contains timestamps in the column 1 (formatted as “%d/%m/%Y %H:%M:%OS”), the acceleration signals (in g’s) for the x, y, and z axis in the columns 2, 3, and 4, respectively, and temperature information in Celsius in the column 5. Also, this file has no header.
First, we test read this file using the
function in GGIR as follows.
library(GGIR) read.myacc.csv(rmc.file = "C:/mystudy/mydata/datafile.csv", rmc.nrow = Inf, rmc.skip = 0, rmc.dec = ".", rmc.firstrow.acc = 2, rmc.col.acc = 2:4, rmc.col.temp = 5, rmc.col.time=1, rmc.unit.acc = "g", rmc.unit.temp = "C", rmc.unit.time = "POSIX", rmc.format.time = "%d/%m/%Y %H:%M:%OS", rmc.desiredtz = "Europe/London", rmc.sf = 100)
rmc.firstrow.acc argument is defined within the
GGIR function, then the data will be read through
read.myacc.csv. GGIR needs the user to specify in which row
starts the accelerometer data within the csv, so this argument must be
always explicitly specified by the user. Thus, a call to the
GGIR including the rmc arguments would look as follows
(note that the
rmc.skip arguments will not be used by
these arguments are already defined by
strategy, and header arguments,
library(GGIR) GGIR( mode=c(1,2,3,4,5), datadir="C:/mystudy/mydata/datafile.csv", outputdir="D:/myresults", do.report=c(2,4,5), #===================== # read.myacc.csv arguments #===================== rmc.nrow = Inf, rmc.dec = ".", rmc.firstrow.acc = 2, rmc.col.acc = 2:4, rmc.col.temp = 5, rmc.col.time=1, rmc.unit.acc = "g", rmc.unit.temp = "C", rmc.unit.time = "POSIX", rmc.format.time = "%d/%m/%Y %H:%M:%OS", rmc.desiredtz = "Europe/London", rmc.sf = 100, rmc.noise = 0.013 )