πŸ¦‹ Rtractor

Complexity and nonlinear time series analysis for physiological signals β€” entropy, fractal/multifractal measures, Lyapunov exponents, multiscale metrics, and recurrence quantification analysis.

r-universe License: GPL (>= 2) R R CMD CHECK Coverage Status pkgdown


[!WARNING] Rtractor is in early development and several planned families are not yet implemented (Lyapunov exponents, phase-space embedding, general recurrence quantification measures). Implemented functions have been validated against reference implementations or ground-truth synthetic data where one exists (see each function's documentation and inst/COPYRIGHTS), but the package as a whole has not undergone peer review and the API may change without notice. Verify outputs independently before using in any research context.


πŸ“– What is Rtractor?

Rtractor is a shared "complexity toolkit" for the Circadia Lab / CoDe-Neuro Lab ecosystem: a single home for the nonlinear dynamics and complex-systems measures (entropy, fractal dimension, Lyapunov exponents, multiscale entropy, recurrence quantification) that otherwise get reimplemented piecemeal inside signal-specific packages like mrpheus, zeitR, and dynR.

Like hypnoR, Rtractor is signal-agnostic: every metric accepts a plain numeric time series regardless of where it came from β€” EEG, actigraphy, BOLD, HRV, or anything else β€” rather than assuming a specific data source or staging scheme.

Where possible, Rtractor wraps existing, well-validated C/C++/Fortran reference implementations via Rcpp rather than reimplementing algorithms from scratch in R, to preserve numerical parity with the original methods literature.

✨ Planned features

None of the Lyapunov metric functions are implemented yet. Currently working: dfa(), higuchi_fd(), mfdma(), chhabra_jensen(), petrosian_fd(), hjorth_parameters(), num_zerocross() (fractal family), perm_entropy(), sample_entropy() (entropy family), multiscale_entropy() (multiscale family), recurrence_microstate_entropy() (RQA family), and pmodel() (simulate family, for generating synthetic test signals). See NEWS.md for progress.

πŸ—‚οΈ Project Structure

Rtractor/
β”œβ”€β”€ R/
β”‚   β”œβ”€β”€ Rtractor-package.R   # package-level doc / Rcpp registration
β”‚   β”œβ”€β”€ entropy.R            # perm_entropy(), sample_entropy()
β”‚   β”œβ”€β”€ fractal.R            # dfa(), higuchi_fd(), mfdma(), chhabra_jensen(),
β”‚   β”‚                       # petrosian_fd(), hjorth_parameters(), num_zerocross()
β”‚   β”œβ”€β”€ lyapunov.R           # planned: Rosenstein/Wolf
β”‚   β”œβ”€β”€ multiscale.R         # multiscale_entropy(); planned: RCMSE
β”‚   β”œβ”€β”€ rqa.R                # recurrence_microstate_entropy(); planned: RQA measures
β”‚   β”œβ”€β”€ embed.R              # planned: phase-space reconstruction utils
β”‚   β”œβ”€β”€ simulate.R           # pmodel() -- synthetic multifractal test signals
β”‚   β”œβ”€β”€ palettes.R           # rtractor_palette(), rtractor_palettes()
β”‚   β”œβ”€β”€ scales.R             # scale_{colour,fill}_rtractor(_c)()
β”‚   └── theme.R              # theme_rtractor()
β”œβ”€β”€ src/
β”‚   β”œβ”€β”€ dfa.cpp              # DFA β€” wraps PhysioNet's dfa.c (GPL-2+)
β”‚   β”œβ”€β”€ higuchi.cpp          # Higuchi FD β€” clean-room reimplementation
β”‚   β”œβ”€β”€ fractal_multifractal.cpp  # MFDMA, Chhabra-Jensen β€” clean-room
β”‚   β”œβ”€β”€ fractal_nonlinear.cpp     # Petrosian FD, Hjorth, zero-crossings β€” from mrpheus
β”‚   β”œβ”€β”€ entropy.cpp          # Permutation entropy β€” from mrpheus
β”‚   β”œβ”€β”€ sample_entropy.cpp   # Sample/multiscale entropy β€” wraps PhysioNet's mse.c (GPL-2+)
β”‚   └── microstates.cpp      # Recurrence microstates entropy β€” wraps MIT code
β”œβ”€β”€ inst/
β”‚   └── COPYRIGHTS           # attribution for wrapped/ported reference code
β”œβ”€β”€ vignettes/
β”‚   β”œβ”€β”€ getting-started.Rmd       # tour of every implemented family
β”‚   β”œβ”€β”€ multifractal-methods.Rmd  # mfdma() vs chhabra_jensen(), validated against pmodel() ground truth
β”‚   └── entropy-and-complexity.Rmd  # perm_entropy/sample_entropy/multiscale_entropy, white noise vs correlated signal
β”œβ”€β”€ tests/testthat/
β”œβ”€β”€ man/
β”œβ”€β”€ DESCRIPTION
└── NEWS.md

πŸš€ Getting Started

Prerequisites

Installation

# once published on r-universe:
install.packages("Rtractor", repos = c(
  "https://circadia-bio.r-universe.dev",
  "https://cloud.r-project.org"
))

# or directly from GitHub:
remotes::install_github("circadia-bio/Rtractor")

Design principles

πŸ“¦ Dependencies

Package Purpose
Rcpp Wrapping C/C++/Fortran reference implementations
ggplot2 (Suggests) theme_rtractor() and the scale_*_rtractor() family
testthat (Suggests) Unit testing

πŸ‘₯ Authors

Role Name Affiliation
Author, maintainer Lucas FranΓ§a Northumbria University, Circadia Lab
Author Mario Leocadio-Miguel Northumbria University, Circadia Lab

🀝 Related Tools

πŸ“„ Licence

Released under the GNU General Public License, version 2 or later (GPL (>= 2)). Some wrapped reference implementations are themselves GPL-licensed β€” see inst/COPYRIGHTS for attribution and citation requirements.

Copyright Β© Circadia Lab, 2026