Title:	Mechanical Loading Prediction Through Accelerometer Data
Version:	0.4.2
Description:	Functions to read, process and analyse accelerometer data related to mechanical loading variables. This package is developed and tested for use with raw accelerometer data from triaxial 'ActiGraph' https://theactigraph.com accelerometers.
License:	MIT + file LICENSE
URL:	https://lveras.com/impactr/
BugReports:	https://github.com/verasls/impactr/issues/
Encoding:	UTF-8
RoxygenNote:	7.3.1
Imports:	glue, lubridate, lvmisc, pillar, pracma, purrr, Rcpp, rlang (≥ 0.4.6), signal, stringr, tibble, toOrdinal, utils, vroom
Suggests:	accdata, covr, knitr, rmarkdown, testthat (≥ 3.0.0)
Config/testthat/edition:	3
LinkingTo:	Rcpp
VignetteBuilder:	knitr
Language:	en-GB
Depends:	R (≥ 2.10)
Additional_repositories:	https://lveras.com/drat/
NeedsCompilation:	yes
Packaged:	2024-02-26 19:51:03 UTC; lucasveras
Author:	Lucas Veras [aut, cre]
Maintainer:	Lucas Veras <lucasdsveras@gmail.com>
Repository:	CRAN
Date/Publication:	2024-02-26 23:50:22 UTC

Define region of interest

Description

Define the region of interest for data analysis based on the accelerometer data timestamp.

Usage

define_region(data, start_time, end_time)

Arguments

Value

An object of class impactr_data.

Examples

data <- read_acc(impactr_example("hip-raw.csv"))
define_region(
  data, start_time = "2021-04-06 15:45:00", end_time = "2021-04-06 15:46:00"
)

Delete accelerometer non-wear time

Description

Deletes all periods marked as non-wear.

Usage

delete_nonwear(data)

Arguments

Details

This is an internal function, designed to be used inside the wrapper function remove_nonwear() that integrates all steps of detection, removal and inspection of accelerometer non-wear time.

Value

The impactr_data object provided by data without the wear column and with the non-wear time removed.

See Also

detect_nonwear(), plot_nonwear(), mark_nonwear(), summarise_nonwear()

Detection of accelerometer non-wear time

Description

Implementation of the van Hees algorithm of non-wear detection.

Usage

detect_nonwear(data, window1, window2, threshold)

Arguments

Details

This is an internal function, designed to be used inside the wrapper function remove_nonwear() that integrates all steps of detection, removal and inspection of accelerometer non-wear time.

Value

A named list of length 2 (stage1 and stage2) containing the binary non-wear classification (0 is wear and 1 is non-wear) of each algorithm's stage per window2 blocks.

See Also

plot_nonwear(), mark_nonwear(), summarise_nonwear(), delete_nonwear()

Filter the acceleration signal

Description

Filter the acceleration signal using a butterworth digital filter.

Usage

filter_acc(data, order = 4, cutoff = 20, type = "lowpass")

Arguments

Details

The default values of the filter parameters are matching the filter used in the paper by Veras et al. that developed the mechanical loading prediction equations (see References).

Value

An object of class impactr_data.

References

• Veras L, Diniz-Sousa F, Boppre G, Devezas V, Santos-Sousa H, Preto J, Machado L, Vilas- Boas JP, Oliveira J, Fonseca H. Accelerometer-based prediction of skeletal mechanical loading during walking in normal weight to severely obese subjects. Osteoporosis International. 2020. 31(7):1239- 1250. doi:10.1007/s00198-020-05295-2.

Examples

data <- read_acc(impactr_example("hip-raw.csv"))
filter_acc(data)

Find peaks in a signal

Description

Find peaks in the acceleration signal.

Usage

find_peaks(data, vector, min_height = 1.3, min_dist = 0.4)

Arguments

Details

The default values of the filter parameters are matching the filter used in the paper by Veras et al. that developed the mechanical loading prediction equations (see References). When the vector parameter is set to "all", there may contain NA values in the resultant_peak_acc and/or vertical_peak_acc at the timestamps in which a peak value for that vector could not be identified.

The default values of min_height and min_dist are matching the criteria used in the paper by Veras et al. that developed the mechanical loading prediction equations (see References)

Value

An object of class impactr_peaks with the peaks magnitude stored in the columns.

References

• Veras L, Diniz-Sousa F, Boppre G, Devezas V, Santos-Sousa H, Preto J, Machado L, Vilas- Boas JP, Oliveira J, Fonseca H. Accelerometer-based prediction of skeletal mechanical loading during walking in normal weight to severely obese subjects. Osteoporosis International. 2020. 31(7):1239- 1250. doi:10.1007/s00198-020-05295-2.

Examples

data <- read_acc(impactr_example("hip-raw.csv"))
data <- use_resultant(data)
find_peaks(data, vector = "resultant")

Get path to example data

Description

impactr comes with some example ActiGraph accelerometer raw data files in its inst/extdata directory. This function make them easy to access.

Usage

impactr_example(file = NULL)

Arguments

Value

If file = NULL, it returns the file names of the example data files, else it returns the path to the example data.

Examples

impactr_example()
impactr_example("hip-raw.csv")

Import datasets from accdata package

Description

A helper function to import datasets from the accdata package.

Usage

import_dataset(data)

Arguments

Details

To import these datasets you need to install the accdata package. It can be installed by running install_accdata(). The datasets documentation can be accessed by ?accdata::`dataset_name` (e.g., ?accdata::daily_acc_3d.

Value

An object of class impactr_data.

Examples

# Ensure that {accdata} package is available before running the example.
# If it is not, run install_accdata() to install the required package.
if (requireNamespace("accdata", quietly = TRUE)) {
  data <- import_dataset("daily_acc_3d")
  data
}

Install accdata package

Description

A helper function to install the accdata package from a drat repository. The accdata package contains datasets that can be used to test the functionalities from impactr. Note that accdata is a large package (approximately 80 MB) and could take a while to download and install.

Usage

install_accdata()

Test if the object is from the impactr package

Description

Test if the object is from the impactr package

Usage

is_impactr_data(x)

is_impactr_peaks(x)

Arguments

Value

TRUE if the object inherits the class being evaluated.

Mark accelerometer non-wear time

Description

Creates a new column, named wear, in the impactr_data object provided by data indicating its classification of wear or non-wear time.

Usage

mark_nonwear(data, nonwear_stage1, nonwear_stage2, window2)

Arguments

Details

This is an internal function, designed to be used inside the wrapper function remove_nonwear() that integrates all steps of detection, removal and inspection of accelerometer non-wear time.

Value

The impactr_data object provided by data with a new column named wear with the binary wear classification (0 is non-wear and 1 is wear) per sample. Notice that this binary classification is regarding the wear time NOT non-wear.

See Also

detect_nonwear(), plot_nonwear(), summarise_nonwear(), delete_nonwear()

Constructor for impactr_data object

Description

Constructor for impactr_data object

Usage

new_impactr_data(
  x,
  filename,
  start_date_time,
  samp_freq,
  acc_placement,
  subj_body_mass,
  filter_type
)

Arguments

Value

An object of the impactr_data class.

Constructor for impactr_peaks object

Description

Constructor for impactr_peaks object

Usage

new_impactr_peaks(
  x,
  filename,
  start_date_time,
  samp_freq,
  acc_placement,
  subj_body_mass,
  filter_type,
  peaks_idx,
  curve_start,
  acc_signal
)

Arguments

Value

An object of the impactr_peaks class.

Plot the non-wear time detection

Description

Draws a plot of the resultant acceleration in epochs of window2 size marking the non-wear time detected by each stage of the non-wear detection algorithm.

Usage

plot_nonwear(data, window2, nonwear_stage1, nonwear_stage2, save_plot)

Arguments

Details

This is an internal function, designed to be used inside the wrapper function remove_nonwear() that integrates all steps of detection, removal and inspection of accelerometer non-wear time.

Value

If save_plot = FALSE it returns the plot, otherwise it saves it.

See Also

detect_nonwear(), mark_nonwear(), summarise_nonwear(), delete_nonwear()

Predict mechanical loading

Description

Predict either ground reaction force or loading rate, or both, based on accelerometer data.

Usage

predict_loading(data, outcome, vector, model)

Arguments

Value

An object of class impactr_peaks with the ground reaction force and/or loading rate peaks magnitude stored in the columns.

Examples

data <- read_acc(impactr_example("hip-raw.csv"))
data <- specify_parameters(data, acc_placement = "hip", subj_body_mass = 78)
data <- find_peaks(data, vector = "vertical")
predict_loading(
  data,
  outcome = "grf",
  vector = "vertical",
  model = "walking/running"
)

Read raw accelerometer data

Description

Reads raw accelerometer data files into an impactr_data object.

Usage

read_acc(file)

Arguments

Value

An object of class impactr_data.

Examples

read_acc(impactr_example("hip-raw.csv"))

Detect and remove accelerometer non-wear time

Description

Detects the accelerometer non-wear time based on an algorithm developed by van Hees (see Details) and remove these periods from the raw data. This function can also draw a plot to better visualize the detected non-wear periods and generate a wear time daily summary.

Usage

remove_nonwear(
  data,
  window1 = 60,
  window2 = 15,
  threshold = 2,
  min_hour_crit = 0,
  min_day_crit = 0,
  plot = FALSE,
  save_plot = FALSE,
  save_summary = FALSE
)

Arguments

Value

An object of class impactr_data and a plot if plot = TRUE and save_plot = FALSE.

The non-wear detection algorithm

The current version of this algorithm is described in a paper by van Hees et al (see References) and also in this vignette from package GGIR. Briefly, in a first stage it identifies non-wear time based on threshold values of standard deviation (0.013g) and range (0.050g) of raw acceleration from each axis. The classification is done per blocks of window2 size (default 15 minutes) based on the characteristics of a larger window1 (default 60 minutes) centred at the window2. In the second stage of the algorithm, the plausibility of wear periods in between non-wear periods is tested based on the duration and proportion of the duration relative to the surrounding non-wear periods.

Data validation

After the detection of non-wear periods through the algorithm, a data validation step is applied. For each measurement day to be considered valid, it has to present a minimum number of wear time hours determined by the min_hour_crit argument. If the number of wear time hours of a given day falls below the threshold, the whole day is considered invalid and is then removed from the subsequent analyses. The whole measurement is also classified as valid or invalid based on the number of valid days and a threshold given by min_day_crit. If the number of valid days is less than the value determined by the min_day_crit argument, the whole data is deleted and the remove_nonwear() function signals an error, stopping its execution. Nevertheless, this error does not prevent the plot to be displayed or saved, or the wear time daily summary to be saved, if the arguments are set to do so.

References

• van Hees VT, Gorzelniak L, Dean León EC, Eder M, Pias M, Taherian S, Ekelund U, Renström F, Franks PW, Horsch A, Brage S. Separating movement and gravity components in an acceleration signal and implications for the assessment of human daily physical activity. PLoS One. 2013. Apr 23. doi:10.1371/journal.pone.0061691.

Examples

# Ensure that {accdata} package is available before running the example.
# If it is not, run install_accdata() to install the required package.
if (requireNamespace("accdata", quietly = TRUE)) {
  data <- import_dataset("daily_acc_3d")
  remove_nonwear(data)
}

Specify prediction model parameters

Description

Specify the accelerometer placement used and the subject body mass. These data is needed in order to use the mechanical loading prediction models.

Usage

specify_parameters(data, acc_placement, subj_body_mass)

Arguments

Value

An object of class impactr_data with the specified parameters as attributes.

Examples

data <- read_acc(impactr_example("hip-raw.csv"))
specify_parameters(data, acc_placement = "hip", subj_body_mass = 79.2)

Summarise mechanical loading variables

Description

Creates a summary table of the selected mechanical loading variables including the number of peaks, the minimum, maximum, mean and standard deviation values of these peaks and also the number of peaks inside a given magnitude range. The summaries can be displayed by day or as a daily average.

Usage

summarise_loading(
  data,
  variable,
  vector,
  daily_average = TRUE,
  ranges_acc = NULL,
  ranges_grf = NULL,
  ranges_lr = NULL,
  save_summary = FALSE
)

Arguments

Value

A tibble (or a list of tibbles) with the requested summaries.

Examples

# Ensure that {accdata} package is available before running the example.
# If it is not, run install_accdata() to install the required package.
if (requireNamespace("accdata", quietly = TRUE)) {
  data <- import_dataset("daily_acc_3d")
  data <- remove_nonwear(data)
  data <- filter_acc(data)
  data <- find_peaks(data, vector = "vertical")
  summarise_loading(
    data,
    variable = "acc", vector = "vertical",
    ranges_acc = 1:5
  )
}

Summarise accelerometer non-wear time

Description

Validates each measurement day based on the minimum number of wear hours and validates the entire observation based on the minimum number of valid days. It updates the values of the wear column (created by mark_nonwear()) of the impactr_data object provided by data, marking as non-wear time the days considered to be invalid. It also creates a wear time daily summary that can be saved in a csv file.

Usage

summarise_nonwear(data, min_hour_crit, min_day_crit, save_summary)

Arguments

Details

This is an internal function, designed to be used inside the wrapper function remove_nonwear() that integrates all steps of detection, removal and inspection of accelerometer non-wear time.

Value

The impactr_data object provided by data with the wear column values updated based on the validations. If no data are classified as valid, it returns NULL. Also saves the summary in a csv file if save_summary is a path.

See Also

detect_nonwear(), plot_nonwear(), mark_nonwear(), delete_nonwear()

Use resultant vector

Description

Computes the acceleration resultant vector.

Usage

use_resultant(data)

Arguments

Value

An object of class impactr_data with the acc_R column containing the acceleration resultant vector.

Examples

data <- read_acc(impactr_example("hip-raw.csv"))
use_resultant(data)