Package {actisomni}

Estimate sleep with the asleep model

Description

Runs asleep::asleep() on complete, time-ordered raw triaxial acceleration and converts its predictions to the common acti_sleep_estimate format.

Usage

acti_asleep(
  data,
  min_wear_hours = 22L,
  time_shift = "0",
  report_light_and_temp = FALSE,
  pytorch_device = c("cpu", "cuda:0"),
  sample_rate = NULL,
  verbose = TRUE,
  force_download = FALSE
)

acti_calculate_asleep(
  data,
  min_wear_hours = 22L,
  time_shift = "0",
  report_light_and_temp = FALSE,
  pytorch_device = c("cpu", "cuda:0"),
  sample_rate = NULL,
  verbose = TRUE,
  force_download = FALSE
)

Arguments

Value

An acti_sleep_estimate tibble with time, sleep, sleep_probability, sleep_stage, nonwear, and method. The asleep backend currently does not return probabilities, so sleep_probability is NA.

Identify a diary-defined sleep window

Description

Identify a diary-defined sleep window

Usage

acti_sleep_diary(data, onset, wakeup)

Arguments

Value

An acti_sleep_guider object. Missing diary times return an empty window rather than imputing either boundary.

Examples

data <- actimetrics::acti_count_data
diary_window <- acti_sleep_diary(
  data, onset = data$time[5], wakeup = data$time[30]
)

Run a sleep-label ensemble from raw or epoch data

Description

This convenience workflow detects or accepts sustained inactivity bouts, runs compatible sleep guiders, creates one sleep label per guider, then produces a consensus. Raw triaxial data use HDCZA, HorAngle, and a fixed 22:00–08:00 window by default; L5 is included only when the data span its requested duration. Epoch data use NotWorn and the fixed window, adding L5 when possible. Set guiders to choose a subset explicitly.

Usage

acti_sleep_ensemble(
  data,
  guiders = NULL,
  epoch = "5 seconds",
  sib_method = "vanHees2015",
  fusion = c("staple", "majority"),
  sleepwindow_type = c("SPT", "TimeInBed"),
  ...
)

Arguments

Value

A list of time-indexed data. epoch_data includes the van Hees sib; each guider has a label_data element with time and window; labels has time plus one logical ⁠sleep_<guider>⁠ column per guider; fused has time, probability, and consensus label; and label_data combines all these analysis columns.

Examples

raw <- actiread::acti_read_gt3x(actiread::acti_example_gt3x(), verbose = FALSE)
result <- acti_sleep_ensemble(raw)

Fuse multiple sleep/wake labels with STAPLE

Description

STAPLE estimates a latent consensus sleep label and each input labeler's sensitivity and specificity using expectation-maximisation.

Usage

acti_sleep_fuse_labels(
  labels,
  threshold = 0.5,
  tolerance = 1e-06,
  max_iterations = 200L
)

Arguments

Value

A tibble with sleep_probability and binary sleep columns. If labels includes time or epoch, that index is retained. The fitted STAPLE parameters are attached as the staple attribute.

Examples

labels <- data.frame(
  sleep_l5 = c(FALSE, TRUE, TRUE, FALSE),
  sleep_fixed = c(FALSE, TRUE, FALSE, FALSE)
)
acti_sleep_fuse_labels(labels)

Dispatch a sleep-period-time guider from data

Description

For "HDCZA" and "HorAngle", supply raw triaxial acceleration; the selected function derives a regular epoch-level posture angle. The remaining methods use regular epoch-level activity, SIB, or timestamp data. Use acti_sleep_guider_requirements() for a method-by-method summary.

Usage

acti_sleep_guider(
  data,
  method = c("HDCZA", "HorAngle", "L5", "setwindow", "HLRB", "NotWorn", "sleeplog"),
  ...
)

Arguments

Value

An acti_sleep_guider object.

Examples

data <- actimetrics::acti_count_data
data <- data[rep(seq_len(nrow(data)), length.out = 24 * 60), ]
data$time <- data$time[1] + (seq_len(nrow(data)) - 1) * 60
guider <- acti_sleep_guider(data, method = "L5")

Describe data requirements for sleep guiders

Description

HDCZA and HorAngle take raw triaxial acceleration and create their own regular epoch-level angle. All other guiders take a regularly spaced, epoch-level data frame and do not require raw acceleration data.

Usage

acti_sleep_guider_requirements()

Value

A tibble describing the required data for each guider.

Examples

acti_sleep_guider_requirements()

Identify a sleep window with HDCZA

Description

Implements the HDCZA sleep-period-time guider for wrist accelerometry. It finds prolonged periods of little change in the supplied z-axis angle, joins interruptions shorter than an hour, and returns the longest resulting block. The default threshold is the 0.2 degrees specified in the GGIR guider documentation.

Usage

acti_sleep_hdcza(
  data,
  epoch = "5 seconds",
  threshold = 0.2,
  ignore_invalid = FALSE,
  min_block_minutes = 30,
  max_gap_minutes = 60
)

Arguments

Value

An acti_sleep_guider object. window is the selected SPT guider; crude_window retains all candidate blocks before choosing the longest.

Examples

# The bundled actiread recording contains raw X, Y, and Z acceleration.
raw <- actiread::acti_read_gt3x(actiread::acti_example_gt3x(), verbose = FALSE)
hdcza <- acti_sleep_hdcza(raw, epoch = "5 seconds")

Identify the longest rest bout from sustained inactivity bouts

Description

Identify the longest rest bout from sustained inactivity bouts

Usage

acti_sleep_hlrb(data)

Arguments

Value

An acti_sleep_guider object. window marks the longest selected rest bout, crude_window marks all bouts before selection, and smoothed_sib is the logical SIB classification after two-hour smoothing.

Examples

data <- actimetrics::acti_count_data
data <- data[rep(seq_len(nrow(data)), length.out = 24 * 60), ]
data$time <- data$time[1] + (seq_len(nrow(data)) - 1) * 60
# In practice, use a validated SIB classification rather than this example.
sib <- data$counts == 0
data$sib <- data$counts == 0
longest_rest <- acti_sleep_hlrb(data)

Identify a sleep window from horizontal posture

Description

Identify a sleep window from horizontal posture

Usage

acti_sleep_horangle(
  data,
  epoch = "5 seconds",
  longitudinal_axis = "Z",
  horizontal_threshold = 45,
  ignore_invalid = FALSE,
  min_block_minutes = 30,
  max_gap_minutes = 60
)

Arguments

Value

An acti_sleep_guider object. window marks the longest selected horizontal-posture block, and crude_window marks all candidate blocks. horizontal is the epoch-level posture flag, threshold is the angle limit, and epoch_data contains the averaged angle and invalid flag.

Examples

raw <- actiread::acti_read_gt3x(actiread::acti_example_gt3x(), verbose = FALSE)
horizontal <- acti_sleep_horangle(raw, epoch = "5 seconds")

Identify a sleep window from the least-active five hours

Description

Identify a sleep window from the least-active five hours

Usage

acti_sleep_l5(data, l5_hours = 5, window_hours = 12)

Arguments

Value

An acti_sleep_guider object. window marks the window centred on the least-active period; l5_start_index and l5_activity_sum identify that period's starting epoch and total activity.

Examples

# Repeat the bundled minute-level count data to form a complete example day.
data <- actimetrics::acti_count_data
data <- data[rep(seq_len(nrow(data)), length.out = 24 * 60), ]
data$time <- data$time[1] + (seq_len(nrow(data)) - 1) * 60
l5 <- acti_sleep_l5(data)

Convert a sleep guider to epoch-level sleep/wake labels

Description

A guider defines the likely main sleep window; it is not a sleep/wake classifier itself. This function applies GGIR's final overlap step to a sustained-inactivity-bout (sib) classification. With the default "SPT" rule, an entire SIB is sleep when any part overlaps the guider. With "TimeInBed", an SIB must be wholly inside the guider.

Usage

acti_sleep_label(sib, guider, sleepwindow_type = c("SPT", "TimeInBed"))

Arguments

Value

A logical vector: TRUE for sleep and FALSE for wake.

Examples

data <- actimetrics::acti_count_data
data <- data[rep(seq_len(nrow(data)), length.out = 24 * 60), ]
data$time <- data$time[1] + (seq_len(nrow(data)) - 1) * 60
guider <- acti_sleep_l5(data)
sib <- data$counts == 0
sleep <- acti_sleep_label(sib, guider)

Create sleep/wake labels for multiple guiders

Description

Create sleep/wake labels for multiple guiders

Usage

acti_sleep_labels(sib, guiders, sleepwindow_type = c("SPT", "TimeInBed"))

Arguments

Value

A tibble with one logical ⁠sleep_<guider>⁠ column per guider.

Examples

data <- actimetrics::acti_count_data
data <- data[rep(seq_len(nrow(data)), length.out = 24 * 60), ]
data$time <- data$time[1] + (seq_len(nrow(data)) - 1) * 60
guiders <- list(L5 = acti_sleep_l5(data), fixed = acti_sleep_setwindow(data))
labels <- acti_sleep_labels(data$counts == 0, guiders)

Identify a low-activity window for no-night-wear protocols

Description

Identify a low-activity window for no-night-wear protocols

Usage

acti_sleep_notworn(data, min_block_minutes = 30, max_gap_minutes = 60)

Arguments

Value

An acti_sleep_guider object. window marks the longest selected low-activity block, and crude_window marks all candidate blocks. smoothed_activity contains five-minute rolling activity values, low_activity flags candidate epochs, and threshold is the activity cutoff used to identify them.

Examples

data <- actimetrics::acti_count_data
data <- data[rep(seq_len(nrow(data)), length.out = 24 * 60), ]
data$time <- data$time[1] + (seq_len(nrow(data)) - 1) * 60
# `counts` is an epoch-level activity metric.
no_night_wear <- acti_sleep_notworn(data)

Identify a fixed daily sleep window

Description

Identify a fixed daily sleep window

Usage

acti_sleep_setwindow(data, start_hour = 22, end_hour = 8)

Arguments

Value

An acti_sleep_guider object.

Examples

data <- actimetrics::acti_count_data
fixed_window <- acti_sleep_setwindow(data, start_hour = 22, end_hour = 8)

Detect sustained inactivity bouts (SIBs)

Description

For raw triaxial accelerometer data, the default "vanHees2015" method derives a longitudinal-axis angle at epoch resolution and identifies periods with no posture change above angle_threshold. For epoch-level data, provide a precomputed sib column; alternatively, "low_activity" marks epochs whose conventional activity metric is at or below activity_threshold.

Usage

acti_sleep_sib(
  data,
  method = c("vanHees2015", "low_activity"),
  epoch = "5 seconds",
  time_threshold_minutes = 5,
  angle_threshold = 5,
  activity_threshold = 0
)

Arguments

Value

A tibble with time, sib, and supporting epoch-level variables.

Examples

raw <- actiread::acti_read_gt3x(actiread::acti_example_gt3x(), verbose = FALSE)
sib <- acti_sleep_sib(raw)

Summarize sleep periods with Tudor–Locke

Description

Coerces actisomni-style epoch data to an actigraph.sleepr tbl_agd and delegates period detection and metric calculation to actigraph.sleepr::apply_tudor_locke(). This avoids maintaining a separate implementation of the Tudor–Locke rules.

Usage

acti_sleep_tudor_locke(
  data,
  time_col = "time",
  activity_col = NULL,
  sleep_col = "sleep",
  id_col = NULL,
  n_bedtime_start = 5,
  n_wake_time_end = 10,
  min_sleep_period = 160,
  max_sleep_period = 1440,
  min_nonzero_epochs = 0
)

Arguments

Value

A tibble of Tudor–Locke sleep periods and metrics, as returned by actigraph.sleepr::apply_tudor_locke().

Examples

time <- as.POSIXct("2020-01-01", tz = "UTC") + 0:299 * 60
epochs <- data.frame(time = time, activity = 0, sleep = TRUE)
acti_sleep_tudor_locke(epochs)

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 resulting data can be passed directly to acti_sleep_tudor_locke().

Usage

acti_sleep_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).

Estimate sleep with the sleeper model

Description

Runs sleeper::estimate_sleep() on complete, time-ordered raw triaxial acceleration. Input is converted to the timestamp-in-seconds format required by sleeper before the model is called.

Usage

acti_sleeper(data, epoch = 30L, model_dir)

Arguments

Value

An acti_sleep_estimate tibble with time, sleep, sleep_probability, sleep_stage, nonwear, and method. The sleeper backend does not return probabilities or sleep stages, so those columns are NA.

Estimate sleep with asleep in an isolated Python process

Description

Uses asleep::py_asleep() to run the same asleep model as acti_asleep() in a callr subprocess. This keeps Python package requirements separate from the current R session.

Usage

py_acti_asleep(
  data,
  min_wear_hours = 22L,
  time_shift = "0",
  report_light_and_temp = FALSE,
  pytorch_device = c("cpu", "cuda:0"),
  sample_rate = NULL,
  verbose = TRUE,
  force_download = FALSE,
  pyenv_function = function() asleep::py_require_asleep(),
  show = FALSE
)

Arguments

Value

An acti_sleep_estimate tibble; see acti_asleep().

Estimate sleep with sleeper in an isolated Python process

Description

Uses sleeper::py_estimate_sleep() to run the same sleeper model as acti_sleeper() in a callr subprocess.

Usage

py_acti_sleeper(
  data,
  epoch = 30L,
  model_dir,
  pyenv_function = function() sleeper::py_require_sleeper(),
  show = FALSE
)

Arguments

Value

An acti_sleep_estimate tibble; see acti_sleeper().