readParmayMatrix {GGIRread} | R Documentation |
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
filename |
Character. Path to the binary file to be read. |
output |
Character. Specifies the type of output. Options include:
|
start |
Integer. The index of the starting packet to process. Default is 1. |
end |
Integer. The index of the ending packet to process. Default is |
desiredtz |
Character. Time zone for the returned timestamps. Default is an empty string, which uses the system's default time zone. |
configtz |
Character. Time zone specified in the file's configuration. Default is |
interpolationType |
Integer. Specifies the type of interpolation
(see |
read_acc |
Logical. Indicates whether accelerometer data should be read. |
read_gyro |
Logical. Indicates whether gyroscope data should be read. |
read_temp |
Logical. Indicates whether temperature data should be read. |
read_heart |
Logical. Indicates whether heart rate data should be read. |
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)