Run the full actigraphy sleep analysis pipeline

Orchestrates the complete pipeline for a single ActTrust recording:

Usage

run_pipeline(
  path,
  tz = "UTC",
  gap_s = 120,
  params = acttrust_params(),
  offwrist_args = list(),
  sleep_args = list(),
  nap_args = list(),
  quiet = FALSE
)

Arguments

path

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

tz

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

gap_s

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

params

Device parameter preset, as returned by acttrust_params(). When supplied, values from params are used as defaults for each detector stage, with any explicit offwrist_args, sleep_args, or nap_args taking precedence. Defaults to acttrust_params().

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.

quiet

logical(1). If TRUE, suppresses the timestamp-issue warning emitted when check_consistency() finds problems. Useful in batch or testing contexts where the warning is expected. Default is FALSE.

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
} # }