GGIRread (version 1.0.7)

readParmayMatrix: 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)

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.

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.

Author

Jairo H Migueles <[e-mail]>

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.

• Header string: Bytes 513-516. If not "MDTC", the file is considered corrupt.

• Total packets: Bytes 517-520.

• 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.

References

For more details on Matrix devices', see: https://www.matrixwearable.net/ For additional details on Matrix bin/BIN files structure, please contact manufacturer: https://www.matrixwearable.net/#!/contact

See Also

resample for resampling sensor data.

Examples

  if (FALSE) {
  # 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)
  }