PhysioAnalysis

Analysis and Visualization for PhysioExperiment Objects

PhysioAnalysis provides 43 exported functions for spectral analysis, time-frequency decomposition, epoching, functional connectivity, statistical testing, and publication-quality visualization of multi-modal physiological signals. Built on PhysioCore, it operates directly on PhysioExperiment objects and covers the full analysis workflow from raw epochs to statistical inference and topographic visualization.

Installation

You can install PhysioAnalysis from r-universe:

# the containers build on Bioconductor, so its repositories are needed too
install.packages("BiocManager", repos = "https://cloud.r-project.org")
install.packages("PhysioAnalysis",
  repos = c("https://x-biosignal.r-universe.dev", BiocManager::repositories()))

Or install the development version from GitHub:

# install.packages("remotes", repos = "https://cloud.r-project.org")
remotes::install_github("x-biosignal/PhysioAnalysis")

Quick Start

library(PhysioAnalysis)

# Create sample EEG data with stimulus events
signal_matrix <- matrix(rnorm(2500 * 4), nrow = 2500, ncol = 4)
pe <- PhysioExperiment(
  assays = list(raw = signal_matrix),
  samplingRate = 250
)
pe <- addEvents(pe, onset = c(1, 3, 5, 7), duration = 0, type = "stimulus")

# Spectral power in standard frequency bands (delta..gamma)
power <- bandPower(pe)

# Epoch around stimulus events (-0.2 to 0.8 s)
pe_epoched <- epochData(pe, event_type = "stimulus", tmin = -0.2, tmax = 0.8)

# Compute the trial-averaged ERP
erp <- averageEpochs(pe_epoched)

# Visualize the event-related potential for the first channel
plotERP(pe_epoched, channel = 1)

Features

FFT and Spectral Analysis

Frequency-domain analysis and spectral decomposition:

fftSignals() -- compute FFT magnitude and phase spectra for all channels
bandPower() -- extract power in standard frequency bands (delta, theta, alpha, beta, gamma) or custom ranges
hilbertTransform() -- analytic signal via Hilbert transform for envelope extraction
instantaneousAmplitude(), instantaneousPhase() -- extract amplitude envelope and instantaneous phase from analytic signals

Time-Frequency Analysis

Multi-resolution time-frequency decomposition:

spectrogram() -- short-time Fourier transform (STFT) with configurable window and overlap
waveletTransform() -- continuous wavelet transform (Morlet) for time-frequency representations
plotSpectrogram() -- visualize time-frequency power maps with customizable color scales

Epoching

Trial segmentation and averaging:

epochData() -- segment continuous data into time-locked epochs around events
averageEpochs() -- compute trial-averaged waveforms (e.g., ERPs, ERFs)
grandAverage() -- compute grand averages across subjects or sessions
epochTimes() -- retrieve the time vector for epoched data

Connectivity Analysis

Functional and effective connectivity metrics:

Spectral coherence: coherence(), crossSpectrum() -- frequency-domain measures of linear coupling
Phase synchrony: plv() (Phase Locking Value), pli() (Phase Lag Index), wPLI() (weighted Phase Lag Index) -- volume conduction-robust phase metrics
Correlation: correlationMatrix() -- pairwise amplitude correlations across channels
General interface: connectivityMatrix() -- compute any connectivity metric as a channel-by-channel matrix

Statistical Testing

Parametric, non-parametric, and mass-univariate statistical methods:

Classical tests: tTestEpochs(), anovaEpochs() -- point-by-point or window-based parametric tests across conditions
Cluster permutation: clusterPermutationTest() -- non-parametric cluster-based permutation testing for family-wise error control over space and time
Effect sizes: effectSize() -- Cohen's d, Hedges' g, and eta-squared
Confidence intervals: bootstrapCI() -- bootstrap confidence intervals for any statistic
Multiple comparisons: correctPValues() -- FDR (Benjamini-Hochberg) and Bonferroni correction
Temporal analysis: findSignificantWindows() -- identify contiguous time windows with significant effects
SPM methods: spmTTest(), spmPairedTTest(), spmAnova() -- Statistical Parametric Mapping for continuous signal analysis

Visualization

Publication-quality plots for physiological signal data:

Time series: plotSignal() -- single-channel waveform display with event markers
Multi-channel: plotMultiChannel() -- stacked multi-channel display with vertical offset and scaling
ERP plots: plotERP() -- event-related potential waveforms with confidence bands and condition overlays
Power spectra: plotPSD() -- power spectral density plots with frequency band shading
Topographic maps: plotTopomap() -- scalp topography with channel markers and either Shepard inverse-distance weighting (default) or Perrin spherical-spline interpolation
Topomap series: plotTopomapSeries() -- temporal evolution of scalp topography at multiple time points
Spectrogram: plotSpectrogram() -- time-frequency power maps with configurable color scales

Dependencies

R (>= 4.2)
PhysioCore -- core data structures
signal -- DSP primitives
methods, SummarizedExperiment, S4Vectors, stats, graphics, grDevices
Suggests: ggplot2, testthat, knitr, rmarkdown

PhysioExperiment Ecosystem

PhysioAnalysis is part of the PhysioExperiment ecosystem, a suite of R packages for multi-modal physiological signal analysis:

Package	Description
PhysioCore	Core data structures and accessors
PhysioIO	File I/O (EDF, HDF5, BIDS, CSV, MAT)
PhysioPreprocess	Signal preprocessing and artifact removal
PhysioAnalysis	Spectral analysis, epoching, statistics, visualization
PhysioMoCap	Motion capture data processing
PhysioOpenSim	OpenSim biomechanical modeling integration

Visit the r-universe page to browse all available packages.

License

MIT License. See LICENSE for details.

Author

Yusuke Matsui

Governance & support

Part of the Physio ecosystem. Community and policy documents live in the umbrella repository: