readParmayMatrix: Read and Process Binary Data from Matrix Devices

In GGIRread: Wearable Accelerometer Data File Readers

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: "all" Returns the full processed data. "sf" Returns the sampling frequency of the accelerometer data. "dynrange" Returns the dynamic range of the accelerometer.
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 NULL, which means all packets are processed.
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 NULL, which means that it uses desiredtz.
interpolationType	Integer. Specifies the type of interpolation (see resample) to use when resampling data: 1 for Linear interpolation, 2 for Nearest-neighbor interpolation.
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 <[e-mail]>

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)

GGIRread documentation built on April 12, 2025, 1:48 a.m.