Actigraphy data parsing and analysis for R.
โ ๏ธ zeitR is in early development and has not been formally validated. The CSPD pipeline has been validated epoch-for-epoch against the Condor circadiaBase Python reference on an ActTrust recording. The Vallim pipeline has been validated at the classification level against Julia Vallim's Python reference notebook. Neither pipeline has undergone formal peer review. Verify outputs independently before using in any research context.
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 ships two end-to-end pipelines:
run_pipeline() โ the Condor CSPD pipeline, validated epoch-for-epoch against the Condor circadiaBase Python reference.run_pipeline_native() โ the Vallim pipeline, a post-processing layer developed by Julia Ribeiro da Silva Vallim that replaces Condor's classification logic with an adaptive 7-rule rule set (Fix 25, 26a/b/c, 27, 29, Rules 3โ7). Handles edge cases including fragmented episodes, long sleep periods, date collisions, and adaptive nocturnal window inference from wrist temperature and ambient light.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.
Beyond the two pipelines, zeitR also estimates energy expenditure and classifies physical activity (PA) intensity from raw ActTrust/GT3X+ activity counts, using published equations (see pa_equations() in Features below) -- extending zeitR beyond sleep into the other half of the 24 h rest-activity cycle. compute_activity_counts() extends this one step further back: for devices or pipelines that only provide raw triaxial acceleration samples rather than onboard-computed counts, it converts them into the same epoch-level PIM/TAT/ZCM shape read_acttrust() already produces.
read_actigraphy() โ parse a raw device file into a zeitr_recording objectread_actigraphy_dir() โ batch-read a whole directory into a zeitr_study
read_acttrust() โ parse a Condor ActTrust .txt export into a tidy tibbleread_axivity() โ bridge axR's raw Axivity AX3/AX6 (.cwa) output into the same epoch-level shape, via compute_activity_counts()
prepare_actigraphy() โ clamp temperature ranges and initialise state/offwrist/sleep columnscheck_consistency() โ flag timestamp gaps, backward jumps, and firmware artefactsdetect_offwrist_bimodal() โ Condor bimodal activity/temperature off-wrist detectiondetect_sleep_crespo() โ main sleep period detection (Crespo et al., 2012)detect_naps_crespo() โ secondary sleep period 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, awakenings, sleep efficiencycompute_npcra() โ non-parametric circadian rhythm analysis (IS, IV, ISm, IVm, RA, L5, M10)compute_sri() โ Sleep Regularity Index (Phillips et al., 2017); epoch-level state by default, or Sadeh/Cole-Kripke/Scripps/Roenneberg scoring via algo
compute_lri() โ Light Regularity Index (Hand et al., 2023), day-to-day consistency of light exposure timingcompute_cosinor() โ Cosinor rhythmometry (Cornelissen, 2014): acrophase, MESOR, amplitude from a fixed-period cosine fitstudy_summary() โ participant-level NPCRA summary across a whole studystudy_sleep_metrics() โ participant-level sleep-timing/chronotype summary (CPD, MSF/MSW, SJL) across a whole studycompute_sleep_metrics() โ per-night sleep metrics split by day type (overall / workday / free day)compute_cpd_metrics() โ CPD, MSW, MSF, MSFsc, social jet lag (SJL, SJLa)compute_activity_counts() โ convert raw triaxial acceleration into epoch-level PIM/TAT/ZCM counts (reuses mrpheus's validated filter primitives)pa_equations() โ published ActTrust/GT3X+ MET-estimation coefficients and count cut-points (Batista et al., 2026)estimate_ee() โ estimate METs from activity counts via the published regression equationclassify_pa_intensity() โ bin METs into light/moderate/vigorous/very vigorous PA bandsclassify_pa_counts() โ classify PA intensity directly from activity counts (device + placement)run_pipeline() โ full CSPD pipeline on a single filerun_pipeline_batch() โ CSPD pipeline across a directoryrun_pipeline_native() โ full Vallim pipeline on a single filerun_pipeline_native_batch() โ Vallim pipeline across a directoryplot_actogram() โ single-column raster actogram of sleep/wake statesplot_actogram_double() โ classic double-plotted actogram (48 h window per row)plot_actogram_activity() โ double-plotted actogram with activity-intensity barsactogram_colours() โ default state colour palette for actogram plotsexport_hypnogram() โ export to hypnoR format (W / Sleep / Quiet sleep; subject_id auto-inferred)extract_sleep_episodes() โ extract per-episode statistics from a CSPD-scored tableclassify_sleep_episodes() โ apply the JRSV rule set to classify episodescirc_mean_h() โ circular mean for clock-time variables (handles midnight wrap)circ_sd_h() โ circular SD for clock-time variableslabel_states() โ convert integer epoch states to a human-readable factoracttrust_params() โ device parameter preset for the ActTrust actigraphlids_transform() โ LIDS non-linear inactivity transform + Gaussian/moving-average smoothingfit_lids() โ sloped-cosine fit scanning candidate ultradian periods (Munich Rhythmicity Index)detect_lids_bouts() โ standalone Roenneberg relative-immobility sleep-bout detector for raw activitycompute_lids() โ full LIDS pipeline: bout extraction, transform, fit, and quality filteringstudy_lids_metrics() โ participant-level ultradian cycle-length/amplitude/offset summary across a whole studyInstall from r-universe (recommended โ pre-built binaries):
install.packages(
"zeitR",
repos = c("https://circadia-bio.r-universe.dev", "https://cloud.r-project.org")
)
Or install the development version from GitHub:
install.packages("pak")
pak::pak("circadia-bio/zeitR")
library(zeitR)
result <- run_pipeline("recordings/P001.txt", tz = "America/Sao_Paulo")
result$nights # nightly sleep statistics
result$data # epoch-level tibble with state column
result$issues # timestamp consistency flags
result <- run_pipeline_native("recordings/P001.txt", tz = "America/Sao_Paulo")
# nights has an additional sleep_type column ("main" / "secondary")
result$nights |> dplyr::filter(sleep_type == "main")
result$data$state_label <- label_states(result$data$state)
table(result$data$state_label)
#> wake sleep nap off-wrist
#> 48231 24603 892 2470
main_nights <- result$nights |> dplyr::filter(sleep_type == "main")
onset_h <- as.numeric(format(main_nights$bed_time, "%H")) +
as.numeric(format(main_nights$bed_time, "%M")) / 60
circ_mean_h(onset_h) # mean sleep onset (handles midnight wrap)
circ_sd_h(onset_h) # within-person variability in sleep onset
rec <- read_acttrust("recordings/P001.txt", tz = "America/Sao_Paulo")
npcra <- compute_npcra(rec)
npcra
#> IS IV ISm IVm RA L5 L5_onset M10 M10_onset n_days
#> 0.72 0.43 0.75 0.41 0.89 12.3 02:30 84.7 11:00 7.0
ISm/IVm average IS/IV across every divisor of 1440 minutes between
1-60 min (22 resolutions), matching pyActigraphy's own multi-resolution
convention.
result <- run_pipeline_native("recordings/P001.txt", tz = "America/Sao_Paulo")
compute_sri(result)
#> participant_id sri n_pairs n_epochs
#> P001 78.4 8640 10080
By default (algo = "vallim"), derives sleep/wake from the epoch-level
state column zeitR's own pipelines already produce, rather than a
pyActigraphy scoring algorithm -- see ?compute_sri for the off-wrist
gap-interpolation rules and why this showed substantially better
agreement with manual reference scoring in validation.
algo = "sadeh", "ck", "scripps", and "roenneberg" instead score raw
activity via pyActigraphy's own algorithms, each verified against a real
execution of the actual reference environment:
rec <- read_acttrust("recordings/P001.txt", tz = "America/Sao_Paulo")
compute_sri(rec, algo = "roenneberg")
See ?compute_sri for the precise differences between "vallim" and the
four raw-activity algorithms (aggregation method, off-wrist handling).
rec <- read_acttrust("recordings/P001.txt", tz = "America/Sao_Paulo")
compute_lri(rec)
#> participant_id LRI_10 LRI_20 LRI_50 LRI_100 LRI_300 n_epochs
#> P001 45.0 43.7 42.9 41.8 40.4 10080
Day-to-day consistency of light exposure timing (Hand et al., 2023),
analogous to compute_sri() but applied to a binarized light-exposure
signal at five default thresholds. See ?compute_lri for a real
discrepancy this port surfaced in the reference implementation itself
(the thresholds are documented as log10-lux but applied to raw,
untransformed light in the actual reference code) and why compute_lri()
matches that real behaviour by default rather than the documented intent.
rec <- read_acttrust("recordings/P001.txt", tz = "America/Sao_Paulo")
compute_cosinor(rec)
#> participant_id acrophase_time acrophase_time_neg MESOR amplitude period_min
#> P001 15:00 -9.0 2082.68 1859.17 1440
Fits a fixed-24h-period cosine model (acrophase/MESOR/amplitude), matching
pyActigraphy's actual Cosinor class as used in the reference pipeline
(period locked, not fit -- a free period let the reference's own optimizer
converge anywhere from 0.23h to 91.75h). Solved here via ordinary least
squares rather than a nonlinear optimizer -- verified by direct execution
to match the reference's real lmfit-based fit to floating-point
precision when the period is locked, which it always is in practice. Pass
col = "light" or col = "int_temp" to fit a different channel.
result <- run_pipeline_native("recordings/P001.txt", tz = "America/Sao_Paulo")
lids_bouts <- compute_lids(result)
lids_bouts[lids_bouts$passes_quality_filter,
c("bout_id", "period_min", "amplitude", "offset", "pearson_r")]
#> bout_id period_min amplitude offset pearson_r
#> 1 92 12.4 88.1 0.67
#> 2 88 10.9 85.3 0.71
# Study-level: median cycle length, amplitude, offset, slope per participant
results <- run_pipeline_native_batch("recordings/", tz = "America/Sao_Paulo")
study_lids_metrics(results)
Ports Winnebeck et al. (2018) and its infant extension in Hammad et al.
(2026, SLEEP): the 100/(1+x) LIDS transform, Gaussian or
moving-average smoothing, and a sloped-cosine period scan selected by the
Munich Rhythmicity Index. Bouts come either from an existing zeitR
pipeline's state column or from the standalone detect_lids_bouts()
relative-immobility detector for raw activity -- see vignette("lids") and
?compute_lids before using this in a real analysis; not yet validated
against pyActigraphy's LIDS class or an external reference dataset.
p <- acttrust_params()
p$sleep$sleep_quantile <- 1/3 # original Crespo (2012) threshold
result <- run_pipeline("recordings/P001.txt", params = p)
result$data$pa_intensity <- classify_pa_counts(
result$data$activity,
device = "ACTT",
placement = "wrist"
)
table(result$data$pa_intensity)
See vignette("physical-activity") and ?pa_equations before using this in
a real analysis -- the equations come from a single controlled-treadmill
validation study and the help page spells out exactly what that does and
doesn't license.
# x, y, z: raw triaxial acceleration samples; sampling_rate in Hz
counts <- compute_activity_counts(x, y, z, sampling_rate = 25, epoch_sec = 60)
counts$mets <- estimate_ee(counts$PIM, device = "ACTT", placement = "wrist")
counts$pa_intensity <- classify_pa_intensity(counts$mets)
Requires mrpheus (reuses its validated remove_dc()/bandpass_filter()
rather than a new, unvalidated filter). See vignette("raw-accelerometry")
and ?compute_activity_counts for the full processing chain and what is
(and isn't) validated about it.
.cwa) files# Bridges axR::axivity_read_cwa()'s raw per-sample output into the same
# epoch-level shape read_acttrust() produces
rec <- read_axivity("recordings/P001.cwa", tz = "America/Sao_Paulo")
rec
# or via the device-agnostic wrapper
rec <- read_actigraphy("recordings/P001.cwa", device = "axivity", tz = "America/Sao_Paulo")
Requires axR (raw .cwa parsing). Treat activity/ZCMn from this path
as an unvalidated approximation -- no filter/threshold preset has been
checked against real Axivity output; see ?read_axivity for the full
caveats.
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) |
ISm / IVm
|
Mean IS/IV across 22 resolutions (every divisor of 1440 min between 1โ60 min) |
RA |
Relative amplitude โ contrast between M10 and L5 (0โ1) |
L5 / L5_onset
|
Mean activity and onset of the least active 5 h window |
M10 / M10_onset
|
Mean activity and onset of the most active 10 h window |
compute_sri())| Variable | Definition |
|---|---|
sri |
Sleep Regularity Index (Phillips et al., 2017) โ day-to-day sleep/wake consistency; โ100 (inverted) to +100 (perfectly regular), 0 = chance |
n_pairs |
Number of valid 24h-apart epoch comparisons used (algo = "vallim" only; NA for the four raw-activity algorithms, whose aggregation isn't a single pooled pair count) |
Five algorithms available via algo: "vallim" (default, epoch-level state), "sadeh", "ck", "scripps", "roenneberg" (raw activity, matching pyActigraphy's own scoring algorithms).
compute_lri())| Variable | Definition |
|---|---|
LRI_10, LRI_20, LRI_50, LRI_100, LRI_300
|
Light Regularity Index (Hand et al., 2023) at five default thresholds โ same โ100/+100 scale and interpretation as sri
|
compute_cosinor())| Variable | Definition |
|---|---|
acrophase_time |
Clock time of the fitted rhythm's peak (HH:MM) |
acrophase_time_neg |
Same, mapped to [-12, 12] for circular-safe comparison |
MESOR |
Rhythm-adjusted mean |
amplitude |
Half the peak-to-trough distance of the fitted cosine |
period_min |
Fixed period used for the fit, in minutes (default 1440 = 24 h) |
| Variable | Definition |
|---|---|
tbt |
Total Bed Time (minutes) |
tst |
Total Sleep Time (minutes) |
waso |
Wake After Sleep Onset (minutes) |
sol |
Sleep Onset Latency (minutes) |
soi |
Sleep Offset Inertia (minutes) |
nw |
Number of awakenings |
eff |
Sleep efficiency โ TST / TBT |
sleep_type |
"main" or "secondary" (Vallim pipeline only) |
classify_pa_intensity() / classify_pa_counts())| Band | MET range |
|---|---|
light |
[0, 3) |
moderate |
[3, 6) |
vigorous |
[6, 9) |
very_vigorous |
[9, โ) |
Published coefficients and count-based cut-points for ActTrust/GT3X+, hip/wrist, are in pa_equations() -- see ?pa_equations for important generalisability caveats before applying these outside the source study's population (single lab-treadmill validation, N=56, healthy adults 18-35).
compute_lids())| Variable | Definition |
|---|---|
period_min |
Estimated ultradian cycle length (minutes) at peak Munich Rhythmicity Index |
amplitude |
Oscillation amplitude (LIDS units) |
offset |
Inactivity level at bout start |
slope_per_60min |
Linear trend in inactivity across the bout (LIDS units/hour) |
phase_rad |
Phase at bout start (radians; 0 = LIDS peak at onset) |
pearson_r, p_value, mri
|
Cosine-fit quality and the Munich Rhythmicity Index |
passes_quality_filter |
TRUE if the bout clears the Winnebeck/Hammad quality bar (pearson_r >= 0.4, p_value <= 0.05, 1 < offset < 99 by default) |
| Step | Algorithm | Reference | Validated |
|---|---|---|---|
| Off-wrist detection | Condor bimodal activity/temperature model | Condor Instruments | ActTrust โ |
| Sleep period detection | Crespo adaptive median filter | Crespo et al. (2012) | ActTrust โ |
| Nap detection | Crespo zero-proportion filter | Crespo et al. (2012) | ActTrust โ |
| Epoch scoring | Cole-Kripke weighted ZCM sum | Cole & Kripke (1992) | ActTrust โ |
| Episode classification | Vallim JRSV rule set (Fixes 25, 26a/b/c, 27, 29) | Vallim (2024) | ActTrust โ |
| Sleep summary | Day-type metric split (overall / workday / free day) | Vallim (2024) | ActTrust โ |
| Chronotype | CPD, MSW, MSF, MSFsc, SJL | Roenneberg et al. | ActTrust โ |
| Ultradian sleep cycles | LIDS sloped-cosine fit (MRI period scan) | Winnebeck et al. (2018); Hammad et al. (2026) | Not yet validated |
The CSPD pipeline has been validated epoch-for-epoch (0 / 76,196 mismatches) against the Condor circadiaBase Python reference. The Vallim pipeline has been validated at the classification level: all 52 main nights on the ActTrust validation recording classified identically to Julia Vallim's Python reference notebook. R is now the reference implementation for Fix 26c (fragment recovery), which correctly uses Cole-Kripke epoch scoring and proper temperature/light column names that were mismatched in the Python original.
zeitR/
โโโ R/
โ โโโ zeitR-package.R # package-level docs and Rcpp registration
โ โโโ read_acttrust.R # ActTrust file parser
โ โโโ read_axivity.R # Axivity .cwa bridge (via axR + compute_activity_counts())
โ โโโ read_actigraphy.R # device-agnostic wrapper, zeitr_study
โ โโโ prepare.R # temperature clamping, state column init
โ โโโ 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()
โ โโโ sleep_classify.R # Vallim pipeline: extract + classify episodes
โ โโโ sleep_metrics.R # compute_sleep_metrics(), compute_cpd_metrics()
โ โโโ cole_kripke.R # score_epochs_cole_kripke()
โ โโโ waso.R # compute_waso()
โ โโโ npcra.R # compute_npcra()
โ โโโ sri.R # compute_sri() (vallim/sadeh/ck/scripps/roenneberg)
โ โโโ lri.R # compute_lri()
โ โโโ cosinor.R # compute_cosinor()
โ โโโ study_summary.R # study_summary()
โ โโโ study_sleep_metrics.R # study_sleep_metrics()
โ โโโ pa_intensity.R # pa_equations(), estimate_ee(), classify_pa_intensity/counts()
โ โโโ raw_accelerometry.R # compute_activity_counts()
โ โโโ lids.R # lids_transform(), fit_lids(), detect_lids_bouts(), compute_lids(), study_lids_metrics()
โ โโโ plot_actogram.R # plot_actogram*(), actogram_colours()
โ โโโ circ_utils.R # circ_mean_h(), circ_sd_h()
โ โโโ params.R # acttrust_params()
โ โโโ pipeline.R # run_pipeline*(), run_pipeline_native*()
โ โโโ export.R # export_hypnogram()
โ โโโ utils.R # label_states() + Rcpp wrappers + helpers
โโโ src/
โ โโโ rolling_filters.cpp # Rcpp: rolling filters, diff5, Cole-Kripke
โโโ man/figures/
โ โโโ logo.svg
โ โโโ favicon.svg
โโโ vignettes/
โ โโโ getting-started.Rmd
โ โโโ npcra.Rmd
โ โโโ study-analysis.Rmd
โ โโโ actogram.Rmd # actogram plotting walkthrough
โ โโโ sleep-analysis.Rmd # CSPD pipeline walkthrough
โ โโโ vallim-pipeline.Rmd # Vallim pipeline walkthrough
โ โโโ holidays.Rmd # classifying weekends/public holidays
โ โโโ physical-activity.Rmd # PA intensity from ActTrust/GT3X+ counts
โ โโโ raw-accelerometry.Rmd # PIM/TAT/ZCM from raw triaxial acceleration
โ โโโ lids.Rmd # ultradian sleep-cycle dynamics (LIDS)
โโโ tests/testthat/
โโโ inst/extdata/ # validation fixtures
โโโ DESCRIPTION
โโโ NEWS.md
โโโ zeitR.Rproj
| Package | Type | Purpose |
|---|---|---|
| cli | Imports | Messages and progress |
| lubridate | Imports | Date/time handling |
| mclust | Imports | Bimodal GMM for off-wrist detection |
| Rcpp | Imports | C++ rolling filters and epoch scoring |
| tibble | Imports | Tidy data frames |
| tidyr | Imports | Pivoting and reshaping |
| ggplot2 | Suggests | Actogram and PA-intensity plots โ checked at runtime, not required for non-plotting functions |
| dplyr, forcats, rlang | Suggests | Used in vignettes and some helper functions |
| mrpheus | Suggests | Filter primitives (remove_dc(), bandpass_filter()) reused by compute_activity_counts(); cross-package dependency from the circadia-bio r-universe, not CRAN |
| axR | Suggests | Raw .cwa/AX6 file parsing (axivity_read_cwa()) reused by read_axivity(); cross-package dependency from the circadia-bio r-universe, not CRAN |
| future, future.apply | Suggests | Parallel batch processing (run_pipeline_batch(), run_pipeline_native_batch()) |
| vdiffr | Suggests | Visual regression tests for actogram plots |
| testthat, covr | Suggests | Test suite and coverage |
| withr | Suggests | Test-only: temporary files/mocked bindings cleanup in test-read-axivity.R
|
| knitr, rmarkdown, pkgdown | Suggests | Vignettes and documentation site |
| Role | Name | Affiliation |
|---|---|---|
| Author, maintainer | Lucas Franรงa | Northumbria University, Circadia Lab |
| Author | Mario Leocadio-Miguel | Northumbria University, Circadia Lab |
| Author | Julia Ribeiro da Silva Vallim | Universidade Federal de Sรฃo Paulo |
If you use zeitR in your research, please cite it:
@software{franca_zeitr_2026,
author = {Franรงa, Lucas and Leocadio-Miguel, Mario and Vallim, Julia Ribeiro da Silva},
title = {{zeitR}: Actigraphy Data Parsing and Analysis for R},
year = {2026},
version = {0.1.8},
doi = {10.5281/zenodo.21315925},
url = {https://github.com/circadia-bio/zeitR}
}
Released under the MIT License.
Copyright ยฉ Lucas Franรงa, Mario Leocadio-Miguel, 2026