bosc
bosc implements behavioral oscillation scoring, phase analysis, and
clustering for behavioral and neural time series. Core methods follow Ter Wal
et al. (2021) and the
behavioral-oscillations
reference software; grouped trial-level and subject-level spectral workflows
extend those methods for dense behavioral sampling.
Documentation
Full pkgdown site: https://bbuchsbaum.github.io/bosc/
Vignettes
- Get started with bosc -- End-to-end introduction to the package workflow and core objects.
- Oscillation Score Analysis -- Computing oscillation scores, surrogate testing, multi-band analysis, and narrowband Hilbert phase extraction.
- PPC Analysis and Cluster Detection -- Pairwise phase consistency, circular statistics, cluster-based permutation testing on time-frequency maps.
- Workflow Wrappers -- High-level config-driven wrappers, batch analysis, phase-at-events pipeline, and tidy output helpers.
Install
Install dependencies (imager, signal, pracma, fitdistrplus, circular, ggplot2, etc.) first, then:
devtools::load_all("bosc") # for development
# or install locally
devtools::install("bosc")
imager may require system image libraries (PNG/JPEG); install via your package manager before install.packages("imager").
Modules (current)
- Signal utils:
make_continuous_trace, autocorr_centered, spectral_peak.
- O-score:
oscillation_score, oscillation_score_surrogates.
- Workflow wrappers:
oscillation_score_config, oscillation_score_surrogates_config, oscillation_score_z, phase_at_events.
- Tidy helpers:
oscore_tidy, oscore_spectrum, clusters_tidy, clusters_pixels.
- Hilbert:
narrowband_hilbert.
- PPC/Stats:
pairwise_phase_consistency, u_score_matrix, paired_tscore, nonparam_pval.
- Clustering:
extract_clusters, detect_clusters (imager-based watershed/extract, cluster splitting).
- Plotting:
plot_spectrum, plot_phase_hist.
Relation to the reference MATLAB toolbox
bosc implements methods from Ter Wal et al. (2021) in R. It is not a
line-by-line translation of the
behavioral-oscillations
MATLAB toolbox: the API, return objects, grouped-analysis workflows, and several
algorithm extensions are native to this package. The sections below note
specific places where behavior intentionally differs from the reference
implementation.
spectral_peak(fcor = TRUE) uses an explicit, stable log-log fit/predict path
in R for improved numerical stability.oscillation_score() supports explicit signal_mode:
event uses event-rate-based effective bands; continuous uses
variance-aware checks and Nyquist-limited upper bounds.autocorr_centered() now supports both direct and FFT-based linear
autocorrelation; method = "auto" selects a fast FFT path for longer vectors
while preserving centered xcorr semantics.oscillation_score_surrogates() supports explicit surrogate_method,
including phase-randomized surrogates for continuous signals
(amplitude-spectrum-preserving nulls), in addition to event shuffle/trend.oscillation_score_z() can return bootstrap confidence intervals for the
log-Z statistic (z_ci) and exposes CI controls (ci_nboot, ci_level).extract_clusters() uses a direct 8-connectivity flood-fill implementation
for consistent connected-component assignments.circ_rayleigh() uses weighted sample size (sum(w)) in weighted mode.paired_tscore() uses per-slice effective sample sizes under missing values.detect_clusters(qval=...) computes adjusted p-values, and optional
filter_by_q=TRUE can filter clusters by adjusted significance.
Testing
devtools::test("bosc")
References
bosc implements methods described in Ter Wal et al. (2021). If you use this
package in published work, please cite that paper and, when appropriate, the
reference MATLAB software:
Ter Wal, M., Linde-Domingo, J., Lifanov, J., Roux, F., Kolibius, L., Gollwitzer, S., Lang, J., Hamer, H., Rollings, D., Sawlani, V., Chelvarajah, R., Staresina, B., Hanslmayr, S., & Wimber, M. (2021). Theta rhythmicity governs the timing of behavioural and hippocampal responses in humans specifically during memory-dependent tasks. Nature Communications, 12, 7048. https://doi.org/10.1038/s41467-021-27323-3
Dense-sampling trial-to-spectrum workflows in the grouped APIs and examples are also motivated by:
Biba, T. M., Decker, A., Herrmann, B., Fukuda, K., Katz, C. N., Valiante, T. A., & Duncan, K. (2026). Episodic memory encoding fluctuates at a theta rhythm of 3-10 Hz. Nature Human Behaviour. https://doi.org/10.1038/s41562-026-02416-5
Roadmap
- CI (R CMD check, lintr).
- Data I/O helpers for MAT/HDF5 and richer plotting wrappers.
Albers theme
This package uses the albersdown theme. Existing vignette theme hooks are replaced so albers.css and local albers.js render consistently on CRAN and GitHub Pages. The palette family is provided via params$family (default 'lapis'). The pkgdown site uses template: { package: albersdown }.
