zeitR — Actigraphy parsing and analysis for R • zeitR

Actigraphy data parsing and analysis for R.

[!WARNING] zeitR is in early development and has not been formally tested. The API may change without notice, computed variables have not yet been validated against reference implementations, and the package has not undergone peer review. Use with caution and verify outputs independently before using in any research context.

📖 What is zeitR?

zeitR is an R package for importing, parsing, and analysing raw actigraphy recordings from wrist-worn devices. It runs a full rest-activity pipeline — off-wrist detection, sleep period identification, WASO computation — and computes standard non-parametric circadian rhythm variables (IS, IV, RA, L5, M10), returning tidy data frames ready for downstream chronobiological analysis.

zeitR is designed to complement slumbR in the Circadia Lab ecosystem: slumbR handles sleep diary and questionnaire data, zeitR handles the actigraphy side of a study, and both speak the same tidy, pipeline-friendly R idioms.

✨ Features

📥 read_actigraphy() — parse a raw device file into a zeitr_recording object with $epochs and $metadata
📂 read_actigraphy_dir() — batch-read a whole directory of files into a zeitr_study
🔍 check_consistency() — flag timestamp gaps, backward jumps, and firmware year artefacts
🦾 detect_offwrist_bimodal() — Condor bimodal activity/temperature off-wrist detection (three-stage refiner)
😴 detect_sleep_crespo() — main sleep period detection (Crespo et al., 2012)
💤 detect_naps_crespo() — secondary sleep period (nap) detection (Crespo et al., 2012)
⏱️ score_epochs_cole_kripke() — epoch-level wake/sleep scoring (Cole & Kripke, 1992)
📊 compute_waso() — nightly TBT, TST, WASO, SOL, SOI, number of awakenings, and sleep efficiency
📐 compute_npcra() — non-parametric circadian rhythm analysis: IS, IV, RA, L5, M10
🗂️ study_summary() — participant-level NPCRA summary across a whole study
🚀 run_pipeline() — run the complete pipeline on a single file in one call
🗃️ run_pipeline_batch() — run the complete pipeline across a directory of files

🚀 Getting Started

Installation

# Install from GitHub
# install.packages("pak")
pak::pak("circadia-bio/zeitR")

Single recording

library(zeitR)

rec <- read_actigraphy("recordings/P001.txt", tz = "America/Sao_Paulo")
rec$epochs    # tidy epoch-level tibble
rec$metadata  # device info, firmware, epoch length

Full pipeline

result <- run_pipeline("recordings/P001.txt", tz = "America/Sao_Paulo")

result$nights  # nightly sleep statistics
result$data    # epoch-level tibble with state, sleep, offwrist columns
result$issues  # timestamp consistency issues (0 rows if none)

Non-parametric circadian rhythm analysis

npcra <- compute_npcra(rec)
npcra
#>   participant_id    IS    IV    RA    L5 L5_onset   M10 M10_onset n_days n_epochs
#>            P001  0.72  0.43  0.89  12.3    02:30  84.7     11:00    7.0    10080

Whole study

study <- read_actigraphy_dir("recordings/", tz = "America/Sao_Paulo")
study_summary(study)
#>   participant_id n_epochs n_days    IS    IV    RA    L5 L5_onset   M10 M10_onset
#>            P001    10080   7.00  0.72  0.43  0.89  12.3    02:30  84.7     11:00
#>            P002     9950   6.91  0.68  0.51  0.85  10.1    03:00  79.4     10:30

📐 Computed variables

NPCRA (`compute_npcra()`)

Variable	Definition
`IS`	Interdaily stability — consistency of the 24 h rhythm across days (0–1)
`IV`	Intradaily variability — fragmentation of the rest-activity rhythm (≥ 0)
`RA`	Relative amplitude — contrast between M10 and L5 (0–1)
`L5` / `L5_onset`	Mean activity and onset time of the least active 5 h window
`M10` / `M10_onset`	Mean activity and onset time of the most active 10 h window

Nightly sleep statistics (`compute_waso()`)

Variable	Definition
`tbt`	Total Bed Time (epochs)
`tst`	Total Sleep Time (epochs)
`waso`	Wake After Sleep Onset (epochs)
`sol`	Sleep Onset Latency (epochs)
`soi`	Sleep Offset Inertia (epochs)
`nw`	Number of awakenings
`eff`	Sleep efficiency — TST / TBT

🔬 Algorithms

Step	Algorithm	Reference
Off-wrist detection	Condor bimodal activity/temperature model	Condor Instruments
Sleep period detection	Crespo adaptive median filter	Crespo et al. (2012)
Nap detection	Crespo zero-proportion filter	Crespo et al. (2012)
Epoch scoring	Cole-Kripke weighted ZCM sum	Cole & Kripke (1992)

🗂️ Project Structure

zeitR/
├── R/
│   ├── zeitR-package.R       # package-level docs
│   ├── read_acttrust.R       # ActTrust file parser
│   ├── read_actigraphy.R     # device-agnostic wrapper, zeitr_study
│   ├── prepare.R             # temperature clamping, state columns
│   ├── consistency.R         # timestamp quality checks
│   ├── offwrist.R            # detect_offwrist_bimodal()
│   ├── offwrist_refiner.R    # three-stage BimodalOffwristRefiner port
│   ├── sleep_periods.R       # detect_sleep_crespo(), detect_naps_crespo()
│   ├── cole_kripke.R         # score_epochs_cole_kripke()
│   ├── waso.R                # compute_waso()
│   ├── npcra.R               # compute_npcra()
│   ├── study_summary.R       # study_summary()
│   ├── pipeline.R            # run_pipeline(), run_pipeline_batch()
│   └── utils.R               # internal helpers
├── man/figures/
│   ├── logo.svg              # hex sticker
│   └── favicon.svg           # favicon
├── vignettes/
│   ├── getting-started.Rmd
│   ├── npcra.Rmd
│   └── study-analysis.Rmd
├── tests/testthat/
├── .github/workflows/
│   ├── R-CMD-check.yaml
│   └── pkgdown.yaml
├── DESCRIPTION
├── NEWS.md
└── zeitR.Rproj

📦 Dependencies

Package	Version	Purpose
cli	≥ 3.6.0	Messages and progress
lubridate	≥ 1.9.0	Date/time handling
tibble	≥ 3.0.0	Tidy data frames
tidyr	≥ 1.3.0	Pivoting and reshaping

👥 Authors

Role	Name	Affiliation
Author, maintainer	Lucas França	Northumbria University, Circadia Lab
Author	Mario Leocadio-Miguel	Northumbria University, Circadia Lab

🌙 slumbR — R companion for Sleep Diaries exports (sleep variables, questionnaire scoring)
🧮 tallieR — R companion for ScoreMe questionnaire exports
🔬 circadia-bio — the Circadia Lab GitHub organisation

📄 Licence

Released under the MIT License.

⌚️ zeitR