custom_mims_unit {MIMSunit}

Compute both MIMS-unit and sensor orientations with custom settings

Description

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.

Usage

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.

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.

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.

See Also

Other Top level API functions: mims_unit(), sensor_orientations(), shiny_app()

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)