Raw physiological signal analysis for biological rhythms research.
mrpheus is the raw signal layer of the Circadia Lab R ecosystem. It ingests and processes multi-modal physiological recordings β polysomnography (EDF/EDF+), MRI-concurrent physiological logs (Philips PMU), and EEG β and extracts features across three biological rhythm domains: cardiac (QRS detection, HRV), respiratory (apnoea detection, respiratory metrics), and neural (sleep spindles, slow oscillations, automatic AASM sleep staging).
Staged hypnograms and derived metrics pass downstream to hypnor and syncR for cross-modal linking.
The name is spelled as Morpheus but carries a silent m, pronounced as Orpheus β carrying both myths at once. Morpheus, god of dreams, gives the package its subject; Orpheus, who descended into the underworld to navigate the unconscious, gives it its spirit.
read_edf(), prepare_psg(): channel inventory, epoch segmentation, bad-channel flaggingpreprocess_psg(): channel renaming, DC removal, powerline notch (50/60 Hz + harmonics), per-channel-type bandpass filtering; operates on the full continuous signal before re-epochingremove_dc(), detect_powerline(), notch_filter(), bandpass_filter(): exported functions that work on any plain numeric vectorcorrect_eog_regression() (linear regression, no blink detection required), correct_eog_ica() (FastICA, threshold-based component rejection)detect_artifacts(): amplitude and muscle contamination flaggingcompute_band_power() (Ξ΄/ΞΈ/Ξ±/Ο/Ξ²/Ξ³ per epoch, YASA-validated Welch PSD), compute_temporal_bandpower() (sliding-window band power across the full night), compute_spectrogram()
compute_spindles(), compute_slow_oscillations()
stage_epochs(): pre-trained LightGBM model ported from YASA (Vallat & Walker, 2021); 77.8 % epoch accuracy on Sleep-EDF Cassettedetect_apneas(), compute_ahi(), compute_odi()
detect_qrs() (Pan-Tompkins), compute_hr_signal(), compute_hrv_sleep()
read_philips_physlog(): wBTU / wired / custom presets, event markers, scan-window alignmentexport_hypnogram() β hypnor; derived metrics β syncR
mrpheus/
βββ R/
β βββ mrpheus-package.R # package doc + palette_orpheus
β βββ read_edf.R # read_edf(), print.mrpheus_edf
β βββ prepare_psg.R # prepare_psg(), print.mrpheus_psg
β βββ signal_filters.R # remove_dc(), detect_powerline(),
β β # notch_filter(), bandpass_filter()
β βββ preprocess_psg.R # preprocess_psg()
β βββ correct_eog.R # correct_eog_regression(), correct_eog_ica()
β βββ detect_artifacts.R # detect_artifacts()
β βββ compute_band_power.R # compute_band_power()
β βββ compute_temporal_bandpower.R# compute_temporal_bandpower()
β βββ compute_spectrogram.R # compute_spectrogram()
β βββ compute_spindles.R # compute_spindles()
β βββ compute_slow_oscillations.R
β βββ compute_hr_signal.R # compute_hr_signal()
β βββ compute_hrv_sleep.R # compute_hrv_sleep()
β βββ stage_epochs.R # stage_epochs()
β βββ staging_features.R # internal YASA feature extraction
β βββ export_hypnogram.R # export_hypnogram()
β βββ detect_qrs.R # detect_qrs(), print.mrpheus_qrs
β βββ detect_apneas.R # detect_apneas(), compute_ahi(), compute_odi()
β βββ read_philips_physlog.R # read_philips_physlog()
βββ src/
β βββ staging_features.cpp # Rcpp hot paths: staging pipeline
β βββ event_detection.cpp # Rcpp hot paths: spindles, slow oscillations
βββ inst/
β βββ extdata/ # example_physlog.log
β βββ filters/ # MNE FIR + resample poly coefficients
β βββ models/ # serialised LightGBM staging model
βββ data-raw/ # model extraction, parity validation scripts
βββ tests/testthat/
βββ vignettes/
β βββ getting-started.Rmd
β βββ mri-physiology.Rmd
β βββ sleep-staging.Rmd
β βββ eeg-preprocessing.Rmd
β βββ spectral-analysis.Rmd
βββ _pkgdown.yml
βββ DESCRIPTION
Install from r-universe (recommended β pre-built binaries, no compiler required):
install.packages(
"mrpheus",
repos = c("https://circadia-bio.r-universe.dev", "https://cloud.r-project.org")
)
Or install the development version from GitHub:
# install.packages("remotes")
remotes::install_github("circadia-bio/mrpheus")
The staging model requires LightGBM. If the r-universe binary does not install it automatically:
install.packages("lightgbm") # CRAN binary
library(mrpheus)
# 1. Ingest
rec <- read_edf("psg_001.edf")
psg <- prepare_psg(rec)
# 2. Preprocess
psg <- preprocess_psg(
psg,
channel_rename = c("C3-A2" = "C3", "C4-A1" = "C4") # if needed
)
# 3. EOG correction
psg <- correct_eog_regression(psg) # or correct_eog_ica()
# 4. Stage
stages <- stage_epochs(psg)
# 5. Band power
bp <- compute_band_power(psg, relative = TRUE)
tbp <- compute_temporal_bandpower(psg, hypno = stages$stage)
# 6. Events
sp <- compute_spindles(psg)
so <- compute_slow_oscillations(psg)
# 7. Export to hypnor
hypnogram <- export_hypnogram(stages, start_time = rec$header$startTime)
| Package | Version | Purpose |
|---|---|---|
edfReader |
>= 1.2.1 | EDF/EDF+ file ingestion |
gsignal |
>= 0.3.5 | IIR filter design, Welch PSD |
pracma |
>= 2.4.2 | Numerical utilities |
lightgbm |
>= 4.0.0 | YASA staging model inference |
fastICA |
>= 1.2-0 | ICA decomposition for EOG correction |
dplyr |
>= 1.1.0 | Tabular manipulation |
tibble |
>= 3.2.0 | Tidy output structures |
cli |
>= 3.6.0 | Diagnostic messages |
rlang |
>= 1.1.0 | Error handling |
Rcpp |
>= 1.0.10 | C++ hot-path implementations (feature extraction, rolling statistics, event detection) |
If you use the automatic sleep staging feature, please also cite the YASA paper:
@article{vallat2021,
author = {Vallat, Raphael and Walker, Matthew P},
title = {An open-source, high-performance tool for automated sleep staging},
journal = {eLife},
volume = {10},
pages = {e70092},
year = {2021},
doi = {10.7554/eLife.70092}
}
| Role | Name | Affiliation |
|---|---|---|
| Author, maintainer | Lucas FranΓ§a | Northumbria University, Circadia Lab |
| Author | Mario Leocadio-Miguel | Circadia Lab |
Released under the MIT License.
Copyright Β© Lucas FranΓ§a, Mario Leocadio-Miguel, 2025
Staging model attribution: The LightGBM model bundled in
inst/models/yasa_staging.txtwas originally trained as part of YASA (Vallat & Walker, eLife, 2021; doi:10.7554/eLife.70092) and is redistributed here under YASA's BSD 3-Clause License with attribution.