Study-level analysis

Overview

When a study contains multiple participants, zeitR provides two functions to work at the group level:

read_actigraphy_dir() — reads all actigraphy files in a folder into a zeitr_study object.
study_summary() — computes per-participant NPCRA variables and recording quality metrics across the whole study.

Reading a directory of files

Place all recording files (one per participant) in a single folder. The filename stem is used as the participant ID.

study <- read_actigraphy_dir(
  "recordings/",
  device  = "acttrust",
  pattern = "*.txt",
  tz      = "America/Sao_Paulo"
)
study

## zeitr_study: 12 recording(s)
## * P001: 10080 epochs
## * P002:  9950 epochs
## * P003: 10056 epochs
## ...

A zeitr_study is a named list of zeitr_recording objects. Individual recordings are accessed by participant ID:

study[["P001"]]$epochs
study[["P001"]]$metadata

Participant-level summary

study_summary() iterates over every recording in the study, calls compute_npcra() for each participant, and returns a single summary tibble:

summary_df <- study_summary(study)
summary_df

## # A tibble: 12 x 12
##    participant_id n_epochs n_days start               end                    IS    IV    RA    L5 L5_onset   M10 M10_onset
##    <chr>           <int>  <dbl> <dttm>              <dttm>              <dbl> <dbl> <dbl> <dbl> <chr>    <dbl> <chr>
##  1 P001            10080   7.00 2021-05-27 11:10:15 2021-06-03 11:09:15  0.72  0.43  0.89  12.3 02:30     84.7 11:00
##  2 P002             9950   6.91 2021-05-28 08:02:00 2021-06-04 07:59:00  0.68  0.51  0.85  10.1 03:00     79.4 10:30
##  3 P003            10056   6.98 2021-05-27 09:44:00 2021-06-03 09:41:00  0.55  0.72  0.74   8.9 04:00     61.2 12:00
## ...

Column reference

Column	Description
`participant_id`	Filename stem
`n_epochs`	Total epochs in the recording
`n_days`	Recording duration in days
`start` / `end`	First and last epoch timestamps
`IS`	Interdaily stability
`IV`	Intradaily variability
`RA`	Relative amplitude
`L5` / `L5_onset`	Least active 5 h mean and onset time
`M10` / `M10_onset`	Most active 10 h mean and onset time

Running the full pipeline across a study

run_pipeline_batch() runs the complete pipeline (off-wrist detection, Crespo sleep detection, Cole-Kripke WASO) for every file in a folder:

results <- run_pipeline_batch(
  "recordings/",
  pattern = "*.txt",
  tz      = "America/Sao_Paulo"
)

Each element of results is a zeitr_result (see vignette("getting-started")). To extract all nightly statistics into a single data frame:

library(dplyr)

all_nights <- lapply(names(results), function(pid) {
  df <- results[[pid]]$nights
  df$participant_id <- pid
  df
}) |>
  bind_rows()

all_nights

Combining NPCRA and sleep statistics

A common workflow is to combine group-level NPCRA from study_summary() with mean nightly statistics from run_pipeline_batch():

# 1. NPCRA summary
npcra_df <- study_summary(study)

# 2. Mean nightly stats per participant
sleep_df <- lapply(names(results), function(pid) {
  nts <- results[[pid]]$nights
  data.frame(
    participant_id = pid,
    mean_tst_min   = mean(nts$tst, na.rm = TRUE) * 60 / 60,  # epochs to min
    mean_eff       = mean(nts$eff, na.rm = TRUE),
    mean_waso_min  = mean(nts$waso, na.rm = TRUE),
    n_nights       = nrow(nts)
  )
}) |>
  bind_rows()

# 3. Join
full_df <- left_join(npcra_df, sleep_df, by = "participant_id")
full_df

Tips

Skipped files: read_actigraphy_dir() and run_pipeline_batch() both skip files that fail to parse and emit a warning, so a single corrupt file will not abort the whole study run.

Time zones: Set tz to the local recording time zone for correct circadian alignment (especially for IS and L5/M10 onset times). Using "UTC" when the recording was made in another time zone will shift all circadian onset times by the UTC offset.

Epoch duration: zeitR estimates epoch duration automatically from the median inter-epoch interval. If your files have inconsistent epoch lengths, pass epoch_s explicitly to study_summary() and compute_npcra().