GENEAread-package: A package to process binary accelerometer output files.
In GENEAread: Package for Reading Binary Files
Description
Usage
Arguments
Details
Main tasks performed
Classes implemented
WARNING
Author(s)
Examples
Description
This is a package to process binary output files from the GENEA accelerometer data.
The main functions are:
read.bin
stft
epoch
A function to process binary accelerometer files and convert the information into R objects.
Usage
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
Arguments
binfile
A filename of a file to process.
outfile
An optional filename specifying where to save the processed data object.
start
Either: A representation of when in the file to begin processing, see Details.
end
Either: A representation of when in the file to end processing, see Details.
Use.Timestamps
To use timestamps as the start and end time values this has to be set to TRUE. (Default FALSE)
verbose
A boolean variable indicating whether some information should be printed during
processing should be printed.
do.temp
A boolean variable indicating whether the temperature signal should be extracted
do.volt
A boolean variable indicating whether the voltage signal should be extracted.
calibrate
A boolean variable indicating whether the raw accelerometer values and the light
variable should be calibrated according to the calibration data in the headers.
downsample
A variable indicating the type of downsampling to apply to the data as it is loaded.
Can take values:
NULL: (Default) No downsampling
Single numeric: Reads every downsample-th value, starting from the first.
Length two numeric vector: Reads every downsample[1]-th value, starting from
the downsample[2]-th.
Non-integer, or non-divisor of 300 downsampling factors are allowed, but will
lead to imprecise frequency calculations, leap seconds being introduced, and
generally potential problems with other methods. Use with care.
blocksize
Integer value giving maximum number of data pages to read in each pass. Defaults
to 10000 for larger data files. Sufficiently small sizes will split very
large data files to read chunk by chunk, reducing memory requirements for the
read.bin function (without affecting the final object), but conversely possibly
increasing processing time. Can be set to Inf for no splitting.
virtual
logical. If set TRUE, do not do any actual data reading. Instead construct a VirtualAccData
object containing header information to allow use with get.intervals
mmap.load
Default is (.Machine$sizeof.pointer >= 8). see mmap for more details
pagerefs
A variable that can take two forms, and is considered only for mmap.load = TRUE
NULL or FALSE, in which case pagerefs are dynamically calculated for each record. (Default)
A vector giving sorted byte offsets for each record for mmap reading of data files.
TRUE, in which case a full page reference table is computed before any processing occurs.
Computing pagerefs takes a little time and so is a little slower.
However, it is safer than dynamic computations in the case of missing pages and high temperature variations.
Further, once page references are calculated, future reads are much faster, so long as the previously
computed references are supplied.
...
Any other optional arguments can be supplied that affect manual calibration and data processing.
These are:
mmap: logical. If TRUE (Default on 64bit R), use the mmap package to process the binfile
gain: a vector of 3 values for manual gain calibration of the raw (x,y,z) axes. If gain=NULL, the
gain calibration values are taken from within the output file itself.
offset: a vector of 3 value for manual offset calibration of the raw (x,y,z) axes. If offset=NULL,
the offset calibration values are taken from within the output file itself.
luxv: a value for manual lux calibration of the light meter. If luxv=NULL, the lux calibration value
is taken from within the output file itself.
voltv: a value for manual volts calibration of the light meter. If voltv=NULL, the volts calibration
value is taken from within the output file itself.
warn: if set to true, give a warning if input file is large, and require user confirmation.
Details
The main tasks performed by the package are listed below.
The relevant topic contains documentation and examples for each.
Extraction of file header material is accomplished by header.info.
Input and downsampling of data is accomplished by read.bin.
Selection of time intervals is accomplished via get.intervals.
Computation of epochal summaries is accomplished by epoch and other functions documented therein.
Computation of STFT analyses is accomplished by stft.
The package provides definitions and methods for the following S3 classes:
GRtime: Provides numeric storage and streamlined plotting for times. GRtime
AccData: Stores GENEA accelerometer data, allowing plotting, subsetting and other computation.AccData
VirtAccData: A virtual AccData object, for just-in-time data access via get.intervals.
stft: Processed STFT outputs, for plotting via plot.stft.
The read.bin package reads in binary files compatible with the GeneActiv line of Accelerometers,
for further processing by the other functions in this package. Most of the default options are those
required in the most common cases, though users are advised to consider setting start and end to
smaller intervals and/or choosing some level of downsampling when working with data files of
longer than 24 hours in length.
The function reads in the desired analysis time window specified by start and end. For convenience,
a variety of time window formats are accepted:
Large integers are read as page numbers in the dataset. Page numbers larger than that which is
available in the file itself are constrained to what is available. Note that the first page is page 1.
Small values (between 0 and 1) are taken as proportions of the data. For example, ‘start = 0.5‘
would specify that reading should begin at the midpoint of the data.
Strings are interpreted as dates and times using parse.time. In particular, times specified as
"HH:MM" or "HH:MM:SS" are taken as the earliest time interval containing these times in the
file. Strings with an integer prepended, using a space seperator, as interpreted as that time after
the appropriate number of midnights have passed - in other words, the appropriate time of day on
the Nth full day. Days of the week and dates in "day/month", "day/month/year", "month-day",
"year-month-day" are also handled. Note that the time is interpreted in the same time zone as the
data recording itself.
Actual data reading proceeds by two methods, depending on whether mmap is true or false. With
mmap = FALSE, data is read in line by line using readLine until blocksize is filled, and then
processed. With mmap = TRUE, the mmap package is used to map the entire data file into an address
file, byte locations are calculated (depending on the setting of pagerefs), blocksize chunks of
data are loaded, and then processed as raw vectors.
There are advantages and disadvantages to both methods: the mmap method is usually much faster,
especially when we are only loading the final parts of the data. readLines will have to
process the entire file in such a case. On the other hand, mmap requires a large amount of memory address
space, and so can fail in 32 bit systems. Finally, reading of compressed bin files can only be done
with the readLine method. Generally, if mmap reading fails, the function will attempt to catch the
failure, and reprocess the file with the readLine method, giving a warning. Once data is loaded,
calibration is then either performed using values from the binary file, or using
manually inputted values (using the gain, offset,luxv and voltv arguments).
Main tasks performed
NA
Classes implemented
NA
WARNING
Reading in an entire .bin file will take a long time if the file contains a lot of datasets.
Reading in such files without downsampling can use up all available memory. See memory.limit.
This function is specific to header structure in GENEActiv output files.
By design, it should be compatible with all firmware and software versions to date
(as of version of current release).
If order or field names are changed in future .bin files, this function may have to be updated appropriately.
Author(s)
Zhou Fang <zhou@activinsights.co.uk>
Activinsights Ltd. <joss.langford@activinsights.co.uk>
Charles Sweetland <charles@sweetland-solutions.co.uk>
Examples
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
requireNamespace("GENEAread")
binfile = system.file("binfile/TESTfile.bin", package = "GENEAread")[1]
#Read in the entire file, calibrated
procfile <- read.bin(binfile)
# print(procfile)
# procfile$data.out[1:5,]
# Uncalibrated, mmap off
procfile2 <- read.bin(binfile, calibrate = FALSE)
# procfile2$data.out[1:5,]
#Read in again, reusing already computed mmap pagerefs
# procfile3 <- read.bin(binfile, pagerefs = procfile2$pagerefs )
#Downsample by a factor of 10
procfilelo<-read.bin(binfile, downsample = 10)
# print(procfilelo)
object.size(procfilelo) / object.size(procfile)
#Read in a 1 minute interval
procfileshort <- read.bin(binfile, start = "16:50", end = "16:51")
# print(procfileshort)
##NOT RUN: Read, and save as a R workspace
#read.bin(binfile, outfile = "tmp.Rdata")
#print(load("tmp.Rdata"))
#print(processedfile)
Example output
Loading required package: bitops
Loading required package: mmap
Number of pages in binary file: 104
Calculated page references...
Processing...
================================================================================
Processing took: 0.133 secs .
Loaded 31200 records (Approx 2 MB of RAM)
12-05-23 16:47:50.000 (Wed) to 12-05-23 16:53:01.990 (Wed)
Warning message:
In FUN(newX[, i], ...) : NAs introduced by coercion
Number of pages in binary file: 104
Calculated page references...
Processing...
================================================================================
Processing took: 0.072 secs .
Loaded 31200 records (Approx 2 MB of RAM)
12-05-23 16:47:50.000 (Wed) to 12-05-23 16:53:01.990 (Wed)
Warning message:
In FUN(newX[, i], ...) : NAs introduced by coercion
Downsampling to 10 Hz
Number of pages in binary file: 104
Calculated page references...
Processing...
================================================================================
Processing took: 0.033 secs .
Loaded 3120 records (Approx 0 MB of RAM)
12-05-23 16:47:50.000 (Wed) to 12-05-23 16:53:01.900 (Wed)
Warning message:
In FUN(newX[, i], ...) : NAs introduced by coercion
0.1 bytes
Number of pages in binary file: 104
Calculated page references...
Processing...
================================================================================
Processing took: 0.007 secs .
Loaded 6600 records (Approx 0 MB of RAM)
12-05-23 16:49:59.000 (Wed) to 12-05-23 16:51:04.990 (Wed)
GENEAread documentation built on Nov. 26, 2020, 1:08 a.m.
R Package Documentation
Browse R Packages
We want your feedback!
Note that we can't provide technical support on individual packages. You should contact the package authors for that.
Description Usage Arguments Details Main tasks performed Classes implemented WARNING Author(s) Examples
Description
This is a package to process binary output files from the GENEA accelerometer data.
The main functions are:
read.bin
stft
epoch
A function to process binary accelerometer files and convert the information into R objects.
Usage
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 |
Arguments
binfile |
A filename of a file to process. |
outfile |
An optional filename specifying where to save the processed data object. |
start |
Either: A representation of when in the file to begin processing, see Details. |
end |
Either: A representation of when in the file to end processing, see Details. |
Use.Timestamps |
To use timestamps as the start and end time values this has to be set to TRUE. (Default FALSE) |
verbose |
A boolean variable indicating whether some information should be printed during processing should be printed. |
do.temp |
A boolean variable indicating whether the temperature signal should be extracted |
do.volt |
A boolean variable indicating whether the voltage signal should be extracted. |
calibrate |
A boolean variable indicating whether the raw accelerometer values and the light variable should be calibrated according to the calibration data in the headers. |
downsample |
A variable indicating the type of downsampling to apply to the data as it is loaded. Can take values: NULL: (Default) No downsampling Single numeric: Reads every downsample-th value, starting from the first. Length two numeric vector: Reads every downsample[1]-th value, starting from the downsample[2]-th. Non-integer, or non-divisor of 300 downsampling factors are allowed, but will lead to imprecise frequency calculations, leap seconds being introduced, and generally potential problems with other methods. Use with care. |
blocksize |
Integer value giving maximum number of data pages to read in each pass. Defaults to 10000 for larger data files. Sufficiently small sizes will split very large data files to read chunk by chunk, reducing memory requirements for the read.bin function (without affecting the final object), but conversely possibly increasing processing time. Can be set to Inf for no splitting. |
virtual |
logical. If set TRUE, do not do any actual data reading. Instead construct a VirtualAccData object containing header information to allow use with get.intervals |
mmap.load |
Default is (.Machine$sizeof.pointer >= 8). see |
pagerefs |
A variable that can take two forms, and is considered only for Computing pagerefs takes a little time and so is a little slower. However, it is safer than dynamic computations in the case of missing pages and high temperature variations. Further, once page references are calculated, future reads are much faster, so long as the previously computed references are supplied. |
... |
Any other optional arguments can be supplied that affect manual calibration and data processing. These are:
|
Details
The main tasks performed by the package are listed below. The relevant topic contains documentation and examples for each.
Extraction of file header material is accomplished by
header.info.Input and downsampling of data is accomplished by
read.bin.Selection of time intervals is accomplished via
get.intervals.Computation of epochal summaries is accomplished by
epochand other functions documented therein.Computation of STFT analyses is accomplished by
stft.
The package provides definitions and methods for the following S3 classes:
GRtime: Provides numeric storage and streamlined plotting for times.
GRtimeAccData: Stores GENEA accelerometer data, allowing plotting, subsetting and other computation.
AccDataVirtAccData: A virtual AccData object, for just-in-time data access via
get.intervals.stft: Processed STFT outputs, for plotting via
plot.stft.
The read.bin package reads in binary files compatible with the GeneActiv line of Accelerometers, for further processing by the other functions in this package. Most of the default options are those required in the most common cases, though users are advised to consider setting start and end to smaller intervals and/or choosing some level of downsampling when working with data files of longer than 24 hours in length.
The function reads in the desired analysis time window specified by start and end. For convenience, a variety of time window formats are accepted:
Large integers are read as page numbers in the dataset. Page numbers larger than that which is available in the file itself are constrained to what is available. Note that the first page is page 1. Small values (between 0 and 1) are taken as proportions of the data. For example, ‘start = 0.5‘ would specify that reading should begin at the midpoint of the data. Strings are interpreted as dates and times using parse.time. In particular, times specified as "HH:MM" or "HH:MM:SS" are taken as the earliest time interval containing these times in the file. Strings with an integer prepended, using a space seperator, as interpreted as that time after the appropriate number of midnights have passed - in other words, the appropriate time of day on the Nth full day. Days of the week and dates in "day/month", "day/month/year", "month-day", "year-month-day" are also handled. Note that the time is interpreted in the same time zone as the data recording itself.
Actual data reading proceeds by two methods, depending on whether mmap is true or false. With mmap = FALSE, data is read in line by line using readLine until blocksize is filled, and then processed. With mmap = TRUE, the mmap package is used to map the entire data file into an address file, byte locations are calculated (depending on the setting of pagerefs), blocksize chunks of data are loaded, and then processed as raw vectors.
There are advantages and disadvantages to both methods: the mmap method is usually much faster,
especially when we are only loading the final parts of the data. readLines will have to
process the entire file in such a case. On the other hand, mmap requires a large amount of memory address
space, and so can fail in 32 bit systems. Finally, reading of compressed bin files can only be done
with the readLine method. Generally, if mmap reading fails, the function will attempt to catch the
failure, and reprocess the file with the readLine method, giving a warning. Once data is loaded,
calibration is then either performed using values from the binary file, or using
manually inputted values (using the gain, offset,luxv and voltv arguments).
Main tasks performed
NA
Classes implemented
NA
WARNING
Reading in an entire .bin file will take a long time if the file contains a lot of datasets. Reading in such files without downsampling can use up all available memory. See memory.limit. This function is specific to header structure in GENEActiv output files. By design, it should be compatible with all firmware and software versions to date (as of version of current release). If order or field names are changed in future .bin files, this function may have to be updated appropriately.
Author(s)
Zhou Fang <zhou@activinsights.co.uk>
Activinsights Ltd. <joss.langford@activinsights.co.uk>
Charles Sweetland <charles@sweetland-solutions.co.uk>
Examples
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 | requireNamespace("GENEAread")
binfile = system.file("binfile/TESTfile.bin", package = "GENEAread")[1]
#Read in the entire file, calibrated
procfile <- read.bin(binfile)
# print(procfile)
# procfile$data.out[1:5,]
# Uncalibrated, mmap off
procfile2 <- read.bin(binfile, calibrate = FALSE)
# procfile2$data.out[1:5,]
#Read in again, reusing already computed mmap pagerefs
# procfile3 <- read.bin(binfile, pagerefs = procfile2$pagerefs )
#Downsample by a factor of 10
procfilelo<-read.bin(binfile, downsample = 10)
# print(procfilelo)
object.size(procfilelo) / object.size(procfile)
#Read in a 1 minute interval
procfileshort <- read.bin(binfile, start = "16:50", end = "16:51")
# print(procfileshort)
##NOT RUN: Read, and save as a R workspace
#read.bin(binfile, outfile = "tmp.Rdata")
#print(load("tmp.Rdata"))
#print(processedfile)
|
Example output
Loading required package: bitops
Loading required package: mmap
Number of pages in binary file: 104
Calculated page references...
Processing...
================================================================================
Processing took: 0.133 secs .
Loaded 31200 records (Approx 2 MB of RAM)
12-05-23 16:47:50.000 (Wed) to 12-05-23 16:53:01.990 (Wed)
Warning message:
In FUN(newX[, i], ...) : NAs introduced by coercion
Number of pages in binary file: 104
Calculated page references...
Processing...
================================================================================
Processing took: 0.072 secs .
Loaded 31200 records (Approx 2 MB of RAM)
12-05-23 16:47:50.000 (Wed) to 12-05-23 16:53:01.990 (Wed)
Warning message:
In FUN(newX[, i], ...) : NAs introduced by coercion
Downsampling to 10 Hz
Number of pages in binary file: 104
Calculated page references...
Processing...
================================================================================
Processing took: 0.033 secs .
Loaded 3120 records (Approx 0 MB of RAM)
12-05-23 16:47:50.000 (Wed) to 12-05-23 16:53:01.900 (Wed)
Warning message:
In FUN(newX[, i], ...) : NAs introduced by coercion
0.1 bytes
Number of pages in binary file: 104
Calculated page references...
Processing...
================================================================================
Processing took: 0.007 secs .
Loaded 6600 records (Approx 0 MB of RAM)
12-05-23 16:49:59.000 (Wed) to 12-05-23 16:51:04.990 (Wed)
R Package Documentation
Browse R Packages
We want your feedback!
Note that we can't provide technical support on individual packages. You should contact the package authors for that.
Embedding an R snippet on your website
Add the following code to your website.
For more information on customizing the embed code, read Embedding Snippets.