Package 'mrpheus'

Description

Calculates the AHI from respiratory event data and total sleep time.

Usage

compute_ahi(events, tst_hours)

Arguments

Value

Numeric scalar. AHI (events per hour).

Description

Estimates power spectral density (PSD) using Welch's method and integrates power within standard EEG frequency bands (delta, theta, alpha, sigma, beta, gamma) for each epoch and each specified channel. Mirrors the band-power feature extraction used by YASA's staging pipeline.

Usage

compute_band_power(
  psg,
  channels = NULL,
  bands = list(delta = c(0.5, 4), theta = c(4, 8), alpha = c(8, 13), sigma = c(13, 16),
    beta = c(16, 30), gamma = c(30, 40)),
  relative = FALSE,
  window_s = 4,
  overlap = 0.5
)

Arguments

list(delta = c(0.5, 4), theta = c(4, 8), alpha = c(8, 13),
     sigma = c(13, 16), beta = c(16, 30), gamma = c(30, 40))

Value

A tibble with columns epoch, channel, one column per band, and total_power. Units are µV²/Hz (or dimensionless if relative = TRUE).

Examples

## Not run: 
bp <- compute_band_power(psg)
bp <- compute_band_power(psg, channels = "EEG Fpz-Cz", relative = TRUE)

## End(Not run)

Description

Extracts R-peak positions from the ECG channel, computes standard time- and frequency-domain heart rate variability (HRV) metrics, and stratifies results by sleep stage.

Usage

compute_hrv_sleep(
  psg,
  staging = NULL,
  ecg_channel = NULL,
  min_rr_ms = 300,
  max_rr_ms = 2000
)

Arguments

Value

A tibble with one row per sleep stage (or one row if staging is NULL):

stage

Character. AASM stage or "ALL".

n_epochs

Integer. Number of epochs in this stage.

mean_rr_ms

Numeric. Mean RR interval (ms).

sdnn_ms

Numeric. SDNN — SD of all NN intervals.

rmssd_ms

Numeric. RMSSD — root mean square of successive differences.

lf_power

Numeric. LF band power (0.04–0.15 Hz).

hf_power

Numeric. HF band power (0.15–0.4 Hz).

lf_hf_ratio

Numeric. LF/HF ratio.

Description

Calculates the ODI (number of >= 3% SpO2 desaturations per hour of sleep) from the SpO2 channel.

Usage

compute_odi(psg, spo2_channel, tst_hours, threshold = 3)

Arguments

Value

Numeric scalar. ODI (desaturations per hour).

Description

Detects slow oscillations (SOs) in EEG channels using a zero-crossing approach in the delta band (0.5–2 Hz), following the algorithm described in Mölle et al. (2002) and implemented in YASA (Vallat & Walker, 2021).

Usage

compute_slow_oscillations(
  psg,
  channel = NULL,
  stages = NULL,
  freq_so = c(0.5, 2),
  amp_ptp_threshold_uv = c(75, 500),
  duration_pos_s = c(0.1, 1),
  duration_neg_s = c(0.1, 1.5)
)

Arguments

Value

A tibble with one row per detected slow oscillation:

epoch

Integer.

start_s

Numeric. Onset (s) relative to epoch start.

end_s

Numeric. Offset (s) relative to epoch start.

duration_s

Numeric.

neg_peak_uv

Numeric. Negative peak amplitude (µV).

pos_peak_uv

Numeric. Positive peak amplitude (µV).

ptp_uv

Numeric. Peak-to-peak amplitude (µV).

channel

Character.

References

Mölle, M., Marshall, L., Gais, S., & Born, J. (2002). Grouping of spindle activity during slow oscillations in human non-rapid eye movement sleep. Journal of Neuroscience, 22(24), 10941–10947.

Vallat, R., & Walker, M. P. (2021). An open-source, high-performance tool for automated sleep staging. eLife, 10, e70092. doi:10.7554/eLife.70092

Description

Generates a short-time Fourier transform (STFT) based spectrogram for a single PSG channel across all epochs. Returns power (µV²/Hz) as a matrix with time (epochs) on rows and frequency on columns.

Usage

compute_spectrogram(
  psg,
  channel = NULL,
  freq_range = c(0, 40),
  window_s = 2,
  overlap = 0.5,
  db = TRUE
)

Arguments

Value

A list of class mrpheus_spectrogram with:

power

Numeric matrix. Rows = epochs, columns = frequency bins.

freqs

Numeric vector. Frequency bin centres (Hz).

epochs

Integer vector. Epoch indices.

channel

Character. The channel label.

db

Logical. Whether power is in dB.

Description

Detects sleep spindles in EEG channels using a band-pass / RMS envelope approach, closely following the algorithm in Lacourse et al. (2019) and implemented in YASA (Vallat & Walker, 2021). Spindles are identified as transient bursts of 11–16 Hz activity during NREM sleep.

Usage

compute_spindles(
  psg,
  channel = NULL,
  stages = NULL,
  freq_spindle = c(11, 16),
  rms_window_s = 0.3,
  min_duration_s = 0.5,
  max_duration_s = 3,
  threshold_sd = 1.5
)

Arguments

Value

A tibble with one row per detected spindle:

epoch

Integer. Epoch in which the spindle was detected.

start_s

Numeric. Spindle onset relative to epoch start (seconds).

end_s

Numeric. Spindle offset relative to epoch start (seconds).

duration_s

Numeric. Spindle duration in seconds.

peak_freq_hz

Numeric. Peak frequency within the spindle.

rms_uv

Numeric. Mean RMS amplitude within the spindle (µV).

channel

Character. Channel label.

References

Lacourse, K., Yetton, B., Mednick, S., & Bhatt, D. L. (2019). Massive online sleep staging: A polysomnography data repository. Journal of Sleep Research.

Vallat, R., & Walker, M. P. (2021). An open-source, high-performance tool for automated sleep staging. eLife, 10, e70092. doi:10.7554/eLife.70092

Description

Detects apneas and hypopneas in respiratory airflow and effort signals, returning event-level metadata and summary indices. Detection follows AASM 2012/2017 criteria: >= 90% signal reduction for >= 10 s (apnea), or >= 30% reduction with >= 3% SpO2 desaturation or arousal for >= 10 s (hypopnea).

Usage

detect_apneas(
  psg,
  airflow_channel = NULL,
  spo2_channel = NULL,
  min_duration_s = 10,
  apnea_threshold = 0.9,
  hypopnea_threshold = 0.3,
  desaturation_threshold = 3
)

Arguments

Value

A list with:

events

Tibble. One row per event: epoch, start_s, end_s, duration_s, type ("apnea" / "hypopnea"), desaturation.

summary

Tibble. n_apneas, n_hypopneas, n_events.

See Also

compute_ahi(), compute_odi()

Description

Flags epochs containing likely artefacts based on amplitude thresholds, excessive high-frequency (muscle) power, and movement contamination. Operates on the EEG channels by default. Returns a logical vector (one value per epoch) and optionally attaches per-epoch artefact metrics for inspection.

Usage

detect_artifacts(
  psg,
  channels = NULL,
  amp_threshold_uv = 500,
  hf_band = c(40, 100),
  hf_percentile = 0.99,
  verbose = TRUE
)

Arguments

Value

A tibble with one row per epoch and columns:

epoch

Integer. Epoch index (1-based).

artefact

Logical. TRUE if the epoch is flagged as artefact.

reason

Character. Comma-separated reasons for flagging, or NA.

peak_to_peak_uv

Numeric. Maximum peak-to-peak amplitude across selected channels.

hf_power_db

Numeric. Mean HF band power (dB) across selected channels.

Description

Prepares the staging tibble produced by stage_epochs() for downstream use with the hypnor package. Attaches recording metadata as attributes and returns a tibble of class mrpheus_hypnogram, which hypnor::new_hypnogram() accepts directly once hypnor is installed.

Usage

export_hypnogram(
  staging,
  epoch_s = 30,
  start_time = NULL,
  participant_id = NULL
)

Arguments

Value

A tibble of class mrpheus_hypnogram with columns epoch, stage, and any probability columns from the staging model. Metadata (epoch_s, start_time, participant_id, source, resolution) are attached as attributes and forwarded to hypnor::new_hypnogram() when hypnor is available.

See Also

stage_epochs()

Description

An 8-colour palette extracted from the Roman mosaic Orpheus Charming the Animals (3rd century AD, Palermo Archaeological Museum). The mosaic depicts Orpheus — the mythological figure whose name and story this package honours — surrounded by animals, rendered in warm Mediterranean tesserae.

Usage

palette_orpheus

Format

A named character vector of 8 hex colour codes:

sand

⁠#CDB992⁠ — warm background tessera

vermillion

⁠#B83E2C⁠ — Orpheus's robe; terracotta

olive

⁠#6A7840⁠ — tree and vegetation

umber

⁠#7C5432⁠ — animal fur and earth

bistre

⁠#3C2212⁠ — shadows and outlines

ochre

⁠#B07C3A⁠ — warm amber accent

slate

⁠#6C8284⁠ — birds; dusty teal-grey

ivory

⁠#EAD6AA⁠ — highlights and light tessera

Details

The palette is intentionally earthy and muted, reflecting the natural pigments of Roman mosaic work: sandy limestone backgrounds, terracotta robes, olive vegetation, warm umber fauna, and the distinctive slate-teal of the birds.

Source

Mosaic: Orpheus Charming the Animals, Roman, 3rd century AD. Palermo Archaeological Museum. Image via Wikimedia Commons, https://en.wikipedia.org/wiki/Orpheus.

Examples

if (requireNamespace("scales", quietly = TRUE)) {
  scales::show_col(palette_orpheus)
}

Description

Takes an mrpheus_edf object and segments it into standard epochs, performs a channel inventory (classifying signals by type), and flags channels that appear flat or likely bad. This is the standard entry point before any downstream analyses (spectral, event detection, staging).

Usage

prepare_psg(
  edf,
  epoch_s = 30,
  eeg_pattern = "EEG|C3|C4|F3|F4|O1|O2|Fpz|Pz",
  eog_pattern = "EOG|ROC|LOC",
  emg_pattern = "EMG|chin|Chin",
  ecg_pattern = "ECG|EKG",
  resp_pattern = "Thor|Abdo|Flow|SpO2|airflow",
  flat_threshold = 1e-06
)

Arguments

Value

A list of class mrpheus_psg with components:

edf

The original mrpheus_edf object.

epochs

List. Each element is one epoch (30 s by default), itself a named list of channel vectors.

n_epochs

Integer. Total number of complete epochs.

epoch_s

Numeric. Epoch duration in seconds.

channel_map

Data frame. Channel label, detected type (EEG/EOG/EMG/ECG/RESP/OTHER), sample rate, and bad flag.

Examples

## Not run: 
rec  <- read_edf("data/psg_001.edf")
psg  <- prepare_psg(rec)
psg$channel_map

## End(Not run)

Description

Reads a European Data Format (EDF or EDF+) file and returns a structured list containing signal data, channel metadata, and recording header. Wraps edfReader::readEdfHeader() and edfReader::readEdfSignals() with consistent output formatting for the mrpheus pipeline.

Usage

read_edf(path, channels = NULL, only_header = FALSE)

Arguments

Value

A list of class mrpheus_edf with components:

header

Data frame. Recording metadata (patient info, start time, number of signals, etc.).

signals

Named list of numeric vectors, one per channel.

channels

Data frame. Channel-level metadata: label, sample rate, physical min/max, digital min/max, transducer type, prefiltering.

duration_s

Numeric. Total recording duration in seconds.

path

Character. Resolved path to the source file.

Examples

## Not run: 
rec <- read_edf("data/psg_001.edf")
rec <- read_edf("data/psg_001.edf", channels = c("EEG Fpz-Cz", "EOG horizontal"))
rec$channels

## End(Not run)

Description

Stages each 30-second epoch using a pre-trained LightGBM model originally developed for YASA (Vallat & Walker, 2021) and shipped as a cross-language serialised model in inst/models/yasa_staging.txt. Features are computed in R to match the Python feature extraction pipeline exactly; bit-exact parity is validated in the package test suite.

Usage

stage_epochs(
  psg,
  eeg_channel = NULL,
  eog_channel = NULL,
  emg_channel = NULL,
  artefacts = NULL,
  model_path = system.file("models", "yasa_staging.txt", package = "mrpheus")
)

Arguments

Details

Stages returned follow standard AASM nomenclature: W (wake), N1, N2, N3, REM.

Value

A tibble with one row per epoch:

epoch

Integer.

stage

Character. AASM stage: W, N1, N2, N3, REM, or NA (artefact).

prob_W, prob_N1, prob_N2, prob_N3, prob_REM

Numeric. Posterior class probabilities from the LightGBM model.

References

Vallat, R., & Walker, M. P. (2021). An open-source, high-performance tool for automated sleep staging. eLife, 10, e70092. doi:10.7554/eLife.70092

See Also

export_hypnogram()