This is the lookup for every metric actiRhythm emits in
its one-row summary: the columns of circadian.batch(), the
Summary sheet of circadian.workbook(), and
the slots of the individual result objects. Find any output here: what
it is, its formula or units, the range you should expect, the defining
reference, and where it lives in the result object.
The table below, the workbook’s Data Dictionary sheet, and
the package’s tests all read one file
(inst/extdata/metrics_dictionary.csv), so the codebook can
never drift from the code (a test checks that the documented metrics are
exactly those circadian.batch() returns). Individual result
objects carry further fields beyond this summary; see each function’s
help page (for example ?circadian.rhythm) for the complete
object.
Reading this codebook
Each metric is named exactly as it appears as a column of the
circadian.batch() data frame and the workbook
Summary sheet. The Output object
column shows where the same value lives when you call the producing
function directly: circadian.rhythm()$IS,
cosinor.analysis()$mesor, and so on. The
Reference column gives the citation key for the method;
full references are listed at the end. A metric whose
Range notes “requires sleep_state” or
“requires sleep_periods” is NA unless that
input is supplied.
Recording descriptors
| Metric | Definition | Formula / units | Range / interpretation | Reference | Output object |
|---|---|---|---|---|---|
n_epochs |
Number of epochs analysed in the recording | count | non-negative integer | summary$n_epochs |
|
epoch_length_s |
Epoch length of the recording | seconds | typically 15-60 s | summary$epoch_length_s |
Nonparametric metrics
Shape-free descriptors of the rest-activity rhythm, computed with no assumed waveform (Van Someren et al., 1999; Witting et al., 1990).
| Metric | Definition | Formula / units | Range / interpretation | Reference | Output object |
|---|---|---|---|---|---|
L5 |
Mean activity over the least-active 5 hours of the average day | activity counts per min | non-negative; lower = deeper rest | vansomeren1999 | circadian.rhythm()$L5 |
M10 |
Mean activity over the most-active 10 hours of the average day | activity counts per min | non-negative; higher = stronger active phase | vansomeren1999 | circadian.rhythm()$M10 |
RA |
Relative amplitude of the rest-activity rhythm | (M10 - L5) / (M10 + L5); unitless | 0 to 1; higher = stronger rhythm | vansomeren1999 | circadian.rhythm()$RA |
IS |
Interdaily stability: strength of coupling of the rhythm to the 24 h day | n*sum((xbar_h - xbar)^2) / (p*sum((x_i - xbar)^2)); unitless | 0 to 1; near 1 = highly stable, < 0.3 = weak | witting1990 | circadian.rhythm()$IS |
IV |
Intradaily variability: fragmentation of the rest-activity rhythm | n*sum((x_i - x_{i-1})^2) / ((n-1)*sum((x_i - xbar)^2)); unitless | 0 to ~2; ~0 = smooth sine, ~2 = noisy/fragmented | witting1990 | circadian.rhythm()$IV |
phi |
First-order (lag-1) autocorrelation of the hourly activity series (1 h lag) | unitless | about -1 to 1; higher = smoother, more predictable hour-to-hour | circadian.rhythm()$phi |
Cosinor and rhythmicity
The single-component cosinor and its zero-amplitude rhythmicity test (Cornelissen, 2014; Nelson et al., 1979).
| Metric | Definition | Formula / units | Range / interpretation | Reference | Output object |
|---|---|---|---|---|---|
cosinor_mesor |
MESOR: the rhythm-adjusted mean of the fitted 24 h cosine | activity counts | non-negative | cornelissen2014 | cosinor.analysis()$mesor |
cosinor_amplitude |
Amplitude: half the peak-to-trough extent of the fitted cosine | activity counts | non-negative; larger = stronger sinusoidal component | cornelissen2014 | cosinor.analysis()$amplitude |
cosinor_acrophase |
Acrophase: clock time of the cosine peak (circular) | clock hours (0-24) | 0 to 24 | cornelissen2014 | cosinor.analysis()$acrophase |
cosinor_r_squared |
Proportion of variance explained by the single cosine | unitless | 0 to 1 | cornelissen2014 | cosinor.analysis()$r_squared |
rhythm_F |
F statistic of the zero-amplitude (no-rhythm) test | unitless | non-negative; larger = stronger evidence of a rhythm | nelson1979 | rhythmicity.test()$F |
rhythm_df2 |
Denominator degrees of freedom of the rhythmicity F-test | count | non-negative | nelson1979 | rhythmicity.test()$df2 |
rhythm_p_value |
p-value of the zero-amplitude F-test | unitless | 0 to 1; < 0.05 = detectable rhythm | nelson1979 | rhythmicity.test()$p_value |
percent_rhythm |
Percent of variance the single cosine explains (100 * R-squared) | percent | 0 to 100 | cornelissen2014 | rhythmicity.test()$percent_rhythm |
rhythmic |
Whether a rhythm is detected at the 0.05 level | logical | TRUE / FALSE | nelson1979 | rhythmicity.test()$rhythmic |
Period and spectral
The endogenous period from the Lomb-Scargle (Lomb, 1976) and chi-square (Sokolove & Bushell, 1978) periodograms, with a circular block-bootstrap confidence interval (Politis & Romano, 1992).
| Metric | Definition | Formula / units | Range / interpretation | Reference | Output object |
|---|---|---|---|---|---|
period_tau |
Dominant free-running period from the Lomb-Scargle periodogram | hours | within the search band (default 18-30 h) | lomb1976 | circadian.period()$tau |
period_peak_power |
Lomb-Scargle spectral power at the dominant period | unitless | 0 to 1; higher = stronger periodicity | lomb1976 | circadian.period()$peak_power |
period_p_value |
False-alarm probability of the periodogram peak (Baluev) | unitless | 0 to 1; < 0.05 = significant period | baluev2008 | circadian.period()$p_value |
period_ci_lower |
Lower bound of the bootstrap period confidence interval | hours | typically <= period_tau | politis1992 | period.ci()$ci_lower |
period_ci_upper |
Upper bound of the bootstrap period confidence interval | hours | typically >= period_tau | politis1992 | period.ci()$ci_upper |
period_ci_se |
Bootstrap standard error of the period estimate | hours | non-negative | politis1992 | period.ci()$se |
chisq_period |
Dominant period from the chi-square (Sokolove-Bushell) periodogram | hours | within the search band | sokolove1978 | chi.sq.periodogram()$period |
chisq_Qp_peak |
Peak Qp statistic of the chi-square periodogram | unitless | non-negative; above threshold = significant | sokolove1978 | chi.sq.periodogram()$Qp_peak |
chisq_p_value |
Significance of the chi-square periodogram peak (Sidak-corrected) | unitless | 0 to 1 | sokolove1978 | chi.sq.periodogram()$p_value |
Fractal and nonlinear
Long-range correlation and complexity of the activity series (Costa et al., 2002; Kantelhardt et al., 2002; Peng et al., 1994).
| Metric | Definition | Formula / units | Range / interpretation | Reference | Output object |
|---|---|---|---|---|---|
dfa_alpha |
Overall detrended-fluctuation scaling exponent | unitless | ~0.5 = noise, ~1 = 1/f, > 1 = random-walk-like | peng1994 | fractal.dfa()$alpha |
dfa_alpha1 |
Short-time-scale DFA exponent (scales below the fixed breakpoint, default 90) | unitless | interpreted as for dfa_alpha | peng1994 | fractal.dfa()$alpha1 |
dfa_alpha2 |
Long-time-scale DFA exponent (scales above the fixed breakpoint, default 90) | unitless | interpreted as for dfa_alpha | peng1994 | fractal.dfa()$alpha2 |
mfdfa_h2 |
Generalized Hurst exponent at q = 2 (equals the DFA exponent) | unitless | ~0.5 to 1.5 | kantelhardt2002 | mfdfa()$alpha_dfa |
mfdfa_width |
Width of the multifractal singularity spectrum | unitless | non-negative; wider = more multifractal | kantelhardt2002 | mfdfa()$width |
mse_area |
Sum of sample entropy across scales (complexity index) | unitless | non-negative; higher = more complex | costa2002 | multiscale.entropy()$area |
mse_slope |
Least-squares slope of sample entropy across scales (package trend summary) | unitless | sign indicates rising or falling complexity with scale | multiscale.entropy()$slope |
Rest-activity transitions
State-transition rates and probabilities that capture fragmentation a single amplitude cannot (Danilevicz et al., 2024; Lim et al., 2011).
| Metric | Definition | Formula / units | Range / interpretation | Reference | Output object |
|---|---|---|---|---|---|
kRA |
Rest-to-active transition rate over the LOWESS plateau | per epoch | 0 to 1; typically < 0.5; higher = more fragmented rest | lim2011 | state.transitions()$kRA |
kAR |
Active-to-rest transition rate over the LOWESS plateau | per epoch | 0 to 1; typically < 0.5; higher = more fragmented activity | lim2011 | state.transitions()$kAR |
pRA |
Overall rest-to-active rate (reciprocal mean rest-bout length) | unitless | 0 to 1 | danilevicz2024 | state.transitions()$pRA |
pAR |
Overall active-to-rest rate (reciprocal mean active-bout length) | unitless | 0 to 1 | danilevicz2024 | state.transitions()$pAR |
Sleep timing and regularity
Metrics that need a sleep label or sleep periods: the Sleep Regularity Index, social jet lag, and LIDS (Phillips et al., 2017; Roenneberg et al., 2012; Winnebeck et al., 2018; Wittmann et al., 2006).
| Metric | Definition | Formula / units | Range / interpretation | Reference | Output object |
|---|---|---|---|---|---|
SRI |
Sleep Regularity Index: how consistently the sleep/wake state repeats 24 h apart (requires sleep_state) | 200*P - 100, where P is the fraction of epoch pairs 24 h apart in the same state; index points | -100 to 100; 100 = perfectly regular, 0 = random, higher = more regular | phillips2017 | sleep.regularity.index() |
social_jet_lag_hours |
Social jet lag: mid-sleep difference between free and work days (requires sleep_periods) | hours | typically 0 to 3; larger = greater misalignment | roenneberg2012 | social.jet.lag()$social_jet_lag_hours |
MSW |
Mid-sleep on work days | clock hours (0-24) | 0 to 24 | wittmann2006 | social.jet.lag()$MSW |
MSF |
Mid-sleep on free days | clock hours (0-24) | 0 to 24 | wittmann2006 | social.jet.lag()$MSF |
lids_period_min |
Mean Locomotor Inactivity During Sleep ultradian period (requires sleep_periods) | minutes | typically ~95 to 130 min (median ~110) | winnebeck2018 | lids()$mean_period_min |
lids_MRI |
Mean Munich Rhythmicity Index of the LIDS cycles (requires sleep_periods) | unitless | >=0 on the 0-100 LIDS scale; higher = stronger ultradian rhythm | winnebeck2018 | lids()$mean_MRI |
References
Full citations for the method keys in the table above: (Baluev, 2008; Cornelissen, 2014; Costa et al., 2002; Danilevicz et al., 2024; Kantelhardt et al., 2002; Lim et al., 2011; Lomb, 1976; Nelson et al., 1979; Peng et al., 1994; Phillips et al., 2017; Politis & Romano, 1992; Roenneberg et al., 2012; Sokolove & Bushell, 1978; Van Someren et al., 1999; Winnebeck et al., 2018; Witting et al., 1990; Wittmann et al., 2006).
Baluev, R. V. (2008). Assessing the statistical significance of
periodogram peaks. Monthly Notices of the Royal Astronomical
Society, 385(3), 1279–1285. https://doi.org/10.1111/j.1365-2966.2008.12689.x
Cornelissen, G. (2014). Cosinor-based rhythmometry. Theoretical
Biology and Medical Modelling, 11, 16. https://doi.org/10.1186/1742-4682-11-16
Costa, M., Goldberger, A. L., & Peng, C.-K. (2002). Multiscale
entropy analysis of complex physiologic time series. Physical Review
Letters, 89(6), 068102. https://doi.org/10.1103/PhysRevLett.89.068102
Danilevicz, I. M., Hees, V. T. van, Heide, F. van der, Jacob, L.,
Landre, B., Benadjaoud, M. A., & Sabia, S. (2024). Measures of
fragmentation of rest activity patterns: Mathematical properties and
interpretability based on accelerometer real life data. BMC Medical
Research Methodology, 24, 132. https://doi.org/10.1186/s12874-024-02255-w
Kantelhardt, J. W., Zschiegner, S. A., Koscielny-Bunde, E., Havlin, S.,
Bunde, A., & Stanley, H. E. (2002). Multifractal detrended
fluctuation analysis of nonstationary time series. Physica A:
Statistical Mechanics and Its Applications, 316(1-4),
87–114. https://doi.org/10.1016/S0378-4371(02)01383-3
Lim, A. S. P., Yu, L., Costa, M. D., Buchman, A. S., Bennett, D. A.,
Leurgans, S. E., & Saper, C. B. (2011). Quantification of the
fragmentation of rest-activity patterns in elderly individuals using a
state transition analysis. Sleep, 34(11), 1569–1581.
https://doi.org/10.5665/sleep.1400
Lomb, N. R. (1976). Least-squares frequency analysis of unequally spaced
data. Astrophysics and Space Science, 39(2), 447–462.
https://doi.org/10.1007/BF00648343
Nelson, W., Tong, Y. L., Lee, J. K., & Halberg, F. (1979). Methods
for cosinor-rhythmometry. Chronobiologia, 6(4),
305–323.
Peng, C. K., Buldyrev, S. V., Havlin, S., Simons, M., Stanley, H. E.,
& Goldberger, A. L. (1994). Mosaic organization of DNA
nucleotides. Physical Review E, 49(2), 1685–1689. https://doi.org/10.1103/PhysRevE.49.1685
Phillips, A. J. K., Clerx, W. M., O’Brien, C. S., Sano, A., Barger, L.
K., Picard, R. W., Lockley, S. W., Klerman, E. B., & Czeisler, C. A.
(2017). Irregular sleep/wake patterns are associated with poorer
academic performance and delayed circadian and sleep/wake timing.
Scientific Reports, 7(1), 3216. https://doi.org/10.1038/s41598-017-03171-4
Politis, D. N., & Romano, J. P. (1992). A circular block-resampling
procedure for stationary data. In R. LePage & L. Billard (Eds.),
Exploring the limits of bootstrap (pp. 263–270). Wiley.
Roenneberg, T., Allebrandt, K. V., Merrow, M., & Vetter, C. (2012).
Social jetlag and obesity. Current Biology, 22(10),
939–943. https://doi.org/10.1016/j.cub.2012.03.038
Sokolove, P. G., & Bushell, W. N. (1978). The chi square
periodogram: Its utility for analysis of circadian rhythms. Journal
of Theoretical Biology, 72(1), 131–160. https://doi.org/10.1016/0022-5193(78)90022-X
Van Someren, E. J. W., Swaab, D. F., Colenda, C. C., Cohen, W., McCall,
W. V., & Rosenquist, P. B. (1999). Bright light therapy: Improved
sensitivity to its effects on rest-activity rhythms in
Alzheimer patients by application of nonparametric methods.
Chronobiology International, 16(4), 505–518. https://doi.org/10.3109/07420529908998724
Winnebeck, E. C., Fischer, D., Leise, T., & Roenneberg, T. (2018).
Dynamics and ultradian structure of human sleep in real life.
Current Biology, 28(1), 49–59. https://doi.org/10.1016/j.cub.2017.11.063
Witting, W., Kwa, I. H., Eikelenboom, P., Mirmiran, M., & Swaab, D.
F. (1990). Alterations in the circadian rest-activity rhythm in aging
and Alzheimer’s disease. Biological
Psychiatry, 27(6), 563–572. https://doi.org/10.1016/0006-3223(90)90523-5
Wittmann, M., Dinich, J., Merrow, M., & Roenneberg, T. (2006).
Social jetlag: Misalignment of biological and social time.
Chronobiology International, 23(1-2), 497–509. https://doi.org/10.1080/07420520500545979