Skip to contents

🪉 mrpheus

Raw physiological signal analysis for biological rhythms research.

r-universe License: MIT R R CMD CHECK Coverage Status pkgdown Circadia Lab

📖 What is mrpheus?

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 Mrpheus 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.

✨ Features

🗂️ Project Structure 

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()
│   ├── compute_hrv_freq.R          # compute_hrv_freq()
│   ├── 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

🚀 Getting Started

Installation

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")

Prerequisites

The staging model requires LightGBM. If the r-universe binary does not install it automatically:

install.packages("lightgbm")   # CRAN binary

Full PSG pipeline 

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)

📦 Dependencies

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)

📄 Citation

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}
}

👥 Authors

Role Name Affiliation
Author, maintainer Lucas França Northumbria University, Circadia Lab
Author Mario Leocadio-Miguel Circadia Lab
  • ⌚️ zeitR — wrist actigraphy analysis and circadian metrics
  • 😵‍💫 hypnor — hypnogram handling, sleep architecture metrics, and visualisation
  • 🔄 syncR — unified participant-indexed database (actigraphy + PSG + diary)
  • 🧲 boldR — fMRIPrep BOLD derivatives → parcellated analysis
  • 🧮 tallieR — sociodemographics and questionnaires
  • 🛌 slumbR — sleep diary processing
  • 🎨 circadia — shared visual identity (palettes, themes)
  • 🔬 circadia-bio — the Circadia Lab GitHub organisation

📄 Licence

Released under the MIT License.

Copyright © Lucas França, Mario Leocadio-Miguel, 2026

Staging model attribution: The LightGBM model bundled in inst/models/yasa_staging.txt was 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.