Package 'actiRhythm'

Description

Generates colors from the actiRhythm palettes for visualizations. These colors match the CSS design system.

Usage

actiRhythm_colors(n = NULL, type = "categorical")

Arguments

Value

A character vector of hex color codes

Examples

actiRhythm_colors(4)

library(ggplot2)
ggplot(mtcars, aes(wt, mpg, color = factor(cyl))) +
  geom_point() +
  scale_color_manual(values = actiRhythm_colors(3))

Description

The Activity Balance Index (Danilevicz et al. 2024), a 0 to 1 transform of a detrended fluctuation analysis scaling exponent that peaks at the healthy $\alpha = 1$ (1/f) balance: $ABI(\alpha) = \exp(-|\alpha - 1| / e^{-2}) = \exp(-e^{2}\,|\alpha - 1|)$.

Usage

activity.balance.index(x)

Arguments

Value

If x is numeric, the scalar ABI. If x is a fractal object, a list with ABI_overall, ABI_short, ABI_long.

References

Danilevicz IM, van Hees VT, van der Heide F, Jacob L, Landre B, Benadjaoud MA, 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. doi:10.1186/s12874-024-02255-w.

Examples

activity.balance.index(1.0)   # perfect 1/f balance -> 1
activity.balance.index(0.7)

Description

The least-active LX and most-active MX periods for arbitrary window lengths, generalizing L5 and M10 (Van Someren et al. 1999). For each window the function returns the mean activity over the window and its onset and midpoint clock times. A fixed L5/M10 pair does not give these phase markers.

Usage

activity.extrema(counts, timestamps, windows = c(5, 10))

Arguments

Value

An object of class actiRhythm_mxlx: a data frame with, for each window, the least- and most-active mean level, onset hour, and midpoint hour. Never errors.

References

Van Someren EJW, Swaab DF, Colenda CC, Cohen W, McCall WV, Rosenquist PB (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. doi:10.3109/07420529908998724.

Examples

ts <- seq(as.POSIXct("2024-01-01", tz = "UTC"), by = 60, length.out = 4 * 1440)
h  <- as.numeric(format(ts, "%H"))
activity.extrema(ifelse(h >= 23 | h < 7, 5, 300), ts, windows = c(5, 8, 10))

Description

Finds the daily activity onset and offset by a relative-difference contrast on the averaged 24-hour profile: the onset is where mean activity rises most sharply (the relative difference of the window after versus before is largest) and the offset is where it falls most sharply. These are non-cosinor, non-changepoint phase markers, a normalized-contrast edge detector on the daily profile rather than a published actigraphy algorithm.

Usage

activity.onset.offset(counts, timestamps, window_hours = 6)

Arguments

Value

An object of class actiRhythm_aont: onset_h and offset_h (clock hours) and the relative-difference profile. Never errors.

Examples

ts <- seq(as.POSIXct("2024-01-01", tz = "UTC"), by = 60, length.out = 4 * 1440)
h  <- as.numeric(format(ts, "%H"))
activity.onset.offset(ifelse(h >= 23 | h < 7, 5, 300), ts)

Description

Extracts activity counts, timestamps, steps, and inclinometer data (if available) from AGD file data. Inclinometer data can be used to enhance sleep detection for AGD files that lack raw acceleration.

Usage

agd.counts(agd_data, convert.timestamps = TRUE, include_inclinometer = TRUE)

Arguments

Details

Inclinometer data is particularly useful for sleep detection in AGD files:

• inclineLying = 1 indicates the device detected lying posture

• Combined with low activity (Cole-Kripke sleep), this sharpens specificity

• Not all AGD files contain inclinometer data (depends on ActiLife processing settings)

Value

Data frame with counts per minute, timestamps, and optional inclinometer data:

• timestamp - POSIXct timestamp (if convert.timestamps = TRUE)

• axis1 - Vertical axis counts (Y-axis)

• axis2 - Horizontal axis counts (X-axis)

• axis3 - Anterior-posterior axis counts (Z-axis)

• steps - Step counts

• lux - Light intensity (if available)

• inclineOff - Off-body indicator (if available)

• inclineStanding - Standing indicator (if available)

• inclineSitting - Sitting indicator (if available)

• inclineLying - Lying indicator (if available)

Description

Estimates per-axis gain and offset corrections by the van Hees et al. (2014) method: during non-movement windows the acceleration vector should lie on the 1 g sphere, so gain/offset are fit by iteratively projecting non-movement window means onto the closest point of the unit sphere. Apply as (raw - offset) * scale.

Usage

auto.calibrate(
  xyz,
  fs,
  sphere_crit = 0.3,
  sd_crit = 0.013,
  max_iter = 1000,
  tol = 1e-10
)

Arguments

Value

A list with scale and offset (length-3), the calibration error before and after (cal_error_start, cal_error_end, mean absolute deviation from 1 g), npoints, a calibrated flag, and a reason string describing the outcome. When there is too little non-movement data the identity correction is returned with calibrated = FALSE.

References

van Hees VT, Fang Z, Langford J, Assah F, Mohammad A, da Silva ICM, Trenell MI, White T, Wareham NJ, Brage S (2014). “Autocalibration of accelerometer data for free-living physical activity assessment using local gravity and temperature: an evaluation on four continents.” Journal of Applied Physiology, 117(7), 738–744. doi:10.1152/japplphysiol.00421.2014.

Examples

# Recover a known per-axis gain and offset from non-movement windows
set.seed(1)
u <- matrix(rnorm(40 * 3), 40, 3); u <- u / sqrt(rowSums(u^2))   # sphere directions
raw <- do.call(rbind, lapply(seq_len(40), function(i)
  matrix(rep(u[i, ] / c(1.03, 0.97, 1.01) + c(0.04, -0.03, 0.02), each = 300),
         300, 3) + rnorm(900, 0, 0.004)))
auto.calibrate(data.frame(x = raw[, 1], y = raw[, 2], z = raw[, 3]), fs = 30)$scale

Description

Reads a raw Axivity (.cwa) accelerometer file and converts it to ActiGraph-equivalent activity counts via the agcounts implementation of the ActiGraph count algorithm (Neishabouri 2022). Requires the GGIRread and agcounts packages.

Usage

axivity.counts(path, epoch = 60, lfe = FALSE, tz = "UTC")

Arguments

Value

Data frame with time, axis1, axis2, axis3 and vm, one row per epoch (the same shape as gt3x.counts).

Cross-brand counts

These are an approximation of ActiGraph counts, not native ActiGraph output. Axivity-to-count conversion has been directly validated (Brond et al. 2017). The result is appropriate for the relative and normalized circadian metrics in this package (IS, IV, RA, L5, M10, SRI); it should not be used to apply ActiGraph intensity cut-points or to compare absolute counts across device brands.

References

Neishabouri A, Nguyen J, Samuelsson J, Guthrie T, Biggs M, Wyatt J, Cross D, Karas M, Migueles JH, Khan S, Guo CC (2022). “Quantification of acceleration as activity counts in ActiGraph wearable.” Scientific Reports, 12, 11958. doi:10.1038/s41598-022-16003-x.

Brond JC, Andersen LB, Arvidsson D (2017). “Generating ActiGraph counts from raw acceleration recorded by an alternative monitor.” Medicine & Science in Sports & Exercise, 49(11), 2351–2360. doi:10.1249/MSS.0000000000001344.

See Also

geneactiv.counts, gt3x.counts, read.raw

Description

Backend Information

Usage

backend_info()

Value

Invisible list with backend info

Description

Estimates the dominant period of an activity time series with the Sokolove-Bushell (1978) chi-square periodogram, the periodogram most widely used in chronobiology and actigraphy. It pairs with the Lomb-Scargle estimator in circadian.period: Lomb-Scargle is the least-squares spectral method for unevenly sampled data; the chi-square periodogram is the analysis-of-variance method for regularly sampled data and reports a significance threshold.

Usage

chi.sq.periodogram(
  counts,
  timestamps,
  from = 18,
  to = 30,
  alpha = 0.05,
  epoch_length = NULL
)

Arguments

Details

For each trial period $P$ (an integer number of epochs) the series is folded into $P$ phase bins over $K = \lfloor N/P \rfloor$ complete cycles and the statistic

$Q_P = \frac{K\,N \sum_{h=1}^{P}(\bar{A}_h - \bar{A})^2}{\sum_{i=1}^{N}(A_i - \bar{A})^2}$

is computed, where $\bar{A}_h$ is the mean at phase $h$ and $\bar{A}$ the grand mean over the $N = KP$ retained points. Under the null hypothesis of no rhythm at $P$, $Q_P$ follows a chi-square distribution with $P-1$ degrees of freedom, giving the significance line $\chi^2_{P-1,\,1-\alpha}$. The estimated period is the $P$ maximising $Q_P$ within the search window.

Value

A named list with period (hours, the $Q_P$ peak), Qp_peak, p_value (family-wise Sidak p-value of the peak across the scanned periods), significant (logical, p_value < alpha), scanned (trial periods in hours), Qp (the periodogram aligned to scanned), critical (the per-period chi-square threshold), epoch_length and alpha. On insufficient/degenerate data the same shape is returned with period/Qp_peak NA and empty vectors; the function never throws.

References

Sokolove PG, Bushell WN (1978). “The chi square periodogram: its utility for analysis of circadian rhythms.” Journal of Theoretical Biology, 72(1), 131–160. doi:10.1016/0022-5193(78)90022-X.

Refinetti R, Cornelissen G, Halberg F (2007). “Procedures for numerical analysis of circadian rhythms.” Biological Rhythm Research, 38(4), 275–325. doi:10.1080/09291010600903692.

Sidak Z (1967). “Rectangular confidence regions for the means of multivariate normal distributions.” Journal of the American Statistical Association, 62(318), 626–633. doi:10.1080/01621459.1967.10482935.

See Also

circadian.period for the Lomb-Scargle estimator.

Description

Complete Circadian Analysis

Usage

circadian_cpp(minute_data, hours_per_day = 24L, start_minute = 0L)

Arguments

Value

List with L5, M10, RA, IS, IV, phi

Description

Non-parametric methods for characterizing 24-hour activity patterns.

References

Witting W, Kwa IH, Eikelenboom P, Mirmiran M, Swaab DF (1990). “Alterations in the circadian rest-activity rhythm in aging and Alzheimer's disease.” Biological Psychiatry, 27(6), 563–572. doi:10.1016/0006-3223(90)90523-5.

Van Someren EJW, Swaab DF, Colenda CC, Cohen W, McCall WV, Rosenquist PB (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. doi:10.3109/07420529908998724.

Phillips AJK, Clerx WM, O'Brien CS, Sano A, Barger LK, Picard RW, Lockley SW, Klerman EB, Czeisler CA (2017). “Irregular sleep/wake patterns are associated with poorer academic performance and delayed circadian and sleep/wake timing.” Scientific Reports, 7(1), 3216. doi:10.1038/s41598-017-03171-4.

Wittmann M, Dinich J, Merrow M, Roenneberg T (2006). “Social jetlag: misalignment of biological and social time.” Chronobiology International, 23(1-2), 497–509. doi:10.1080/07420520500545979.

Description

Two nonlinear complexity and scaling metrics for accelerometer activity time series: Detrended Fluctuation Analysis (DFA) and Multiscale Sample Entropy (MSE). Both run in base R (only stats is used) so they add no new runtime dependency. They measure the temporal structure (long-range correlations and information-theoretic complexity) of minute-level activity counts, alongside the amplitude- and timing-based circadian metrics in circadian.rhythm.

References

Peng CK, Buldyrev SV, Havlin S, Simons M, Stanley HE, Goldberger AL (1994). “Mosaic organization of DNA nucleotides.” Physical Review E, 49(2), 1685–1689. doi:10.1103/PhysRevE.49.1685.

Hu K, Ivanov PC, Chen Z, Carpena P, Stanley HE (2001). “Effect of trends on detrended fluctuation analysis.” Physical Review E, 64(1), 011114. doi:10.1103/PhysRevE.64.011114.

Hu K, Van Someren EJW, Shea SA, Scheer FAJL (2009). “Reduction of scale invariance of activity fluctuations with aging and Alzheimer's disease: Involvement of the circadian pacemaker.” Proceedings of the National Academy of Sciences, 106(8), 2490–2494. doi:10.1073/pnas.0806087106.

Richman JS, Moorman JR (2000). “Physiological time-series analysis using approximate entropy and sample entropy.” American Journal of Physiology - Heart and Circulatory Physiology, 278(6), H2039–H2049. doi:10.1152/ajpheart.2000.278.6.H2039.

Costa M, Goldberger AL, Peng C (2002). “Multiscale entropy analysis of complex physiologic time series.” Physical Review Letters, 89(6), 068102. doi:10.1103/PhysRevLett.89.068102.

Costa M, Goldberger AL, Peng C (2005). “Multiscale entropy analysis of biological signals.” Physical Review E, 71(2), 021906. doi:10.1103/PhysRevE.71.021906.

Description

Estimates the dominant (endogenous) circadian PERIOD (tau) of an activity time series using the Lomb-Scargle periodogram. Unlike the classical Fast Fourier Transform (FFT), the Lomb-Scargle method does not require evenly sampled data, so it correctly handles the irregular and gappy sampling that results from non-wear periods, dropped epochs, or mixed epoch lengths in accelerometer recordings.

Description

ggplot2 visualizations for the circadian / chronobiology metrics produced by actiRhythm. These functions are thin plotting wrappers around the existing analytic engines and add no new fitting logic:

• plot_periodogram draws the Lomb-Scargle periodogram and highlights the endogenous period estimated by circadian.period.

• plot_extended_cosinor overlays the Marler extended (anti-logistic) cosinor fit from cosinor.antilogistic and the ordinary cosinor from cosinor.analysis on the averaged 24-hour activity profile.

• plot_dfa draws the detrended-fluctuation log-log scaling plot from fractal.dfa.

Every function returns a ggplot object, never errors on degenerate or insufficient input (it returns an annotated empty plot instead), and falls back to ggplot2::theme_minimal() when the package theme helpers are unavailable.

References

Lomb NR (1976). “Least-squares frequency analysis of unequally spaced data.” Astrophysics and Space Science, 39(2), 447–462. doi:10.1007/BF00648343.

Scargle JD (1982). “Studies in astronomical time series analysis. II. Statistical aspects of spectral analysis of unevenly spaced data.” The Astrophysical Journal, 263, 835–853. doi:10.1086/160554.

Marler MR, Gehrman P, Martin JL, Ancoli-Israel S (2006). “The sigmoidally transformed cosine curve: a mathematical model for circadian rhythms with symmetric non-sinusoidal shapes.” Statistics in Medicine, 25(22), 3893–3904. doi:10.1002/sim.2466.

Peng CK, Buldyrev SV, Havlin S, Simons M, Stanley HE, Goldberger AL (1994). “Mosaic organization of DNA nucleotides.” Physical Review E, 49(2), 1685–1689. doi:10.1103/PhysRevE.49.1685.

Description

Reads a set of ActiGraph .agd files, runs the full circadian analysis on each, and returns one combined summary row per file, the package equivalent of uploading a batch of files. Files that fail to read or analyse are reported in an error column rather than aborting the run. Optionally writes a single Excel workbook whose Summary sheet has one row per file.

Usage

circadian.batch(
  files,
  file = NULL,
  metric = c("axis1", "vm"),
  include_period_ci = FALSE,
  n_boot = 200,
  epoch_length = NULL,
  verbose = TRUE
)

Arguments

Value

A data frame with one row per file (a file column, an error column, and every summary metric). Returned invisibly when a workbook file is written.

See Also

circadian.workbook

Examples

# Pass a folder to analyse a whole batch; a single file is used here.
batch <- circadian.batch(example_agd(), verbose = FALSE)
batch[, c("file", "IS", "IV", "RA", "rhythm_p_value")]

Description

The intraday nonparametric metrics computed for each day separately, showing within-recording drift that the pooled values hide. Interdaily stability is a between-day measure and so is not a per-day quantity; the per-day table reports L5, M10, their onset times, relative amplitude, and intradaily variability (Goncalves et al. 2014).

Usage

circadian.daily(counts, timestamps, min_hours = 12)

Arguments

Value

An object of class actiRhythm_daily: a daily data frame, one row per day. Never errors.

References

Goncalves BSB, Cavalcanti PRA, Tavares GR, Campos TF, Araujo JF (2014). “Nonparametric methods in actigraphy: an update.” Sleep Science, 7(3), 158–164. doi:10.1016/j.slsci.2014.09.013.

Examples

ts <- seq(as.POSIXct("2024-01-01", tz = "UTC"), by = 60, length.out = 4 * 1440)
h  <- as.numeric(format(ts, "%H"))
circadian.daily(ifelse(h >= 23 | h < 7, 5, 300), ts)

Description

Decomposes the activity series into intrinsic mode functions by empirical mode decomposition, a data-adaptive, nonlinear alternative to the linear SSA decomposition (Huang et al. 1998). The intrinsic mode function whose period is nearest 24 hours is taken as the circadian component. Optional ensemble EMD adds noise to reduce mode mixing (Wu and Huang 2009).

Usage

circadian.emd(
  counts,
  timestamps,
  max_imf = 10L,
  ensemble = 1L,
  noise_sd = 0.2,
  period_range = c(20, 28),
  epoch_length = 60,
  seed = NULL
)

Arguments

Value

An object of class actiRhythm_emd: the IMF matrix, the residual trend, per-IMF period and variance share, the circadian IMF index, and the reconstruction error. The first and last epochs are unreliable (the spline envelopes pin the IMFs near zero at the edges), so read the instantaneous series away from the boundary. Never errors.

References

Huang NE, Shen Z, Long SR, Wu MC, Shih HH, Zheng Q, Yen NC, Tung CC, Liu HH (1998). “The empirical mode decomposition and the Hilbert spectrum for nonlinear and non-stationary time series analysis.” Proceedings of the Royal Society A, 454(1971), 903–995. doi:10.1098/rspa.1998.0193.

Wu Z, Huang NE (2009). “Ensemble empirical mode decomposition: a noise-assisted data analysis method.” Advances in Adaptive Data Analysis, 1(1), 1–41. doi:10.1142/S1793536909000047.

See Also

hilbert.huang, circadian.ssa

Examples

ts <- seq(as.POSIXct("2024-01-01", tz = "UTC"), by = 600, length.out = 6 * 144)
th <- as.numeric(difftime(ts, ts[1], units = "hours"))
circadian.emd(100 + 60 * cos(2 * pi * th / 24), ts, epoch_length = 600)

Description

Fits the averaged 24-hour activity profile with a periodic basis expansion (Fourier by default, B-spline alternative) by weighted least squares, giving a smooth functional form of the daily activity pattern. The single-component cosinor is the one-harmonic special case; adding harmonics fits the non-sinusoidal shape of a real rest-activity profile. This follows the functional form of Wang et al. (2011), as implemented for actigraphy by pyActigraphy.

Usage

circadian.flm(
  counts,
  timestamps,
  basis = c("fourier", "bspline"),
  n_harmonics = 4,
  nbasis = 9,
  spline_order = 4,
  period = 24,
  wear_time = NULL,
  min_valid_hours = 10,
  weights = c("n", "none"),
  n_eval = 1440
)

Arguments

Value

An object of class actiRhythm_flm: the fitted coefficients, the smooth daily curve (smooth_curve), the fitted profile, per-harmonic amplitudes and acrophases (harmonics, Fourier only), the peak and trough, and the fit statistics (r_squared, aic, f_statistic, p_value). The function never errors; on insufficient data it returns the same structure with r_squared NA.

References

Wang J, Xian H, Licis A, Deych E, Ding J, McLeland J, Toedebusch C, Li T, Duntley S, Shannon W (2011). “Measuring the impact of apnea and obesity on circadian activity patterns using functional linear modeling of actigraphy data.” Journal of Circadian Rhythms, 9, 11. doi:10.1186/1740-3391-9-11.

Ramsay JO, Silverman BW (2005). Functional Data Analysis, 2nd edition. Springer. doi:10.1007/b98888.

Hammad G, Reyt M, Beliy N, Baillet M, Deantoni M, Lesoinne A, Muto V, Schmidt C (2021). “pyActigraphy: open-source python package for actigraphy data visualization and analysis.” PLOS Computational Biology, 17(10), e1009514. doi:10.1371/journal.pcbi.1009514.

See Also

cosinor.analysis, circadian.ssa

Examples

ts <- seq(as.POSIXct("2024-01-01", tz = "UTC"), by = 60, length.out = 4 * 1440)
h  <- as.numeric(format(ts, "%H")) + as.numeric(format(ts, "%M")) / 60
counts <- 100 + 60 * cos(2 * pi * (h - 14) / 24) + 25 * cos(2 * pi * (h - 6) / 12)
circadian.flm(counts, ts)

Description

Computes interdaily stability at several within-day bin resolutions. IS is classically reported at 60-min bins, but finer bins (30/15 min) capture higher-frequency day-to-day regularity. For each bin width, IS = (N * sum_h (xbar_h - xbar)^2) / (p * sum_i (x_i - xbar)^2) where p is bins-per-day, xbar_h the mean for bin-of-day h, and N the total number of bins.

Usage

circadian.is.multiscale(
  counts,
  timestamps,
  bin_minutes = (1:60)[1440L%%(1:60) == 0L]
)

Arguments

Value

An object of class actiRhythm_ism: a per-bin IS table and the averaged ISm.

References

Witting W, Kwa IH, Eikelenboom P, Mirmiran M, Swaab DF (1990). “Alterations in the circadian rest-activity rhythm in aging and Alzheimer's disease.” Biological Psychiatry, 27(6), 563–572. doi:10.1016/0006-3223(90)90523-5.

Goncalves BSB, Cavalcanti PRA, Tavares GR, Campos TF, Araujo JF (2014). “Nonparametric methods in actigraphy: an update.” Sleep Science, 7(3), 158–164. doi:10.1016/j.slsci.2014.09.013.

Description

Percentile bootstrap confidence interval for the mean daily onset time of a circadian phase marker (e.g. L5 or M10), using circular resampling of the per-day onsets.

Usage

circadian.onset.ci(onset_hours, level = 0.95, n_boot = 2000)

Arguments

Value

List with mean_onset, ci_lower, ci_upper (decimal hours) and n_days.

Description

Computes the Lomb-Scargle periodogram of an activity counts series sampled at the supplied timestamps and returns the period (tau, in hours) of the strongest spectral peak within the search window [from, to]. The Lomb-Scargle method (Lomb 1976; Scargle 1982) is the least-squares-equivalent spectral estimator for unevenly sampled time series and is therefore appropriate for actigraphy data containing gaps, which the FFT cannot accommodate.

Usage

circadian.period(counts, timestamps, from = 18, to = 30, ofac = 4)

Arguments

Details

Processing steps:

1. Timestamps are converted to hours since the first sample (t_hours = (as.numeric(timestamps) - min) / 3600).

2. Pairs with a missing count or a missing/non-finite time are dropped.

3. Two guards are applied so the estimate is never based on insufficient data: the recording must span at least 2 days (otherwise a 18-30 h period cannot be resolved) and at least 10 non-NA observations must remain.

4. The standard-normalized Lomb-Scargle periodogram is evaluated over the period window. Its strongest peak gives the period (hours), and the Baluev (2008) analytic false-alarm probability gives the p-value.

The Lomb-Scargle periodogram is chosen specifically because actigraphy series are rarely gap-free: the FFT assumes uniform sampling, whereas Lomb-Scargle fits sinusoids by least squares at each trial frequency and is unbiased for irregular sampling.

Value

A named list with elements:

tau

Numeric. Period (hours) of the strongest Lomb-Scargle peak in [from, to], i.e. the estimated endogenous circadian period. NA_real_ when the data are insufficient.

peak_power

Numeric. Normalized power of that peak (the Lomb-Scargle peak statistic). NA_real_ when insufficient.

p_value

Numeric. P-value of the peak under the null hypothesis of Gaussian noise (Baluev 2008 analytic false-alarm probability). NA_real_ when insufficient.

oversampling

The ofac oversampling factor used.

n_used

Integer. Number of non-NA observations actually passed to the periodogram (NA_integer_ when not run).

span_days

Numeric. Total recording span in days (max minus min timestamp), used for the >= 2-day guard.

scanned

Numeric vector of trial periods (hours) of the full Lomb-Scargle spectrum (numeric(0) when not run).

power

Numeric vector of standard-normalized Lomb-Scargle power, aligned to scanned (numeric(0) when not run).

On any edge case (too few points, too short a span, degenerate input, or an internal numerical failure) the function returns this same structure with tau, peak_power and p_value set to NA; it never throws.

References

Lomb NR (1976). “Least-squares frequency analysis of unequally spaced data.” Astrophysics and Space Science, 39(2), 447–462. doi:10.1007/BF00648343.

Scargle JD (1982). “Studies in astronomical time series analysis. II. Statistical aspects of spectral analysis of unevenly spaced data.” The Astrophysical Journal, 263, 835–853. doi:10.1086/160554.

Ruf T (1999). “The Lomb-Scargle periodogram in biological rhythm research: analysis of incomplete and unequally spaced time-series.” Biological Rhythm Research, 30(2), 178–201. doi:10.1076/brhm.30.2.178.1422.

Baluev RV (2008). “Assessing the statistical significance of periodogram peaks.” Monthly Notices of the Royal Astronomical Society, 385(3), 1279–1285. doi:10.1111/j.1365-2966.2008.12689.x.

Refinetti R, Cornelissen G, Halberg F (2007). “Procedures for numerical analysis of circadian rhythms.” Biological Rhythm Research, 38(4), 275–325. doi:10.1080/09291010600903692.

See Also

cosinor.analysis for parametric (fixed-period) rhythm estimation, circadian.rhythm for non-parametric L5/M10/IS/IV metrics.

Examples

# Seven days of minute-level data with a 24 h rhythm
t_hours <- seq(0, 7 * 24 - 1/60, by = 1/60)
ts <- as.POSIXct("2024-01-01 00:00:00") + t_hours * 3600
counts <- 100 + 80 * cos(2 * pi * (t_hours - 8) / 24) + rnorm(length(t_hours), 0, 5)
circadian.period(counts, ts)$tau   # about 24.0

Description

Computes the circadian quotient (amplitude divided by MESOR) and a cosinor relative amplitude (amplitude divided by the overall mean) from a cosinor result. The circadian quotient is a dimensionless measure of rhythm strength against the rhythm-adjusted mean.

Usage

circadian.quotient(cosinor_result)

Arguments

Value

A list with class "actiRhythm_circadian_quotient" containing:

circadian_quotient

amplitude / mesor.

relative_amplitude

amplitude / overall_mean (falls back to amplitude / mesor when overall_mean is absent).

Returns NA entries when the inputs are missing or the denominator is non-positive.

References

Nelson W, Tong YL, Lee JK, Halberg F (1979). “Methods for cosinor-rhythmometry.” Chronobiologia, 6(4), 305–323.

Examples

ts <- seq(as.POSIXct("2024-01-01", tz = "UTC"), by = 60, length.out = 1440 * 3)
counts <- 100 + 80 * cos(2 * pi * (as.numeric(format(ts, "%H")) - 14) / 24)
cos <- cosinor.analysis(counts, ts)
circadian.quotient(cos)

Description

From a raw accelerometer file (or raw data frame), computes a per-epoch raw metric (ENMO or MAD) with auto-calibration, then runs the count-style circadian analysis (circadian.rhythm) on it. The metrics (IS, IV, RA, L5/M10, cosinor, DFA, periodograms, SRI, ...) run on the raw metric the same way they run on counts, so raw data needs no new per-method code.

Usage

circadian.raw(
  x,
  metric = c("ENMO", "MAD"),
  device = "auto",
  epoch = 60,
  calibrate = TRUE,
  tz = "UTC",
  ...
)

Arguments

Value

The circadian.rhythm result computed on the raw metric.

See Also

raw.metrics, circadian.rhythm, example_raw

Examples

# The full count-style battery on synthetic raw ENMO

cr <- circadian.raw(example_raw(days = 2), metric = "ENMO")
c(IS = cr$IS, IV = cr$IV, RA = cr$RA)

Description

Computes non-parametric circadian metrics as in GGIR, ActCR, and nparACT. Uses a minute-level sliding window for L5/M10, plus the Sleep Regularity Index and several phase metrics.

Usage

circadian.rhythm(
  counts,
  timestamps,
  sleep_state = NULL,
  wear_time = NULL,
  min_valid_hours = 10,
  epoch_length = 60,
  calculate_sri = TRUE,
  use_cpp = TRUE
)

Arguments

Details

Non-Parametric Metrics (L5/M10/RA: van Someren et al., 1999; IS/IV: Witting et al., 1990):

L5/M10 use a minute-level sliding window, not hourly aggregation, so timing is resolved to the minute rather than the hour.

• L5 = Average activity during the least active 5 consecutive hours. Uses sliding window across minute-level data for precise timing.

• M10 = Average activity during the most active 10 consecutive hours.

• RA = Relative amplitude = (M10 - L5) / (M10 + L5). Ranges 0 to 1; higher values mean stronger day-night amplitude.

• IS = Interdaily stability. Measures coupling of the rhythm to stable zeitgebers. Range 0 (Gaussian noise) to 1 (perfect stability).

• IV = Intradaily variability. Measures rhythm fragmentation. About 0 for a perfect sine wave, about 2 for Gaussian noise, and can exceed 2 with ultradian rhythms.

Sleep Regularity Index (Phillips et al., 2017):

SRI = probability of being in same sleep/wake state at any two time points 24 hours apart. Range -100 to +100, with 100 indicating perfect regularity.

Value

List with class 'actiRhythm_circadian' containing:

L5, L5_start, L5_start_hour

Least active 5-hour average and timing (sliding window)

M10, M10_start, M10_start_hour

Most active 10-hour average and timing (sliding window)

L1, M1

Least/most active 1-hour for additional granularity

RA

Relative amplitude: (M10-L5)/(M10+L5), range 0-1

IS

Interdaily stability: day-to-day consistency (0-1, higher=more stable)

IV

Intradaily variability: within-day fragmentation (0 for a sine wave, near 2 for noise)

phi

First-order autocorrelation at 1-hour lag

SRI

Sleep Regularity Index (-100 to 100, higher=more regular)

onset_timing_variability

Mean circular SD of daily L5/M10 onset times (day-to-day phase variability). NOT the published Fischer/Roenneberg CPD.

hourly_profile

Mean activity by hour of day

daily_metrics

Per-day L5, M10, RA values

See Also

sleep.regularity.index for standalone SRI calculation, social.jet.lag for social jet lag calculation

Examples

counts <- agd.counts(read.agd(example_agd()))
result <- circadian.rhythm(counts$axis1, counts$timestamp)
print(result)

Description

Slides a window across the recording and computes the chi-square (Sokolove-Bushell) periodogram in each window, producing a period-by-time map that shows how the dominant period and its strength drift across the recording (non-stationarity, fragmentation, re-entrainment). A single global periodogram or cosinor fit cannot show this.

Usage

circadian.spectrogram(
  counts,
  timestamps,
  window_hours = 72,
  step_hours = 6,
  from = 18,
  to = 30,
  epoch_length = NULL
)

Arguments

Value

An object of class actiRhythm_spectrogram: a long data frame (window centre time, period, power) and a ggplot heat map in $plot.

See Also

chi.sq.periodogram, circadian.period

Examples

t_hours <- seq(0, 8 * 24, by = 1 / 60)
ts <- as.POSIXct("2024-01-01", tz = "UTC") + t_hours * 3600
counts <- 100 + 80 * cos(2 * pi * t_hours / 24) + rnorm(length(t_hours), 0, 20)
circadian.spectrogram(counts, ts, step_hours = 24)$plot

Description

Decomposes an activity-count series into additive components (trend, a circadian component, ultradian components, and noise) with Basic Singular Spectrum Analysis: embed the series into a Hankel trajectory matrix, take its singular value decomposition, group the resulting elementary series, and reconstruct each group by diagonal averaging. pyActigraphy implements this model-free decomposition for actigraphy.

Usage

circadian.ssa(
  counts,
  timestamps,
  window_hours = 24,
  n_components = 10,
  groups = NULL,
  w_components = NULL,
  period_range = c(20, 28),
  detrend = FALSE
)

Arguments

Details

Singular Spectrum Analysis on a long minute-level series builds a large trajectory matrix; for multi-day recordings, resampling to a coarser epoch (for example 10 to 30 minutes) before calling keeps the decomposition fast.

Value

An object of class actiRhythm_ssa: the singular values and partial variances, the reconstructed component series (trend, circadian, ultradian), the w-correlation matrix, the circadian fundamental_period, and the share of variance the circadian component carries. The function never errors; on insufficient data it returns the same structure with insufficient = TRUE.

References

Golyandina N, Zhigljavsky A (2013). Singular Spectrum Analysis for Time Series, SpringerBriefs in Statistics. Springer. doi:10.1007/978-3-642-34913-3.

Vautard R, Yiou P, Ghil M (1992). “Singular-spectrum analysis: a toolkit for short, noisy chaotic signals.” Physica D: Nonlinear Phenomena, 58(1-4), 95–126. doi:10.1016/0167-2789(92)90103-T.

Hammad G, Reyt M, Beliy N, Baillet M, Deantoni M, Lesoinne A, Muto V, Schmidt C (2021). “pyActigraphy: open-source python package for actigraphy data visualization and analysis.” PLOS Computational Biology, 17(10), e1009514. doi:10.1371/journal.pcbi.1009514.

See Also

circadian.period, circadian.flm

Examples

ts <- seq(as.POSIXct("2024-01-01", tz = "UTC"), by = 1800, length.out = 7 * 48)
h  <- as.numeric(format(ts, "%H")) + as.numeric(format(ts, "%M")) / 60
counts <- 50 + 0.5 * seq_along(ts) + 60 * cos(2 * pi * (h - 14) / 24)
ssa <- circadian.ssa(counts, ts)
ssa

Description

Runs a Morlet continuous wavelet transform on the activity series and returns the time-frequency power surface across circadian and ultradian periods and a dominant-period-over-time track (Torrence and Compo 1998; Leise 2013). Unlike the sliding chi-square spectrogram, it localizes period drift at every time point, so a lengthening or fragmenting rhythm shows up directly.

Usage

circadian.wavelet(counts, timestamps, dj = 1/12, omega0 = 6, epoch_length = 60)

Arguments

Value

An object of class actiRhythm_wavelet: the period grid (hours), the time-averaged global power spectrum, the per-time dominant period, the overall peak period, the power matrix, and the cone of influence (coi_period_h, the largest reliable period at each time, with the in_coi mask of edge-affected cells). The global spectrum and dominant period are computed outside the cone so edge effects do not bias them. A significant logical matrix flags cells whose power exceeds the 95\ confidence level against an AR(1) red-noise background (with the per-scale threshold sig_power and the lag-1 autocorrelation phi), which separates a real rhythm from background. The power is scale-rectified ($|W|^2/s$, Liu et al. 2007), which reduces the Torrence bias toward long periods. Never errors.

References

Torrence C, Compo GP (1998). “A practical guide to wavelet analysis.” Bulletin of the American Meteorological Society, 79(1), 61–78. doi:10.1175/1520-0477(1998)079<0061:APGTWA>2.0.CO;2.

Leise TL (2013). “Wavelet analysis of circadian and ultradian behavioral rhythms.” Journal of Circadian Rhythms, 11, 5. doi:10.1186/1740-3391-11-5.

Liu Y, Liang XS, Weisberg RH (2007). “Rectification of the bias in the wavelet power spectrum.” Journal of Atmospheric and Oceanic Technology, 24(12), 2093–2102. doi:10.1175/2007JTECHO511.1.

Examples

ts <- seq(as.POSIXct("2024-01-01", tz = "UTC"), by = 600, length.out = 6 * 144)
th <- as.numeric(difftime(ts, ts[1], units = "hours"))
circadian.wavelet(100 + 80 * cos(2 * pi * th / 24), ts, epoch_length = 600)

Description

Runs the complete actiRhythm circadian analysis on one activity time series and writes a multi-sheet .xlsx workbook: a one-row Summary of every metric (nonparametric IS/IV/RA/L5/M10, cosinor, the rhythmicity F-test, the Lomb-Scargle period with its bootstrap confidence interval, the chi-square periodogram, DFA, multifractal DFA, multiscale entropy, rest-activity state transitions, and, when sleep is supplied, the Sleep Regularity Index, social jet lag and LIDS), plus detail sheets for the hourly profile, both periodograms, the fluctuation and multifractal spectra, the transition curves, the LIDS fits, and a data dictionary.

Usage

circadian.workbook(
  activity,
  timestamps,
  file = NULL,
  sleep_state = NULL,
  sleep_periods = NULL,
  wear_time = NULL,
  epoch_length = 60,
  include_period_ci = TRUE,
  n_boot = 200
)

Arguments

Value

The openxlsx workbook object, invisibly.

Examples

ts <- seq(as.POSIXct("2024-01-01", tz = "UTC"), by = 60, length.out = 2 * 1440)
h  <- as.numeric(format(ts, "%H"))
act <- pmax(0, 100 + 80 * cos(2 * pi * (h - 14) / 24) + rnorm(length(ts), 0, 20))
circadian.workbook(act, ts, file = tempfile(fileext = ".xlsx"), include_period_ci = FALSE)

Description

Combines, for each day, the deviation of the phase marker from the individual's own mean phase (precision) and from a reference phase (accuracy) as CPD = mean(sqrt(precision^2 + accuracy^2)). When no external reference phase is supplied, accuracy is measured from the individual's own mean phase. CPD is distinct from the circular SD reported by onset_timing_variability.

Usage

composite.phase.deviation(onset_hours, reference_phase = NULL)

Arguments

Value

List with CPD, precision (mean absolute deviation from own mean phase, hours), accuracy (mean absolute deviation from the reference, hours), reference_phase, and n_days.

References

Fischer D, Vetter C, Roenneberg T (2016). “A novel method to visualise and quantify circadian misalignment.” Scientific Reports, 6, 38601. doi:10.1038/srep38601.

Description

Combines the rhythmicity verdicts of three tests into one call: the cosinor zero-amplitude F-test (rhythmicity.test), the Lomb-Scargle Baluev false-alarm probability (circadian.period), and the chi-square (Sokolove-Bushell) periodogram (chi.sq.periodogram). The three share one series, so their p-values are pooled by the Cauchy combination, which is valid under arbitrary dependence, and a majority vote is also reported.

Usage

consensus.rhythmicity(
  counts,
  timestamps,
  period = 24,
  alpha = 0.05,
  wear_time = NULL
)

Arguments

Value

An object of class actiRhythm_consensus: the combined p-value and consensus call, the vote count, a per-method tests data frame, and the agreement fraction.

References

Liu Y, Xie J (2020). “Cauchy combination test: a powerful test with analytic p-value calculation under arbitrary dependency structures.” Journal of the American Statistical Association, 115(529), 393–402. doi:10.1080/01621459.2018.1554485.

Examples

ts <- seq(as.POSIXct("2024-01-01", tz = "UTC"), by = 60, length.out = 3 * 1440)
h <- as.numeric(format(ts, "%H"))
counts <- pmax(0, 100 + 80 * cos(2 * pi * (h - 14) / 24))
consensus.rhythmicity(counts, ts)

Description

Fits a single-component cosinor model to activity data and returns the parametric circadian parameters.

Usage

cosinor.analysis(
  counts,
  timestamps,
  period = 24,
  wear_time = NULL,
  min_valid_hours = 10,
  transform = c("none", "log1p")
)

Arguments

Details

The single-component cosinor model fits:

$Y(t) = M + A \cdot cos(2\pi t / T + \phi)$

Where:

• M = mesor (rhythm-adjusted mean)

• A = amplitude (half peak-to-trough difference)

• T = period (typically 24 hours)

• $\phi$ = acrophase (phase angle, converted to time)

The model is fit using linear least squares on the linearized form:

$Y(t) = M + \beta_1 \cos(2\pi t / T) + \beta_2 \sin(2\pi t / T)$

Value

List with class 'actiRhythm_cosinor' containing:

mesor

Rhythm-adjusted mean (MESOR)

amplitude

Half the peak-to-trough difference

acrophase

Time of peak activity (hours, 0-24)

acrophase_time

Acrophase as HH:MM string

r_squared

Goodness of fit (coefficient of determination)

f_statistic

F-statistic for model significance

p_value

P-value for model significance

References

Nelson W, Tong YL, Lee JK, Halberg F (1979). “Methods for cosinor-rhythmometry.” Chronobiologia, 6(4), 305–323.

Cornelissen G (2014). “Cosinor-based rhythmometry.” Theoretical Biology and Medical Modelling, 11, 16. doi:10.1186/1742-4682-11-16.

Examples

counts <- agd.counts(read.agd(example_agd()))
result <- cosinor.analysis(counts$axis1, counts$timestamp)
print(result)

Description

Fits the sigmoidally transformed cosine ("anti-logistic" extended cosinor) model of Marler et al. (2006) to the averaged 24-hour activity profile. The extended model relaxes the symmetric shape of the ordinary cosinor by adding two shape parameters: alpha sets the relative width of the active versus rest phase, and beta sets the steepness of the rest-to-active transitions. It is the same model as ActCR::ActExtendCosinor and reproduces its parameter estimates numerically.

Usage

cosinor.antilogistic(counts, timestamps, period = 24)

Arguments

Details

The model fitted to the averaged profile is

$f(t) = minimum + amplitude \cdot expit(\beta (cos(2\pi (t - acrotime)/T) - \alpha))$

where $expit(z) = 1/(1+e^{-z})$. This is the ActCR/Marler parameterization, in which amplitude is the raw multiplier of the logistic transform (it is not renormalized by $expit(\beta(1-\alpha))$). The closely related "normalized" Marler form, $f(t) = min + amp \cdot expit(\beta(cos(\cdot) - \alpha)) / expit(\beta(1-\alpha))$, rescales amplitude so that the peak equals exactly minimum + amplitude; the two forms describe the same curve shape and the (alpha, beta, acrotime) parameters are identical. The normalized peak level is reported as peak.

Starting values are taken from an ordinary cosinor fit (minimum = max(mesor - amp, 0), amplitude = 2 * amp, alpha = 0, beta = 2, acrotime = ordinary acrophase). The nonlinear least-squares problem is solved with stats::optim() using the box-constrained L-BFGS-B method (bounds lower = c(0, 0, -1, 0, -3), upper = c(Inf, Inf, 1, Inf, 27), matching ActCR), so no extra package dependency is required.

Value

A list with class "actiRhythm_cosinor_ext" containing:

minimum

Lower asymptote of the fitted curve (rest-phase level).

amplitude

Vertical span of the sigmoidal transition (amp); the asymptotic ceiling is minimum + amplitude, with the fitted-curve maximum slightly below it at a finite steepness.

alpha

Width-asymmetry parameter in $[-1, 1]$.

beta

Steepness parameter ($\ge 0$).

acrophase

Time of peak activity in clock hours (acrotime).

acrotime

Alias of acrophase (ActCR naming).

peak

Fitted activity level at the acrophase (renormalized Marler peak).

UpMesor

Clock time of the rest-to-active (rising) transition, $-\arccos(\alpha) / (2\pi/T) + acrotime$.

DownMesor

Clock time of the active-to-rest (falling) transition, $\arccos(\alpha) / (2\pi/T) + acrotime$.

MESOR

Midline statistic minimum + amplitude / 2.

F_pseudo

Pseudo-F improvement of the extended fit over the ordinary cosinor: $((RSS_{cos} - RSS_{ext})/2)/(RSS_{ext}/(n-5))$.

rss_cosinor

Residual sum of squares of the ordinary cosinor.

rss_extended

Residual sum of squares of the extended cosinor.

converged

Logical; whether the nonlinear fit converged.

period

Period used (hours).

n_profile_hours

Number of profile hours used in the fit.

On non-convergence or insufficient data all numeric parameters are returned as NA with converged = FALSE.

References

Marler MR, Gehrman P, Martin JL, Ancoli-Israel S (2006). “The sigmoidally transformed cosine curve: a mathematical model for circadian rhythms with symmetric non-sinusoidal shapes.” Statistics in Medicine, 25(22), 3893–3904. doi:10.1002/sim.2466.

Di J, Zipunnikov V (2021). ActCR: Extract Circadian Rhythms Metrics from Actigraphy Data. R package version 0.2.0, https://CRAN.R-project.org/package=ActCR.

Examples

ts <- seq(as.POSIXct("2024-01-01 00:00:00"), by = 60, length.out = 1440 * 3)
hour <- as.numeric(format(ts, "%H")) + as.numeric(format(ts, "%M")) / 60
counts <- 50 + 300 * plogis(4 * (cos((hour - 14) * 2 * pi / 24) - 0.2))
fit <- cosinor.antilogistic(counts, ts)
print(fit)

Description

Tests whether the rest-activity rhythm differs between two groups. Fits each subject's cosinor with the same engine as cosinor.analysis. An Bingham et al. (1982) comparison is a 2-variate Hotelling's $T^2$ on the cosine and sine coefficients (testing equal amplitude and acrophase, accounting for their correlation), with the MESOR compared by a separate pooled-variance F-test. Auxiliary per-parameter two-sample (Welch) t-tests break the result down for the MESOR, amplitude, and acrophase; the acrophase test is circular-aware, unwrapping the per-subject acrophases about their common circular mean.

Usage

cosinor.compare(
  activity,
  timestamps,
  subject,
  group,
  period = 24,
  level = 0.95,
  min_valid_hours = 12
)

Arguments

Value

An object of class actiRhythm_cosinor_compare: a joint list (the amplitude/acrophase Hotelling $T^2$ with its F, degrees of freedom and p-value, plus a separate MESOR F-test), a tests data frame of auxiliary per-parameter Welch comparisons (each group's estimate, the difference, the t statistic, p-value and CI), and the per-subject coefficients.

References

Bingham C, Arbogast B, Cornelissen Guillaume G, Lee JK, Halberg F (1982). “Inferential statistical methods for estimating and comparing cosinor parameters.” Chronobiologia, 9(4), 397–439.

See Also

population.cosinor

Examples

set.seed(1); hrs <- 0:23
act <- ts <- subj <- grp <- NULL
for (g in c("A", "B")) for (i in 1:5) {
  acro <- if (g == "A") 8 else 11
  y <- 100 + 40 * cos(2 * pi * (hrs - acro) / 24) + rnorm(24, 0, 4)
  act <- c(act, y); subj <- c(subj, rep(paste0(g, i), 24)); grp <- c(grp, rep(g, 24))
  ts <- c(ts, as.POSIXct("2024-01-01", tz = "UTC") + hrs * 3600)
}
cosinor.compare(act, as.POSIXct(ts, tz = "UTC", origin = "1970-01-01"), subj, grp)

Description

Computes the joint confidence region for the cosinor amplitude and acrophase, following Bingham et al. (1982). The region is an ellipse in the $(\beta_1, \beta_2)$ (cosine/sine coefficient) plane. When the ellipse excludes the origin, the population amplitude differs significantly from zero and a rhythm is detected.

Usage

cosinor.confidence.ellipse(cosinor_result, level = 0.95, n_points = 200)

Arguments

Details

Under the cosinor model $Y(t) = M + \beta_1 cos(\omega t) + \beta_2 sin(\omega t)$, the $100(1-\alpha)\%$ joint confidence region for $(\beta_1, \beta_2)$ is the set of points $b$ satisfying

$(b - \hat b)^\top \Sigma^{-1} (b - \hat b) \le 2 F_{2, df, 1-\alpha}$

where $\Sigma$ is the covariance of the estimated coefficients and $df$ the residual degrees of freedom. The averaged-profile cosinor design used by cosinor.analysis() has orthogonal cosine and sine columns, so $\Sigma$ is (very nearly) diagonal with equal variances $\sigma^2$; in that case se_amplitude equals the standard error of each coefficient $\sqrt{\mathrm{Var}(\beta)}$, which is how $\Sigma$ is reconstructed when it is not supplied explicitly. The point estimate is recovered from amplitude and acrophase as $\beta_1 = A cos(\phi)$, $\beta_2 = A sin(\phi)$ with $\phi = acrophase \cdot 2\pi / T$.

Value

A list with class "actiRhythm_cosinor_ellipse" containing:

ellipse

Data frame with columns x ($\beta_1$) and y ($\beta_2$) giving the ellipse boundary vertices.

center

Numeric vector c(beta1, beta2) of the point estimate.

excludes_origin

Logical; TRUE when the ellipse excludes (0, 0) (i.e. a rhythm is detected at the requested level).

rhythm_detected

Alias of excludes_origin.

distance_stat

Mahalanobis-type statistic of the origin relative to the fitted ellipse.

critical_value

Threshold $2 F_{2, df, level}$ the statistic is compared against.

level

Confidence level used.

When the input is missing required fields or is degenerate, the boundary is returned as NA and excludes_origin = NA.

References

Bingham C, Arbogast B, Cornelissen Guillaume G, Lee JK, Halberg F (1982). “Inferential statistical methods for estimating and comparing cosinor parameters.” Chronobiologia, 9(4), 397–439.

Examples

ts <- seq(as.POSIXct("2024-01-01", tz = "UTC"), by = 60, length.out = 1440 * 3)
counts <- 100 + 80 * cos(2 * pi * (as.numeric(format(ts, "%H")) - 14) / 24)
cos <- cosinor.analysis(counts, ts)
cosinor.confidence.ellipse(cos)$rhythm_detected

Description

Fits a multi-component cosinor model with the fundamental (24h) and harmonics (12h, 8h, etc.) to capture patterns the single cosinor misses, such as bimodal rhythms.

Usage

cosinor.extended(
  counts,
  timestamps,
  harmonics = c(24, 12),
  wear_time = NULL,
  min_valid_hours = 10
)

Arguments

Details

The multi-component model is:

Y(t) = M + sum_k[A_k * cos(2*pi*t/T_k - phi_k)]

Where T_k are the periods (24h, 12h, 8h, etc.)

Use it for:

• Bimodal patterns (morning + evening peaks), captured by the 12h harmonic

• Complex daily routines with multiple activity bouts

• Shift workers or irregular schedules

Value

A list with class "actiRhythm_cosinor_extended" containing:

mesor

Rhythm-adjusted mean

components

Data frame with amplitude, acrophase, acrophase_time for each harmonic

dominant_period

Period with largest amplitude

dominant_acrophase

Acrophase of dominant component

r_squared

Model R-squared (should be higher than single-component)

r_squared_improvement

Improvement over single 24h cosinor

References

Cornelissen G (2014). “Cosinor-based rhythmometry.” Theoretical Biology and Medical Modelling, 11, 16. doi:10.1186/1742-4682-11-16.

Refinetti R, Cornelissen G, Halberg F (2007). “Procedures for numerical analysis of circadian rhythms.” Biological Rhythm Research, 38(4), 275–325. doi:10.1080/09291010600903692.

Examples

counts <- agd.counts(read.agd(example_agd()))
result <- cosinor.extended(counts$axis1, counts$timestamp, harmonics = c(24, 12, 8))
print(result)

Description

Fits the multi-component (harmonic) cosinor of Cornelissen (2014) with one to several harmonics of the fundamental period and picks the number of harmonics by an information criterion (AIC or BIC, a package choice), so it captures a bimodal or asymmetric daily shape without your choosing the order by hand. The single cosinor is the one-harmonic special case.

Usage

cosinor.multicomponent(
  counts,
  timestamps,
  period = 24,
  max_harmonics = 3,
  criterion = c("AIC", "BIC")
)

Arguments

Value

An object of class actiRhythm_multicosinor: the selected number of harmonics, the per-harmonic amplitude and acrophase, the MESOR, R-squared, and the full model-comparison table. Never errors.

References

Cornelissen G (2014). “Cosinor-based rhythmometry.” Theoretical Biology and Medical Modelling, 11, 16. doi:10.1186/1742-4682-11-16.

Examples

ts <- seq(as.POSIXct("2024-01-01", tz = "UTC"), by = 60, length.out = 4 * 1440)
th <- as.numeric(difftime(ts, ts[1], units = "hours"))
y  <- 100 + 40 * cos(2 * pi * th / 24) + 20 * cos(2 * pi * 2 * th / 24)
cosinor.multicomponent(y, ts)

Description

A device-neutral entry point: pull a count column (and optionally a time column) out of any data frame and return a tidy timestamp/counts frame ready for the analysis functions. Use it for non-ActiGraph counts or any pre-extracted series.

Usage

counts.from.data.frame(
  df,
  count_col = "axis1",
  time_col = NULL,
  epoch_length = 60,
  tz = "UTC",
  start = "1970-01-01"
)

Arguments

Value

A data frame with timestamp (POSIXct) and counts.

See Also

read.actigraph.csv

Examples

df <- data.frame(activity = c(0, 50, 300), clock = c("2024-01-01 00:00:00",
  "2024-01-01 00:01:00", "2024-01-01 00:02:00"))
counts.from.data.frame(df, count_col = "activity", time_col = "clock")

Description

Check C++ Availability

Usage

cpp_available()

Value

Logical

Description

Aligns each day's 24-hour activity profile on its active-phase landmark (the M10 centre), separating the horizontal phase variation (how the timing shifts day to day) from the vertical amplitude variation (the registered mean profile, sharper than the plain average because phase jitter no longer blurs it). The per-day landmark times are a scale-invariant phase marker (the M10-window centre), unchanged by any rescaling of the counts (Ramsay and Silverman 2005).

Usage

curve.registration(counts, timestamps, n_grid = 144L, period = 24)

Arguments

Value

An object of class actiRhythm_registration: a per-day landmark table (L5 and M10 centre hours), the circular-mean landmarks, the phase variability (circular SD of the M10 landmark), and the registered mean profile. Never errors.

References

Ramsay JO, Silverman BW (2005). Functional Data Analysis, 2nd edition. Springer. doi:10.1007/b98888.

Van Someren EJW, Swaab DF, Colenda CC, Cohen W, McCall WV, Rosenquist PB (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. doi:10.3109/07420529908998724.

Examples

ts <- seq(as.POSIXct("2024-01-01", tz = "UTC"), by = 60, length.out = 5 * 1440)
h  <- as.numeric(format(ts, "%H"))
curve.registration(ifelse(h >= 23 | h < 7, 5, 300), ts)

Description

Classifies each epoch as wear or non-wear with the Choi et al. (2011) algorithm: a run of consecutive zero-count epochs of at least frame minutes is non-wear, tolerating a short nonzero spike only when it is flanked by a fully zero window of stream minutes both before and after. The returned mask can be passed as the wear_time argument to the rest-activity and sleep functions.

Usage

detect.nonwear.choi(
  counts,
  epoch_length = 60,
  frame = 90,
  spike_tolerance = 2,
  stream = 30
)

Arguments

Value

A logical vector, one per epoch: TRUE = wear, FALSE = non-wear. Never errors.

References

Choi L, Liu Z, Matthews CE, Buchowski MS (2011). “Validation of accelerometer wear and nonwear time classification algorithm.” Medicine & Science in Sports & Exercise, 43(2), 357–364. doi:10.1249/MSS.0b013e3181ed61a3.

See Also

detect.nonwear.troiano

Examples

ts <- seq(as.POSIXct("2024-01-01", tz = "UTC"), by = 60, length.out = 600)
counts <- c(rep(200, 200), rep(0, 200), rep(200, 200))   # 200-min non-wear gap
table(detect.nonwear.choi(counts))

Description

Flags non-wear time from raw acceleration by the van Hees et al. (2013) / GGIR standard-deviation-and-range rule: a block is non-wear when, over a window centred on it (default 60 minutes), at least two of the three axes have both a standard deviation below sd_crit and a value range below range_crit. A stationary, taken-off device reads as non-wear. This lets the z-angle sleep detector tell device-off periods from real sleep (a still arm that keeps micro-movement). Pass the result as the wear argument of rest.spt.

Usage

detect.nonwear.raw(
  x,
  device = "auto",
  epoch = 5,
  block = 300,
  window = 3600,
  sd_crit = 0.013,
  range_crit = 0.05,
  tz = "UTC"
)

Arguments

Value

A logical vector, one per epoch: TRUE = wear, FALSE = non-wear. Never errors.

References

van Hees VT, Gorzelniak L, Dean Leon EC, Eder M, Pias M, Taherian S, Ekelund U, Renstrom F, Franks PW, Horsch A, Brage S (2013). “Separating movement and gravity components in an acceleration signal and implications for the assessment of human daily physical activity.” PLoS ONE, 8(4), e61691. doi:10.1371/journal.pone.0061691.

See Also

rest.spt, raw.metrics

Examples

raw  <- example_raw(days = 2, device_off = 1)   # two worn days + one device-off day
mean(detect.nonwear.raw(raw, epoch = 60))       # fraction of epochs worn

Description

Classifies each epoch as wear or non-wear with the Troiano et al. (2008, NHANES) algorithm: a run of at least frame minutes of zero counts is non-wear, tolerating up to spike_tolerance consecutive nonzero minutes only if every one of them is at or below stoplevel counts. Unlike Choi it has no flanking-window requirement but applies a count ceiling on spikes.

Usage

detect.nonwear.troiano(
  counts,
  epoch_length = 60,
  frame = 60,
  spike_tolerance = 2,
  stoplevel = 100
)

Arguments

Value

A logical vector, one per epoch: TRUE = wear, FALSE = non-wear. Never errors.

References

Troiano RP, Berrigan D, Dodd KW, Masse LC, Tilert T, McDowell M (2008). “Physical activity in the United States measured by accelerometer.” Medicine & Science in Sports & Exercise, 40(1), 181–188. doi:10.1249/mss.0b013e31815a51b3.

See Also

detect.nonwear.choi

Examples

ts <- seq(as.POSIXct("2024-01-01", tz = "UTC"), by = 60, length.out = 400)
counts <- c(rep(150, 100), rep(0, 200), rep(150, 100))
table(detect.nonwear.troiano(counts))

Description

The fraction of in-rest activity counts that fall below the median of the out-of-rest (active) counts, a rest/active separation index used in cancer chronobiology (Mormont et al. 2000). A high I<O means rest is quiet relative to the active day, marking a well-separated rhythm.

Usage

dichotomy.index(counts, rest)

Arguments

Value

An object of class actiRhythm_dichotomy: the index IO (percent), the active-period median, and epoch counts. Never errors.

References

Mormont MC, Waterhouse J, Bleuzen P, Giacchetti S, Jami A, Bogdan A, Lellouch J, Misset JL, Touitou Y, Levi F (2000). “Marked 24-h rest/activity rhythms are associated with better quality of life, better response, and longer survival in patients with metastatic colorectal cancer and good performance status.” Clinical Cancer Research, 6(8), 3038–3045.

Examples

ts <- seq(as.POSIXct("2024-01-01", tz = "UTC"), by = 60, length.out = 2 * 1440)
h  <- as.numeric(format(ts, "%H"))
counts <- ifelse(h >= 23 | h < 7, 5, 300)
dichotomy.index(counts, rest = h >= 23 | h < 7)

Description

Get Path to Example AGD Files

Usage

example_agd(file = 1)

Arguments

Value

Character. Full path to the example AGD file.

Examples

example_agd()
example_agd("list")
agd_path <- example_agd(1)

Description

Generates a deterministic synthetic triaxial raw acceleration recording (in g) with a day/night posture cycle, daytime movement and posture changes, still (sleeping) nights, and a slight built-in miscalibration. It is the file-free stand-in for a real raw file in the examples: feed it to raw.metrics, circadian.raw, or the z-angle sleep pipeline. Raw acceleration is far too large to ship as data, so it is generated on demand rather than bundled.

Usage

example_raw(days = 2, fs = 30, device_off = 0)

Arguments

Value

A data frame with a POSIXct time column and x/y/ z acceleration in g, with the sample rate in the "fs" attribute.

See Also

raw.metrics, circadian.raw, rest.spt

Examples

raw <- example_raw(days = 1)
str(raw)

Description

Computes the scaling exponent alpha of an activity time series using Detrended Fluctuation Analysis (Peng et al., 1994). DFA quantifies long-range temporal correlations: alpha approximately 0.5 indicates uncorrelated (white) noise, alpha approximately 1.0 indicates 1/f (pink) noise, and alpha approximately 1.5 indicates Brownian (random-walk / brown) noise. Healthy human activity fluctuations typically show alpha in the 0.9 to 1.0 range, with reductions reported in aging and Alzheimer's disease (Hu et al., 2009); those reference values were obtained with quadratic DFA-2 (detrend_order = 2), which can differ from the default linear DFA-1 on trend-carrying data.

Usage

fractal.dfa(
  x,
  scale_min = 4,
  scale_max = NULL,
  breakpoint_min = 90,
  detrend_order = 1L
)

Arguments

Details

Algorithm (integrated, non-overlapping DFA, polynomial detrend of order detrend_order):

1. Extract the longest continuous non-NA segment of x.

2. Integrate the mean-centred signal: y = cumsum(x - mean(x)).

3. For each window size n (log-spaced from scale_min to scale_max), split y into floor(N / n) non-overlapping windows of length n, fit and remove a least-squares polynomial of order detrend_order within each window, and pool the residuals. The fluctuation is F(n) = sqrt(mean(residuals^2)) over all pooled residuals.

4. The scaling exponent is the slope of log10(F(n)) regressed on log10(n).

Window sizes are unique integers chosen on a base-10 log grid, which gives approximately even spacing in the log-log fit and matches the convention used by reference implementations such as nonlinearTseries.

Value

A list with class "actiRhythm_dfa" containing:

alpha

Overall scaling exponent: slope of lm(log10(F) ~ log10(n)) across all scales.

alpha1

Short-timescale exponent (scales < breakpoint_min). NA if fewer than two qualifying scales.

alpha2

Long-timescale exponent (scales >= breakpoint_min). NA if fewer than two qualifying scales.

scales

Integer vector of window sizes n that were used.

fluctuations

Numeric vector of fluctuation magnitudes F(n) corresponding to scales.

n_used

Length of the analyzed (longest non-NA) segment.

breakpoint_min

The breakpoint value used.

On an unusable series (too short, all NA, or constant) the numeric scaling outputs are returned as NA with the same structure (never an error).

See Also

multiscale.entropy, circadian.rhythm

Examples

set.seed(1)
# White noise -> alpha near 0.5
fractal.dfa(rnorm(10000))$alpha
# Brown noise -> alpha near 1.5
fractal.dfa(cumsum(rnorm(10000)))$alpha

Description

Reads a raw GENEActiv (.bin) accelerometer file and converts it to ActiGraph-equivalent activity counts via the agcounts implementation of the ActiGraph count algorithm (Neishabouri 2022). Requires the GGIRread and agcounts packages.

Usage

geneactiv.counts(path, epoch = 60, lfe = FALSE, tz = "UTC")

Arguments

Value

Data frame with time, axis1, axis2, axis3 and vm, one row per epoch.

Cross-brand counts

These are an approximation of ActiGraph counts, not native ActiGraph output, and GENEActiv-to-count conversion is not empirically validated (only theoretically motivated by the shared filter). GENEActiv records at about 85.7 Hz, which is resampled to 30 Hz before the count filter. Appropriate for the relative and normalized circadian metrics here (IS, IV, RA, L5, M10, SRI); do not apply ActiGraph cut-points or compare absolute counts across brands.

References

Neishabouri A, Nguyen J, Samuelsson J, Guthrie T, Biggs M, Wyatt J, Cross D, Karas M, Migueles JH, Khan S, Guo CC (2022). “Quantification of acceleration as activity counts in ActiGraph wearable.” Scientific Reports, 12, 11958. doi:10.1038/s41598-022-16003-x.

Brond JC, Andersen LB, Arvidsson D (2017). “Generating ActiGraph counts from raw acceleration recorded by an alternative monitor.” Medicine & Science in Sports & Exercise, 49(11), 2351–2360. doi:10.1249/MSS.0000000000001344.

See Also

axivity.counts, gt3x.counts, read.raw

Description

Compute activity counts from a raw ActiGraph .gt3x accelerometer file using the agcounts implementation of the ActiGraph count algorithm (Neishabouri 2022). Requires the agcounts and read.gt3x packages.

Usage

gt3x.counts(path, epoch = 60, lfe = FALSE, tz = "UTC")

Arguments

Value

Data frame with time, axis1, axis2, axis3 and vm, one row per epoch.

References

Neishabouri A, Nguyen J, Samuelsson J, Guthrie T, Biggs M, Wyatt J, Cross D, Karas M, Migueles JH, Khan S, Guo CC (2022). “Quantification of acceleration as activity counts in ActiGraph wearable.” Scientific Reports, 12, 11958. doi:10.1038/s41598-022-16003-x.

See Also

axivity.counts, geneactiv.counts, read.raw

Description

Computes counts with gt3x.counts and writes them to a small .agd, carrying device/subject metadata from the .gt3x header. Requires agcounts.

Usage

gt3x.to.agd(gt3x_path, agd_path = NULL, epoch = 60, lfe = FALSE, tz = "UTC")

Arguments

Value

The output .agd path.

Description

Checks whether an AGD file contains inclinometer data, which can be used to enhance sleep detection algorithms.

Usage

has.inclinometer(agd_data)

Arguments

Value

Logical. TRUE if inclinometer data is available

Description

Computes the instantaneous amplitude, phase, and period of a circadian intrinsic mode function via its analytic signal (Huang et al. 1998). Where the cosinor gives one acrophase for the whole recording, the instantaneous phase tracks the rhythm cycle by cycle, and the spread of the instantaneous period measures how stationary the circadian band is.

Usage

hilbert.huang(x, timestamps = NULL, imf = NULL, epoch_length = 60)

Arguments

Value

An object of class actiRhythm_hht: the instantaneous amplitude, phase, and period series, plus the mean instantaneous period and its SD, mean amplitude and its CV, and the fraction of time the period stays in 20-28 h. Never errors.

References

Huang NE, Shen Z, Long SR, Wu MC, Shih HH, Zheng Q, Yen NC, Tung CC, Liu HH (1998). “The empirical mode decomposition and the Hilbert spectrum for nonlinear and non-stationary time series analysis.” Proceedings of the Royal Society A, 454(1971), 903–995. doi:10.1098/rspa.1998.0193.

See Also

circadian.emd

Examples

ts <- seq(as.POSIXct("2024-01-01", tz = "UTC"), by = 600, length.out = 6 * 144)
th <- as.numeric(difftime(ts, ts[1], units = "hours"))
e <- circadian.emd(100 + 60 * cos(2 * pi * th / 24), ts, epoch_length = 600)
hilbert.huang(e)

Description

Intradaily variability computed across a set of bin sizes and averaged, the counterpart to multiscale interdaily stability (circadian.is.multiscale). Fragmentation that is invisible at the hourly scale often shows at finer bins, so the averaged IVm varies less across recordings than the single hourly IV (Goncalves et al. 2014).

Usage

intradaily.variability.multiscale(counts, timestamps, bin_minutes = 1:60)

Arguments

Value

An object of class actiRhythm_ivm: a per-bin IV table and the averaged IVm. Never errors; returns NA on insufficient data.

References

Goncalves BSB, Cavalcanti PRA, Tavares GR, Campos TF, Araujo JF (2014). “Nonparametric methods in actigraphy: an update.” Sleep Science, 7(3), 158–164. doi:10.1016/j.slsci.2014.09.013.

See Also

circadian.is.multiscale

Examples

ts <- seq(as.POSIXct("2024-01-01", tz = "UTC"), by = 60, length.out = 3 * 1440)
h  <- as.numeric(format(ts, "%H"))
intradaily.variability.multiscale(ifelse(h >= 23 | h < 7, 5, 300), ts)

Description

Interdaily Stability (IS)

Usage

IS_cpp(hourly_data, hours_per_day = 24L)

Arguments

Value

IS value (0-1, higher = more stable)

Description

Intradaily Variability (IV)

Usage

IV_cpp(hourly_data)

Arguments

Value

IV value (lower = less fragmented)

Description

Finds least active 5 hours (L5) and most active 10 hours (M10) using van Someren (1999) average-profile method.

Usage

L5M10_cpp(minute_data, window_L5 = 300L, window_M10 = 600L, start_minute = 0L)

Arguments

Value

List with L5_value, L5_onset, L5_onset_hours, M10_value, M10_onset, M10_onset_hours, RA

Description

Quantifies the ultradian (sleep-cycle) oscillation of inactivity during sleep, following Winnebeck et al. (2018). Within each sleep period the activity is summed into 10-minute bins, transformed to LIDS (100 / (activity + 1)), smoothed with a centered 30-minute moving average, and fit with an ultradian cosine over a scan of candidate periods; the best period is the interior peak that maximises the Munich Rhythmicity Index (MRI).

Usage

lids(
  counts,
  timestamps,
  sleep_periods,
  epoch_length = 60,
  smooth_minutes = 30,
  period_min = 30,
  period_max = 180,
  period_step = 5
)

Arguments

Value

An object of class actiRhythm_lids: a per-period data frame (period in minutes, MRI, amplitude, Pearson r, ...) and the mean period and MRI across periods.

References

Winnebeck EC, Fischer D, Leise T, Roenneberg T (2018). “Dynamics and ultradian structure of human sleep in real life.” Current Biology, 28(1), 49–59. doi:10.1016/j.cub.2017.11.063.

Description

Generalizes detrended fluctuation analysis (fractal.dfa) to a spectrum of moment orders q (Kantelhardt et al. 2002). A flat generalized Hurst exponent h(q) indicates a monofractal signal; a decreasing h(q) and a wide multifractal spectrum indicate multifractality. h(2) equals the standard DFA scaling exponent.

Usage

mfdfa(
  x,
  scale_min = 8L,
  scale_max = NULL,
  q_values = seq(-5, 5, by = 0.5),
  both_ends = TRUE,
  detrend_order = 1L
)

Arguments

Value

An object of class actiRhythm_mfdfa: a list with q_values, h_q (generalized Hurst exponent), tau_q (mass exponent), alpha/f_alpha (the multifractal spectrum), alpha_dfa (= h(2)) and the spectrum width. Returns an NA structure on insufficient data; never errors.

References

Kantelhardt JW, Zschiegner SA, Koscielny-Bunde E, Havlin S, Bunde A, Stanley HE (2002). “Multifractal detrended fluctuation analysis of nonstationary time series.” Physica A: Statistical Mechanics and its Applications, 316(1-4), 87–114. doi:10.1016/S0378-4371(02)01383-3.

See Also

fractal.dfa

Examples

set.seed(1)
mfdfa(stats::rnorm(4096))$alpha_dfa   # near 0.5 for white noise

Description

Computes Multiscale Sample Entropy (Costa et al., 2002, 2005), which applies Sample Entropy (Richman & Moorman, 2000) to coarse-grained versions of an activity time series across a range of temporal scales. MSE distinguishes genuinely complex signals (whose entropy is sustained or increases across scales, e.g. 1/f-like physiological signals) from uncorrelated random signals (whose entropy falls monotonically with scale).

Usage

multiscale.entropy(x, scales = 1:20, m = 2, r = 0.15)

Arguments

Details

For each scale tau the series is coarse-grained into non-overlapping means of length tau, then Sample Entropy is computed on the coarse-grained series with embedding dimension m and the FIXED absolute tolerance r * sd(x_original). Sample Entropy is the negative natural log of the conditional probability that two sub-sequences matching for m points (within the tolerance, Chebyshev distance, self-matches excluded) also match for m + 1 points.

Value

A list with class "actiRhythm_mse" containing:

mse

Numeric vector of SampEn values, one per requested scale (NA where the coarse-grained series is too short or yields no matches).

scales

Integer vector of the scale factors used.

area

Sum of mse over scales (complexity index), sum(mse, na.rm = TRUE).

slope

Slope of lm(mse ~ scales) over the non-NA points (negative => entropy declines with scale, typical of noise).

r_absolute

The absolute tolerance r * sd(x_original) used.

n_used

Length of the analyzed (longest non-NA) segment.

On an unusable series the entropy vector is all NA with the same structure (never an error).

See Also

fractal.dfa, circadian.rhythm

Examples

set.seed(1)
# White noise: entropy decreases with scale
multiscale.entropy(rnorm(2000))$mse
# 1/f-like (random walk): flatter / sustained entropy
multiscale.entropy(cumsum(rnorm(2000)))$mse

Description

Attaches a bootstrap confidence interval (and standard error) to the Lomb-Scargle period estimate from circadian.period. Because activity is strongly autocorrelated, an i.i.d. resample would destroy the rhythm and give an invalid (too-narrow) interval, so a circular moving-block bootstrap of the cosinor residuals is used: the rhythm fitted at the point estimate is held fixed while blocks of residuals are resampled, the periodogram peak is re-located on each replicate (with sub-grid parabolic refinement), and the interval is taken from the quantiles of the replicate periods.

Usage

period.ci(
  counts,
  timestamps,
  from = 18,
  to = 30,
  ofac = 4,
  n_boot = 200,
  block_hours = 24,
  level = 0.95,
  seed = NULL
)

Arguments

Value

An object of class actiRhythm_period_ci: a list with tau (the point estimate, hours), ci_lower/ci_upper, se, the level, the number of valid replicates, and tau_boot (the vector of bootstrap replicate periods).

References

Kunsch HR (1989). “The jackknife and the bootstrap for general stationary observations.” The Annals of Statistics, 17(3), 1217–1241. doi:10.1214/aos/1176347265.

Politis DN, Romano JP (1992). “A circular block-resampling procedure for stationary data.” In LePage R, Billard L (eds.), Exploring the Limits of Bootstrap, 263–270. Wiley, New York.

See Also

circadian.period

Examples

t_hours <- seq(0, 5 * 24 - 1/60, by = 1/60)
ts <- as.POSIXct("2024-01-01", tz = "UTC") + t_hours * 3600
counts <- 100 + 80 * cos(2 * pi * (t_hours - 8) / 24) + rnorm(length(t_hours), 0, 20)
period.ci(counts, ts, n_boot = 50, seed = 1)

Description

Tests whether a set of daily phase markers (acrophases, onsets, L5/M10 times) are concentrated rather than scattered around the clock. Reports the mean resultant vector, the Rayleigh test of uniformity (Fisher 1993), and the Hermans-Rasson test (Landler et al. 2019), which catches multimodal clustering that Rayleigh misses.

Usage

phase.concentration(times_h, period = 24, n_perm = 2000)

Arguments

Value

An object of class actiRhythm_phasetest: mean direction, mean resultant length R, and the Rayleigh and Hermans-Rasson statistics and p-values. Never errors.

References

Fisher NI (1993). Statistical Analysis of Circular Data. Cambridge University Press. doi:10.1017/CBO9780511564345.

Landler L, Ruxton GD, Malkemper EP (2019). “The Hermans-Rasson test as a powerful alternative to the Rayleigh test for circular statistics in biology.” BMC Ecology, 19, 30. doi:10.1186/s12898-019-0246-8.

Examples

set.seed(1)
onsets <- 23 + stats::rnorm(10, 0, 0.5)      # tightly clustered near 23:00
phase.concentration(onsets %% 24)

Description

Draws a classic double-plotted actogram: one row per calendar day, each row showing 48 hours (the day itself on the left, the following day on the right) so circadian phase can be traced down the diagonal. Activity is rendered as a per-minute raster (darker = more active). Non-wear (via wear_time) and missing time are left blank, and any skipped calendar days appear as empty rows.

Usage

plot_actogram(
  counts,
  timestamps,
  epoch_length = NULL,
  wear_time = NULL,
  double_plot = TRUE,
  L5_onset = NULL,
  M10_onset = NULL,
  sleep_mask = NULL,
  scale = c("linear", "sqrt")
)

Arguments

Value

A ggplot object. Never errors; returns an annotated empty plot on insufficient data.

Description

Plots the activity series with the per-night sleep-onset and wake-onset change points from sleep.changepoints marked and the detected sleep episodes shaded, so each night's rest timing is visible against the raw counts. Returns a ggplot object and never errors.

Usage

plot_changepoints(counts, timestamps, ...)

Arguments

Value

A ggplot object.

References

Chen S, Sun X (2024). “Validating CircaCP: a generic sleep-wake cycle detection algorithm for unlabelled actigraphy data.” Royal Society Open Science, 11(5), 231468. doi:10.1098/rsos.231468.

Examples

ts <- seq(as.POSIXct("2024-01-01", tz = "UTC"), by = 60, length.out = 5 * 1440)
h  <- as.numeric(format(ts, "%H"))
plot_changepoints(ifelse(h >= 8 & h < 23, 300, 5), ts)

Description

Draws the chi-square periodogram from chi.sq.periodogram: the $Q_P$ statistic against trial period, with the per-period chi-square significance threshold overlaid as a dashed line. The estimated period (the $Q_P$ peak) is marked and a 24-hour reference line drawn. Unlike the Lomb-Scargle plot, the explicit threshold shows directly whether a rhythm is significant at a given period.

Usage

plot_chisq(
  counts,
  timestamps,
  from = 18,
  to = 30,
  alpha = 0.05,
  epoch_length = NULL
)

Arguments

Value

A ggplot object. Never errors; returns an annotated empty plot on insufficient data.

See Also

plot_periodogram for the Lomb-Scargle spectrum.

Description

Draws the joint confidence ellipse of the cosinor cosine and sine coefficients on the amplitude-acrophase plane, over clock-hour spokes and amplitude rings. The estimate is the vector from the pole, and the rhythm is detectable when the ellipse excludes the pole (Bingham et al. 1982). Returns a ggplot object and never errors.

Usage

plot_cosinor_ellipse(counts, timestamps, period = 24, level = 0.95)

Arguments

Value

A ggplot object.

References

Bingham C, Arbogast B, Cornelissen Guillaume G, Lee JK, Halberg F (1982). “Inferential statistical methods for estimating and comparing cosinor parameters.” Chronobiologia, 9(4), 397–439.

Examples

set.seed(1)
ts <- seq(as.POSIXct("2024-01-01", tz = "UTC"), by = 60, length.out = 3 * 1440)
h  <- as.numeric(format(ts, "%H"))
counts <- pmax(0, 100 + 80 * cos(2 * pi * (h - 14) / 24) + rnorm(length(h), 0, 25))
plot_cosinor_ellipse(counts, ts)

Description

A teaching figure: one smooth cosine annotating the MESOR (midline), the amplitude A and double amplitude 2A, the acrophase (clock time of the peak), and the period. Useful as a legend for the cosinor parameters. Returns a ggplot object and never errors.

Usage

plot_cosinor_schematic(
  mesor = 100,
  amplitude = 50,
  acrophase = 16,
  period = 24
)

Arguments

Value

A ggplot object.

Examples

plot_cosinor_schematic()

Description

Runs fractal.dfa on an activity series and draws the detrended-fluctuation log-log scaling plot: log10(F(n)) against log10(n) (window size). A regression line whose slope is the overall scaling exponent alpha is overlaid, and when the analysis splits the scales at a breakpoint the short- (alpha1) and long-timescale (alpha2) segments are drawn separately. The exponents are annotated on the plot and an interpretive guide appears in the subtitle.

Usage

plot_dfa(counts)

Arguments

Details

DFA quantifies long-range temporal correlations. The scaling exponent is the slope of log10(F(n)) regressed on log10(n): alpha near 0.5 indicates uncorrelated (white) noise, alpha near 1.0 indicates 1/f (pink) noise, and alpha near 1.5 indicates Brownian (random-walk) noise. The scales, fluctuations, alpha, alpha1, alpha2 and breakpoint_min fields returned by fractal.dfa() drive the plot directly.

Value

A ggplot object: log10(F(n)) (y) versus log10(window size) (x) as points with fitted scaling line(s) and alpha/alpha1/alpha2 annotations. On an unusable series (too short, all-NA, or constant) an annotated empty ggplot is returned. The function never errors.

References

Peng CK, Buldyrev SV, Havlin S, Simons M, Stanley HE, Goldberger AL (1994). “Mosaic organization of DNA nucleotides.” Physical Review E, 49(2), 1685–1689. doi:10.1103/PhysRevE.49.1685.

Hu K, Van Someren EJW, Shea SA, Scheer FAJL (2009). “Reduction of scale invariance of activity fluctuations with aging and Alzheimer's disease: Involvement of the circadian pacemaker.” Proceedings of the National Academy of Sciences, 106(8), 2490–2494. doi:10.1073/pnas.0806087106.

See Also

fractal.dfa, multiscale.entropy

Examples

set.seed(1)
plot_dfa(cumsum(rnorm(5000)))   # Brownian-like, alpha near 1.5

Description

Cumulative distributions of the rest-span and active-span activity counts on a log scale, marking the active-span median and the dichotomy index I<O (the share of rest-span counts below that median). Returns a ggplot object and never errors.

Usage

plot_dichotomy(counts, rest)

Arguments

Value

A ggplot object.

References

Mormont MC, Waterhouse J, Bleuzen P, Giacchetti S, Jami A, Bogdan A, Lellouch J, Misset JL, Touitou Y, Levi F (2000). “Marked 24-h rest/activity rhythms are associated with better quality of life, better response, and longer survival in patients with metastatic colorectal cancer and good performance status.” Clinical Cancer Research, 6(8), 3038–3045.

Examples

ts <- seq(as.POSIXct("2024-01-01", tz = "UTC"), by = 60, length.out = 2 * 1440)
h  <- as.numeric(format(ts, "%H"))
plot_dichotomy(ifelse(h >= 23 | h < 7, 5, 300), rest = h >= 23 | h < 7)

Description

Stacks the intrinsic mode functions and residual trend from circadian.emd, finest at the top to the trend at the bottom, over a shared time axis, with the circadian IMF highlighted. Returns a ggplot object and never errors.

Usage

plot_emd(counts, timestamps, ensemble = 1L, epoch_length = 60)

Arguments

Value

A ggplot object.

References

Huang NE, Shen Z, Long SR, Wu MC, Shih HH, Zheng Q, Yen NC, Tung CC, Liu HH (1998). “The empirical mode decomposition and the Hilbert spectrum for nonlinear and non-stationary time series analysis.” Proceedings of the Royal Society A, 454(1971), 903–995. doi:10.1098/rspa.1998.0193.

Examples

ts <- seq(as.POSIXct("2024-01-01", tz = "UTC"), by = 600, length.out = 8 * 144)
th <- as.numeric(difftime(ts, ts[1], units = "hours"))
plot_emd(100 + 60 * cos(2 * pi * th / 24) + 20 * cos(2 * pi * th / 8), ts, epoch_length = 600)

Description

Builds the averaged 24-hour activity profile and overlays two model fits for comparison: the Marler (2006) anti-logistic extended cosinor from cosinor.antilogistic (drawn as a bold solid curve) and the ordinary single-component cosinor from cosinor.analysis (drawn as a dashed curve). The acrophase (time of peak) is marked with a vertical line and the extended-fit parameters are shown in the subtitle.

Usage

plot_extended_cosinor(counts, timestamps, period = 24)

Arguments

Details

The profile is the mean activity in each clock-hour bin averaged across all recorded days (bin centres at hour + 0.5), matching the profile that cosinor.analysis() and cosinor.antilogistic() fit internally. The fitted curves are evaluated on a dense 0-24 h grid:

• Extended (Marler): $f(t) = minimum + amplitude \cdot expit(\beta (cos(2\pi (t - acrotime)/T) - \alpha))$, using the minimum, amplitude, alpha, beta and acrotime returned by cosinor.antilogistic().

• Ordinary: $M + A cos(2\pi (t - acrophase)/T)$, using the mesor, amplitude and acrophase from cosinor.analysis().

The subtitle reports the extended-fit MESOR, amplitude, the alpha width-asymmetry and the beta steepness when the fit converged.

Value

A ggplot object: the averaged hourly profile (points and a light connecting line) over hour-of-day 0-24, with the extended and ordinary cosinor curves overlaid. If the extended fit does not converge the profile and ordinary cosinor are still drawn with a "did not converge" note; on insufficient data an annotated empty ggplot is returned. The function never errors.

References

Marler MR, Gehrman P, Martin JL, Ancoli-Israel S (2006). “The sigmoidally transformed cosine curve: a mathematical model for circadian rhythms with symmetric non-sinusoidal shapes.” Statistics in Medicine, 25(22), 3893–3904. doi:10.1002/sim.2466.

Cornelissen G (2014). “Cosinor-based rhythmometry.” Theoretical Biology and Medical Modelling, 11, 16. doi:10.1186/1742-4682-11-16.

See Also

cosinor.antilogistic, cosinor.analysis

Examples

ts <- seq(as.POSIXct("2024-01-01 00:00:00"), by = 60, length.out = 1440 * 7)
hour <- as.numeric(format(ts, "%H")) + as.numeric(format(ts, "%M")) / 60
counts <- 50 + 300 * plogis(4 * (cos((hour - 14) * 2 * pi / 24) - 0.2)) +
  rnorm(length(ts), 0, 10)
plot_extended_cosinor(counts, ts)