Package 'ActiSleep'

Accelerometry Data

Description

A dataset containing accelerometry data for a single subject in 1-minute epochs, includes vector magnitude and other measurements.

• date: Time and date of a single measurement.

• axis1: X-axis movement.

• axis2: Y-axis movement.

• axis3: Z-axis movement.

• steps: Steps taken by the subject.

• lux: Amount of light present, measured in lux.

• inclineOff: Incline off.

• inclineStanding: Incline standing.

• inclineSitting: Incline sitting.

• inclineLying: Incline lying.

• VM: Vector magnitude, calculated from x-, y-, and z-axis measurements.

Usage

data("AccelData")

Format

A data frame with 1351 rows and 11 variables.

---

Extract the segments data frame from an actisleep_result

Description

Extract the segments data frame from an actisleep_result

Usage

## S3 method for class 'actisleep_result'
as.data.frame(x, ...)

Arguments

x	An actisleep_result object.
...	Ignored.

Value

The segments data frame.

---

Sleep duration estimation via Pruned Dynamic Programming

Description

Applies a Pruned Dynamic Programming (PDP) segmentation algorithm to wrist or hip accelerometer data to identify transitions between sleep and wakefulness. The algorithm is described in Baek et al. (2021); this function wraps the full analysis pipeline including optional non-wear detection and diary-based validation.

Usage

estimate_sleep(
  data,
  cost_model = "poisson",
  subject_id = NA,
  activity_col = "max_count",
  threshold_pct = 0.4,
  segments_per_hour = 3,
  no_activity_cutoff = 0.7,
  min_sleep_minutes = 20,
  min_wake_minutes = 180,
  min_nap_minutes = 20,
  detect_nonwear = FALSE,
  min_wear_minutes = 120,
  use_diary = FALSE,
  diary = NULL,
  default_bedtime = "22:00:00",
  default_waketime = "08:00:00",
  tz = "GMT"
)

Arguments

data	Data frame of accelerometer data. Must contain a date column (POSIXct or a character string parseable by ymd_hms) and a numeric activity column named by activity_col.
cost_model	Cost function for the PDP algorithm. Either a string ("poisson", "normal", "negative_binomial", "variance", "exponential") or the corresponding integer (1–5). Default "poisson".
subject_id	Optional subject identifier stored in the result.
activity_col	Name of the column containing the activity-count variable to segment (e.g. "VM" for vector magnitude). Default "max_count".
threshold_pct	Quantile (0–1) used to compute the person-specific activity threshold; counts at or below this quantile are set to zero before segmentation. Default 0.4 (40th percentile). Use 0 to skip thresholding.
segments_per_hour	Number of PDP segments allocated per hour of recording. Higher values allow finer time resolution at the cost of computation. Default 3.
no_activity_cutoff	Proportion (0–1) of zero-count epochs required within a segment to classify it as no physical activity (NoPA). Default 0.7.
min_sleep_minutes	Minimum duration (minutes) for a segment to qualify as sleep. Default 20.
min_wake_minutes	Minimum duration (minutes) for a segment to qualify as wake. Default 180.
min_nap_minutes	Sleep segments shorter than this (minutes) that do not overlap the diary window are excluded as naps. Default 20.
detect_nonwear	Logical; if TRUE the weartime algorithm is applied before segmentation. Days with non-wear periods are flagged with valid_accel = 0. Default FALSE.
min_wear_minutes	Minimum number of wear minutes required when detect_nonwear = TRUE. Default 120.
use_diary	Logical; if TRUE diary-based bed/wake times are used to validate sleep segments. diary must be supplied. Default FALSE.
diary	Data frame with columns bed and wake (POSIXct) giving the expected sleep window for each night. Required when use_diary = TRUE. One row per night.
default_bedtime	Default bed-time clock string used when use_diary = FALSE. Default "22:00:00".
default_waketime	Default wake-time clock string used when use_diary = FALSE. Default "08:00:00".
tz	Timezone string applied to all date-time operations. Default "GMT".

Details

Estimate daily sleep duration from accelerometer data

**Algorithm overview**

1. A person-specific activity threshold is computed as the threshold_pct-th percentile of the activity counts. Counts at or below this threshold are set to zero. 2. The zeroed series is segmented into $K = \text{hours} \times \text{segments\_per\_hour}$ pieces using the PDP changepoint algorithm with the selected cost model. 3. Consecutive segments in which the proportion of zero-count epochs exceeds no_activity_cutoff are merged and labelled as potential sleep. 4. Candidate sleep segments are validated against the supplied (or default) sleep window and filtered by minimum duration.

**Cost models**

| Value | Model | Best for | |——-|——-|———-| | "poisson" or 1 | Poisson | Non-negative integer counts | | "normal" or 2 | Normal | Continuous, roughly symmetric data | | "negative_binomial" or 3 | Negative binomial | Overdispersed integer counts | | "variance" or 4 | Variance change | Constant-mean, changing variance | | "exponential" or 5 | Exponential | Positive continuous waiting times |

Value

An object of class actisleep_result (a list) with two elements:

segments

Data frame of estimated sleep segments. Columns: sleep_onset, sleep_offset (character timestamps), duration_min (difftime), pct_zero_activity (proportion), no_activity_cutoff, is_sleep (0/1), is_no_activity (0/1), diary_overlap (0/1), diary_bedtime, diary_waketime (POSIXct), n_sleep_segments (integer).

parameters

Named list recording the call parameters: subject_id, cost_model, threshold_pct, segments_per_hour, n_segments, valid_accel, day_of_week.

Use as.data.frame.actisleep_result to extract the segments data frame directly.

References

Baek, J., Banker, M., Jansen, E. C., She, X., Peterson, K. E., Pitchford, E. A., & Song, P. X. K. (2021). An Efficient Segmentation Algorithm to Estimate Sleep Duration from Actigraphy Data. Statistics in Biosciences. doi:10.1007/s12561-021-09309-3

See Also

read_agd for reading ActiGraph .agd files.

Examples

data("AccelData")
# estimate_sleep() auto-detects common date formats
result <- estimate_sleep(AccelData, activity_col = "VM")
print(result)

data("AccelData")
result <- estimate_sleep(AccelData, activity_col = "VM", detect_nonwear = TRUE)

data("AccelData")
data("SleepDiary1Day")
# Build a diary data frame with bed and wake columns.
# estimate_sleep() auto-parses common character date-time formats.
diary <- data.frame(
  bed  = SleepDiary1Day$bed,
  wake = SleepDiary1Day$wake
)
result <- estimate_sleep(
  AccelData,
  cost_model         = "normal",
  activity_col       = "VM",
  threshold_pct      = 0,
  detect_nonwear     = TRUE,
  segments_per_hour  = 2,
  no_activity_cutoff = 0.45,
  min_sleep_minutes  = 5,
  use_diary          = TRUE,
  diary              = diary
)
print(result)

---

Print an actisleep_result

Description

Displays a concise, formatted summary of the sleep estimation output.

Usage

## S3 method for class 'actisleep_result'
print(x, ...)

Arguments

x	An actisleep_result object.
...	Ignored.

Value

x invisibly.

---

Read AGD file data

Description

Read an ActiGraph .agd file (SQLite format) and return device settings and raw accelerometer data.

Usage

read_agd(file, tz = "GMT", sec = 10)

Arguments

file	Path to an AGD data file.
tz	Timezone string, default "GMT".
sec	Epoch length in seconds used to construct timestamps, default 10.

Value

A list with two elements:

settings

Data frame of device settings metadata.

raw.data

Data frame with columns date and all accelerometer channels (axis1, axis2, axis3, steps, lux, etc.).

---

This code was written by Alice Cleynen, Guillem Rigaill, and Michel Koskas as part of the Segmentor3IsBack package, which is no longer in CRAN. It has been imported into the ActiSleep package to ensure this package's longevity.

Description

This code was written by Alice Cleynen, Guillem Rigaill, and Michel Koskas as part of the Segmentor3IsBack package, which is no longer in CRAN. It has been imported into the ActiSleep package to ensure this package's longevity.

---

Sleep Diary 1-Day Data

Description

A small dataset containing sleep diary data for a single day and single subject

• bed. time at which the subject reported going to sleep on day 1

• wake. time at which the subject reported waking up on day 1

Usage

data("SleepDiary1Day")

Format

a data frame with 1 row and 2 variables

---

Sleep Diary 1-Week Data

Description

A small dataset containing sleep diary data for a single week and single subject

• FOLIOCC. unique subject id

• etapa.

• stage.

• start_day. first day of measurement

• time_bed1. time at which the subject reported going to sleep on day 1

• time_wake1. time at which the subject reported waking up on day 1

• time_bed2. time at which the subject reported going to sleep on day 2

• time_wake2. time at which the subject reported waking up on day 2

• time_bed3. time at which the subject reported going to sleep on day 3

• time_wake3. time at which the subject reported waking up on day 3

• time_bed4. time at which the subject reported going to sleep on day 4

• time_wake4. time at which the subject reported waking up on day 4

• time_bed5. time at which the subject reported going to sleep on day 5

• time_wake5. time at which the subject reported waking up on day 5

• time_bed6. time at which the subject reported going to sleep on day 6

• time_wake6. time at which the subject reported waking up on day 6

• time_bed7. time at which the subject reported going to sleep on day 7

• time_wake7. time at which the subject reported waking up on day 7

Usage

data("SleepDiary1Week")

Format

a data frame with 1 row and 18 variables

---

Summarise an actisleep_result

Description

Prints key aggregate statistics: total sleep time, number of sleep segments, and average proportion of zero-activity epochs.

Usage

## S3 method for class 'actisleep_result'
summary(object, ...)

Arguments

object	An actisleep_result object.
...	Ignored.

Value

object invisibly.

---