Package {actimetrics}

Type:	Package
Title:	Create Metrics Actigraphy and Activity Analysis
Version:	0.9.0
Description:	Provides functions for calibrating, counting, and summarizing actigraphy and activity data into specific metrics and sleep measures. The metrics include activity counts, step counts, activity index, Monitor Independent Movement Summary Unit (MIMS), mean amplitude deviation (MAD), and provides wrappers for sleep estimation from activity counts using Tudor-Locke (2014) <doi:10.1139/apnm-2013-0173> and Sadeh (1994) <doi:10.1093/sleep/17.3.201>.
License:	GPL-3
Depends:	R (≥ 4.1.0)
Suggests:	testthat, utils, covr, knitr, httr, rmarkdown, MIMSunit, data.table, reticulate, stepcount (≥ 0.6.0), agcounts (≥ 0.6.7), callr
Encoding:	UTF-8
VignetteBuilder:	knitr
Imports:	actibase, actiread, actigraph.sleepr (≥ 0.3.1), dplyr, lubridate, assertthat, purrr, readr, tibble, rlang, stats, tidyr, walking (≥ 0.8.0), methods
LazyData:	true
Config/roxygen2/version:	8.0.0
URL:	https://jhuwit.github.io/actimetrics/
BugReports:	https://github.com/jhuwit/actimetrics/issues
NeedsCompilation:	no
Packaged:	2026-10-20 15:45:28 UTC; johnmuschelli
Author:	John Muschelli [aut, cre]
Maintainer:	John Muschelli <muschellij2@gmail.com>
Repository:	CRAN
Date/Publication:	2026-10-20 16:00:02 UTC

Apply Tudor–Locke sleep period detection

Description

Delegates to actigraph.sleepr::apply_tudor_locke(). Input must be 60-second epoch data with activity counts and a sleep state. Data from acti_apply_cole_kripke() is accepted directly. Data labeled by acti_apply_tudor_locke_diary() is also accepted: its logical sleep column is converted to the S/W states expected downstream.

Usage

acti_apply_tudor_locke(data, ..., sleep_col = "sleep")

Arguments

Value

A data frame summarizing detected sleep periods.

Apply a sleep diary to epoch data for Tudor–Locke

Description

Adds a logical sleep column to epoch data from diary onset and wakeup times. The result can be passed to acti_apply_tudor_locke() when it also has activity counts and represents 60-second epochs. The wrapper converts the logical diary labels to the S/W states required downstream.

Usage

acti_apply_tudor_locke_diary(
  data,
  sleep_diary,
  time_col = "time",
  diary_onset_col = "onset",
  diary_wakeup_col = "wakeup",
  sleep_col = "sleep"
)

Arguments

Value

data with a logical sleep_col, TRUE from onset (inclusive) to wakeup (exclusive).

Calculate the Activity Index (AI)

Description

Computes the Activity Index of Bai et al. (2016) from raw tri-axial accelerometry. For each 1-second window t, with \sigma^2_m(t) the variance of axis m \in \{X, Y, Z\} over the samples in that second,

AI(t) = \sqrt{\frac{1}{3}\sum_{m} \sigma^2_m(t)}.

The per-second values are then summed within each unit (e.g. a minute).

Usage

acti_calculate_ai(
  data,
  unit = "1 min",
  ensure_all_time = TRUE,
  verbose = FALSE
)

acti_calculate_activity_index(
  data,
  unit = "1 min",
  ensure_all_time = TRUE,
  verbose = FALSE
)

Arguments

Details

This is the unadjusted index (sometimes written AI_0): it does not subtract or normalise by the device's systematic noise variance \bar{\sigma}^2_m, which the original definition estimates from a stationary period. It differs from AI_DEFINED returned by acti_calculate_mad(), which takes the variances over the whole unit rather than summing 1-second values.

A 1-second variance needs at least two samples, so seconds with fewer than two samples are NA and are skipped when summing; a unit with no valid seconds is NA. Data sampled at under 2 Hz therefore give all-NA AI (with a warning).

Value

A data.frame (or data.table if data is one) with columns HEADER_TIME_STAMP and AI.

References

Bai J, Di C, Xiao L, et al. (2016). An Activity Index for Raw Accelerometry Data and Its Comparison with Other Activity Metrics. PLoS ONE 11(8): e0160644. doi:10.1371/journal.pone.0160644

Examples

file = actiread::acti_example_gt3x()
res = actiread::acti_read_gt3x(file, verbose = FALSE)
ai = acti_calculate_ai(res[1:12000, ])

Process Count Data

Description

Process Count Data

Process Count Data

Usage

acti_calculate_counts(
  data,
  epoch = 60L,
  resample = TRUE,
  lfe_select = FALSE,
  verbose = TRUE,
  fix_first_second = TRUE,
  round_digits = NULL
)

acti_calculate_wear(
  data,
  method = c("choi", "troiano"),
  use_magnitude = TRUE,
  ...
)

acti_calculate_nonwear(
  data,
  method = c("choi", "troiano"),
  use_magnitude = TRUE,
  ...
)

acti_apply_cole_kripke(data)

acti_apply_sadeh(data, ...)

Arguments

Details

The sampling frequency is only needed when resample = FALSE; it is taken from the sample_rate attribute (or estimated from time).

acti_calculate_wear(), acti_apply_cole_kripke(), and acti_apply_sadeh() require 60-second epochs. Cole–Kripke, Sadeh, and acti_calculate_wear(use_magnitude = FALSE) score the vertical axis, so data must contain axis1; vector-magnitude-only counts are an error.

Value

A data.frame of transformed data

A data.frame of transformed data with columns axis1-3, counts, and counts_log10.

A data.frame of transformed data

Note

This calls the downstream wear-processing helpers used by actigraph.sleepr

Examples

path = actiread::acti_example_gt3x()
ac = actiread::acti_read_gt3x(path)
out = acti_calculate_counts(ac)

data = actimetrics::acti_count_data
wear = actimetrics::acti_calculate_wear(data)
tro_wear = actimetrics::acti_calculate_wear(data, method = "troiano")
ck = actimetrics::acti_apply_cole_kripke(data)
tl = actimetrics::acti_apply_tudor_locke(ck)
sadeh = actimetrics::acti_apply_sadeh(ck)

Calculate Step Counts via Oak/Forest

Description

Calculate Step Counts via Oak/Forest

Usage

acti_calculate_forest(data, ...)

Arguments

Value

A tibble with minute-level time, steps columns.

Examples

  Sys.setenv("SSQ_PARALLEL" = 0)
  if (reticulate::py_module_available("forest")) {
    data = actiread::acti_read_gt3x(actiread::acti_example_gt3x())
    steps = acti_calculate_forest(data, sample_rate = 100)
  }

Calculate Summary Measures from Raw Accelerometer Data

Description

Calculate Summary Measures from Raw Accelerometer Data

Usage

acti_calculate_measures(
  data,
  unit = "1 min",
  fix_zeros = TRUE,
  dynamic_range = NULL,
  calculate_mims = TRUE,
  calculate_ac = TRUE,
  flag_data = TRUE,
  flags = NULL,
  ensure_all_time = TRUE,
  verbose = TRUE,
  sample_rate = NULL,
  ...
)

acti_calculate_flags(data, unit = "1 min", ensure_all_time = TRUE)

acti_calculate_n_idle(data, unit = "1 min", ensure_all_time = TRUE)

acti_calculate_enmo(...)

acti_calculate_ai_defined(...)

acti_calculate_mad(
  data,
  unit = "1 min",
  ensure_all_time = TRUE,
  verbose = FALSE
)

acti_calculate_auc(
  data,
  unit = "1 min",
  sample_rate = NULL,
  allow_truncation = FALSE,
  ensure_all_time = TRUE,
  verbose = TRUE
)

acti_calculate_fast_mims(
  data,
  unit = "1 min",
  dynamic_range = NULL,
  sample_rate = NULL,
  allow_truncation = TRUE,
  ensure_all_time = TRUE,
  verbose = TRUE,
  ...
)

acti_calculate_mims(
  data,
  unit = "1 min",
  dynamic_range = c(-6, 6),
  ensure_all_time = TRUE,
  ...
)

Arguments

Value

A data set with the calculated features

Examples

file = actiread::acti_example_gt3x()
res = actiread::acti_read_gt3x(file, verbose = FALSE)
res = res[1:12000, ]
measures = acti_calculate_measures(
  res,
  dynamic_range = NULL,
  calculate_mims = FALSE,
  calculate_ac = FALSE,
  flag_data = FALSE
)
auc = acti_calculate_auc(res)

mims = acti_calculate_mims(res, dynamic_range = NULL)

if (requireNamespace("data.table", quietly = TRUE)) {
   dt = data.table::as.data.table(res)
   out = acti_calculate_measures(dt, calculate_mims = FALSE, flag_data = FALSE,
     calculate_ac = FALSE)
}

Calculate Step Counts via SDT

Description

Calculate Step Counts via SDT

Usage

acti_calculate_sdt(data, sample_rate = NULL, ...)

Arguments

Value

A tibble with minute-level time, steps columns.

Examples

data = actiread::acti_read_gt3x(actiread::acti_example_gt3x())
steps = acti_calculate_sdt(data)

Calculate Step Counts via stepcount

Description

Use the stepcount package to estimate steps from raw accelerometer data and summarize them to minute-level epochs (as opposed to 10s default)

Usage

acti_calculate_stepcount(data, sample_rate = NULL, ..., epoch = "1 minute")

Arguments

Value

A tibble with minute-level time, steps, and walking columns.

Examples

  # reticulate::py_require("stepcount==3.11.0", python_version = "3.10", action = "add")
  # sc = try({ reticulate::import("stepcount") })
  if (stepcount::have_stepcount()) {
    data = actiread::acti_read_gt3x(actiread::acti_example_gt3x())
    steps = acti_calculate_stepcount(data, sample_rate = 100)
    steps = acti_calculate_stepcount(data, model_type = "rf")
  }

Calculate Step Counts via Verisense

Description

Calculate Step Counts via Verisense

Usage

acti_calculate_verisense(
  data,
  resample_to_15hz = TRUE,
  method = c("original", "revised"),
  ...
)

Arguments

Value

A tibble with minute-level time, steps columns.

Examples

data = actiread::acti_read_gt3x(actiread::acti_example_gt3x())
steps = acti_calculate_verisense(data)

Calibrate Accelerometer Data using agcounts

Description

This uses the van Hees calibration method typically exposed through GGIR, implemented here via agcounts::agcalibrate().

Usage

acti_calibrate(
  data,
  verbose = TRUE,
  fill_zeroes = TRUE,
  round_after_calibration = TRUE,
  ...
)

Arguments

Value

A calibrated dataset with the same columns as the input data, but with the X/Y/Z values calibrated using the van Hees method.

Examples

  res = acti_calibrate(data = actiread::acti_example_gt3x())

Example Actigraphy/Activity Count Data

Description

Example Actigraphy/Activity Count Data

Usage

acti_count_data

Format

A data.frame with the columns

time

time at the minute level

axis1

axis1 (Y) counts

axis2

axis2 (X) counts

axis3

axis3 (Z) counts

counts

vector magnitude of all 3 axes column

This data was taken from running agcounts::calculate_counts via acti_calculate_counts on actibase::acti_raw_data.

Process Raw data to Counts

Description

Process Raw data to Counts

Usage

acti_process(
  data,
  lfe_select = FALSE,
  method = c("choi", "troiano"),
  use_magnitude = TRUE,
  calibrate = FALSE,
  verbose = TRUE,
  ...,
  min_required = 1368L,
  round_digits = NULL
)

Arguments

Details

To match ActiLife for GT3X files, a GT3X path is read with digits = 8 (unless digits is given in ...), resampled, and then rounded to 3 digits. ActiLife rounds the scaled samples to 3 digits, half away from zero. Reading at 8 digits and then rounding gives exactly those values, but rounding values already read at 5 digits does not (e.g. 0.1234996 -> 0.12350 -> 0.124).

Value

A data frame containing activity counts and wear-time indicators.

Note

For acti_process, the ... argument are passed to actiread::acti_read_gt3x()

Process all supported actigraphy files in a directory

Description

Files are read according to their extension, passed to acti_process(), and saved as individual RDS files in outdir. Supported extensions are GT3X, CWA, GeneActiv BIN, and CSV, including .gz and .xz compressed suffixes for the supported formats described below.

Usage

acti_process_study(directory, outdir, verbose = TRUE, ...)

Arguments

Value

Invisibly, a character vector of paths to the saved RDS files. Files that failed are listed in its failed attribute: a named character vector of error messages, named by input file. Each RDS contains the processed data, with the raw reader header attached as the header attribute when available.

Default MIMS worker functions

Description

Default MIMS worker functions

Usage

mims_default_extrapolation(data, dynamic_range = NULL)

mims_default_interpolation(data)

mims_default_filtering(data)

Arguments

Value

A data set of data

Default MIMS Pre-processing

Description

Default MIMS Pre-processing

Usage

mims_default_processing(
  data,
  use_extrapolation = TRUE,
  use_filtering = TRUE,
  verbose = TRUE,
  dynamic_range = NULL,
  round_after_processing = FALSE
)

Arguments

Value

A processed data set

Perform step count calculation in a separate Python environment

Description

Perform step count calculation in a separate Python environment

Usage

py_acti_calculate_forest(
  ...,
  pyenv_function = function() {
     reticulate::import("forest")
 },
  show = FALSE
)

Arguments

Value

The output from acti_calculate_forest().

Examples

  Sys.setenv("SSQ_PARALLEL" = 0)
  if (reticulate::py_module_available("forest")) {
    data = actiread::acti_read_gt3x(actiread::acti_example_gt3x())
    steps = py_acti_calculate_forest(data, sample_rate = 100)
  }

Perform step count calculation in a separate Python environment

Description

Perform step count calculation in a separate Python environment

Usage

py_acti_calculate_stepcount(
  ...,
  pyenv_function = function() {
     stepcount::py_require_stepcount()
 },
  show = FALSE
)

Arguments

Value

The output from acti_calculate_stepcount(). A tibble with minute-level time, steps, and walking columns.

Examples

  if (stepcount::have_stepcount()) {
    data = actiread::acti_read_gt3x(actiread::acti_example_gt3x())
    steps = py_acti_calculate_stepcount(data, sample_rate = 100)
  }