Run the full actigraphy sleep analysis pipeline

Orchestrates the complete pipeline for a single ActTrust recording:

Usage

run_pipeline(
  path,
  tz = "UTC",
  wake_thresh = 60L,
  gap_s = 120,
  offwrist_args = list(),
  sleep_args = list(),
  nap_args = list()
)

Arguments

path

character(1). Path to the ActTrust .txt file.

tz

character(1). Recording time zone. Passed to read_acttrust(). Default is "UTC".

wake_thresh

integer(1). Minimum wake-bout length (epochs) used to separate sleep periods in compute_waso(). Default is 60.

gap_s

numeric(1). Gap threshold (seconds) for check_consistency(). Default is 120.

offwrist_args

list. Additional arguments passed to detect_offwrist_bimodal(). Default is an empty list.

sleep_args

list. Additional arguments passed to detect_sleep_crespo(). Default is an empty list.

nap_args

list. Additional arguments passed to detect_naps_crespo(). Default is an empty list.

Value

A zeitr_result S3 object — a named list with:

subject_id

character — derived from the input filename stem.

source_file

character — absolute path to the input file.

data

tibble — final epoch-level data frame with all state columns populated.

nights

tibble — per-night sleep statistics.

issues

tibble — timestamp consistency issues (0 rows if none).

metadata

list — device and subject metadata from the file header.

Details

1. Read — read_acttrust()

2. Consistency check — check_consistency()

3. Prepare — prepare_actigraphy()

4. Off-wrist detection — detect_offwrist_bimodal()

5. Main sleep period detection — detect_sleep_crespo()

6. Nap detection — detect_naps_crespo()

7. WASO + nightly statistics — compute_waso()

See also

run_pipeline_batch() for processing a directory of files.

Examples

if (FALSE) { # \dontrun{
result <- run_pipeline("recordings/P001.txt", tz = "America/Sao_Paulo")
result$nights
result$data
} # }