Skip to contents

Getting started with zeitR

Source: vignettes/getting-started.Rmd
getting-started.Rmd

What is zeitR?

zeitR is an R package for importing, parsing, and analysing raw actigraphy recordings from wrist-worn devices. It reads device output files, runs a full rest-activity pipeline, and returns tidy data frames ready for chronobiological analysis.

zeitR is part of the Circadia Lab R ecosystem:

Package Purpose
zeitR Actigraphy parsing and rest-activity analysis
slumbR Sleep diary and questionnaire scoring
tallieR ScoreMe questionnaire exports

Installation 

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

Reading a single recording

The main entry point is read_actigraphy(). It accepts a path to a raw device file and returns a zeitr_recording object with two slots: $epochs (the epoch-level tibble) and $metadata (device and subject information from the file header).

rec <- read_actigraphy("recordings/P001.txt", tz = "America/Sao_Paulo")
rec
## zeitr_recording: P001
## * Device:   ActTrust2 (ID 828)
## * Firmware: 1.4
## * Interval: 60 s
## * Epochs:   10080
## * From:     2021-05-27 11:10:15
## * To:       2021-06-03 11:09:15

The $epochs tibble 

rec$epochs
## # A tibble: 10,080 x 8
##    datetime            activity int_temp ext_temp  ZCMn state offwrist sleep
##    <dttm>                 <dbl>    <dbl>    <dbl> <dbl> <dbl>    <dbl> <dbl>
##  1 2021-05-27 11:10:15     4856     24.2     23.9  0        0        0     0
##  2 2021-05-27 11:11:15     4483     24.4     24.1  1.5      0        0     0
##  3 2021-05-27 11:12:15      425     24.4     23.9  0.05     0        0     0
## ...

Each row is one epoch (60 seconds by default). The key columns are:

Column Description
datetime Epoch timestamp
activity PIM activity count
int_temp Internal (on-body) temperature, °C
ext_temp External (ambient) temperature, °C
ZCMn Normalised zero-crossing mode count
state Pipeline state (0 = wake, 1 = sleep, 4 = off-wrist, 7 = nap)
offwrist Off-wrist indicator (0.25 = off-wrist)
sleep Binary sleep/wake (1 = sleep)

The $metadata list 

rec$metadata
## $subject
## [1] "Julius"
## $device_model
## [1] "ActTrust2"
## $interval_s
## [1] 60
## ...

Running the full pipeline

run_pipeline() chains all analysis steps in one call: timestamp consistency check → prepare → off-wrist detection → sleep period detection (Crespo) → nap detection (Crespo) → WASO computation (Cole-Kripke).

result <- run_pipeline("recordings/P001.txt", tz = "America/Sao_Paulo")
result
## zeitr_result: P001
## * Source:  .../recordings/P001.txt
## * Epochs:  10080
## * Nights:  7
## * Issues:  0

Nightly sleep statistics 

result$nights
## # A tibble: 7 x 11
##   night is_nap bed_time            get_up_time          tbt   tst  waso   sol   soi    nw   eff
##   <int> <lgl>  <dttm>              <dttm>             <int> <dbl> <dbl> <int> <int> <int> <dbl>
## 1     1 FALSE  2021-05-27 22:04:15 2021-05-28 07:18:15  494   432    48    12     2    18  0.874
## ...

The metrics are:

Column 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)

Tip: Multiply epoch counts by result$data$metadata$interval_s / 60 to convert to minutes.

Timestamp issues 

result$issues

If no issues were found, this is a zero-row tibble. Issues are flagged for gaps > 120 s, backward jumps, and year artefacts (1970 or 2000).

Running pipeline steps individually

For more control, each step can be called separately. This is useful when you want to inspect intermediate outputs or customise algorithm parameters.

# 1. Read
rec  <- read_actigraphy("recordings/P001.txt", tz = "America/Sao_Paulo")

# 2. Check timestamps
issues <- check_consistency(rec$epochs)

# 3. Prepare (temperature clamping, state columns)
prep <- prepare_actigraphy(rec$epochs)

# 4. Off-wrist detection (Condor bimodal algorithm)
prep <- detect_offwrist_bimodal(prep)
sum(prep$state == 4)  # off-wrist epochs

# 5. Main sleep periods (Crespo, 2012)
prep <- detect_sleep_crespo(prep)

# 6. Naps (Crespo, 2012)
prep <- detect_naps_crespo(prep)

# 7. WASO + nightly stats (Cole-Kripke, 1992)
out <- compute_waso(prep)
out$nights

Next steps