Compute both MIMS-unit and sensor orientations with custom settings

custom_mims_unit computes the Monitor Independent Motion Summary unit and estimates the sensor orientations for the input multi-channel accelerometer signal with custom settings. The input signal can be from devices of any sampling rate and dynamic range. Please refer to the manuscript for detailed description of the algorithm. Please refer to functions for the intermediate steps: extrapolate for extrapolation, iir for filtering, aggregate_for_mims and aggregate_for_orientation for aggregation.

custom_mims_unit(
  df,
  epoch = "5 sec",
  dynamic_range,
  noise_level = 0.03,
  k = 0.05,
  spar = 0.6,
  filter_type = "butter",
  cutoffs = c(0.2, 5),
  axes = c(2, 3, 4),
  use_extrapolation = TRUE,
  use_filtering = TRUE,
  combination = "sum",
  allow_truncation = TRUE,
  output_mims_per_axis = FALSE,
  output_orientation_estimation = FALSE,
  epoch_for_orientation_estimation = NULL,
  before_df = NULL,
  after_df = NULL,
  use_gui_progress = FALSE,
  st = NULL,
  use_snapshot_to_check = FALSE
)

Arguments

df: dataframe. Input multi-channel accelerometer signal.
epoch: string. Any format that is acceptable by argument breaks in method cut.POSIXt.For example, "1 sec", "1 min", "5 sec", "10 min". Default is "5 sec".
dynamic_range: numerical vector. The dynamic ranges of the input signal. Should be a 2-element numerical vector. c(low, high), where low is the negative max value the device can reach and high is the positive max value the device can reach.
noise_level: number. The tolerable noise level in \(g\) unit, should be between 0 and 1. Default is 0.03, which applies to most devices.
k: number. Duration of neighborhood to be used in local spline regression for each side, in seconds. Default is 0.05, as optimized by MIMS-unit algorithm.
spar: number. Between 0 and 1, to control how smooth we want to fit local spline regression, 0 is linear and 1 matches all local points. Default is 0.6, as optimized by MIMS-unit algorithm.
filter_type: string. The type of filter to be applied. Could be 'butter' for butterworth bandpass filter, 'ellip' for elliptic bandpass filter or 'bessel' for bessel lowpass filter + average removal highpass filter. Default is "butter".
cutoffs: numerical vector. Cut off frequencies to be used in filtering. If filter_type is "bessel", the cut off frequency for lowpass filter would be multiplied by 2 when being used. Default is 0.2Hz and 5Hz.
axes: numerical vector. Indices of columns that specifies the axis values of the input signal. Default is c(2,3,4).
use_extrapolation: logical. If it is TRUE, the function will apply extrapolation algorithm to the input signal, otherwise it will skip extrapolation but only linearly interpolate the signal to 100Hz. Default is TRUE.
use_filtering: logical. If it is TRUE, the function will apply bandpass filtering to the input signal, otherwise it will skip the filtering. Default is TRUE.
combination: string. Method to combine MIMS-unit values for each axis. Could be "sum" for sum_up or "vm" for vector_magnitude.
allow_truncation: logical. If it is TRUE, the algorithm will truncate very small MIMS-unit values to zero. Default is TRUE.
output_mims_per_axis: logical. If it is TRUE, the output MIMS-unit dataframe will have MIMS-unit values for each axis from the third column. Default is FALSE.
output_orientation_estimation: logical. If it is TRUE, the function will also estimate sensor orientations over each epoch. And the output will be a list, with the first element being the MIMS-unit dataframe, and the second element being the sensor orientation dataframe. Default is FALSE.
epoch_for_orientation_estimation: string. string. Any format that is acceptable by argument breaks in method cut.POSIXt.For example, "1 sec", "1 min", "5 sec", "10 min". Default is "5 sec". It is independent from epoch for MIMS-unit.
before_df: dataframe. The multi-channel accelerometer signal comes before the input signal to be prepended to the input signal during computation. This is used to eliminate the edge effect during extrapolation and filtering. If it is NULL, algorithm will run directly on the input signal. Default is NULL.
after_df: dataframe. The multi-channel accelerometer signal comes after the input signal to be append to the input signal. This is used to eliminate the edge effect during extrapolation and filtering. If it is NULL, algorithm will run directly on the input signal. Default is NULL.
use_gui_progress: logical. If it is TRUE, show GUI progress bar on windows platform. Default is FALSE.
st: character or POSIXct timestamp. An optional start time you can set to force the epochs generated by referencing this start time. If it is NULL, the function will use the first timestamp in the timestamp column as start time to generate epochs. This is useful when you are processing a stream of data and want to use a common start time for segmenting data. Default is NULL.
use_snapshot_to_check: logical. If TRUE, the function will use the first 100 rows or 10 the algorithm will use all data to check timestamp duplications. Default is FALSE.

Value

dataframe or list. If output_orientation_estimation is TRUE, the output will be a list, otherwise the output will be the MIMS-unit dataframe.

The first element will be the MIMS-unit dataframe, in which the first column is the start time of each epoch in POSIXct format, and the second column is the MIMS-unit value for the input signal, and the third column and on are the MIMS-unit values for each axis of the input signal if

output_mims_per_axis is TRUE.

The second element will be the orientation dataframe, in which the first column is the start time of each epoch in POSIXct format, and the second to fourth column is the estimated orientations for the input signal.

Note

This function allows you to run customized algorithm for MIMSunit and sensor orientations.

before_df and after_df are often set when the accelerometer data are divided into files of smaller chunk.

How is it used in MIMS-unit algorithm?

This is the low-level entry of MIMS-unit and orientation estimation algorithm. mims_unit calls this function internally.

Examples

  # Use sample data for testing
  df = sample_raw_accel_data

  # compute mims unit values with custom parameter
  output = custom_mims_unit(df, epoch = '1 sec', dynamic_range=c(-8, 8), spar=0.7)
#> ================================================================================
  head(output)
#>     HEADER_TIME_STAMP MIMS_UNIT
#> 1 2016-01-15 11:00:00  1.071916
#> 2 2016-01-15 11:00:01  1.079748
#> 3 2016-01-15 11:00:02  1.001164
#> 4 2016-01-15 11:00:03  1.023815
#> 5 2016-01-15 11:00:04  1.016161
#> 6 2016-01-15 11:00:05  0.813439