15 RSP API Reference

Complete reference for scicloj.ripple.rsp — the public API for respiratory signal processing.

Setup

Shared parameters for the examples below.

(def sampling-rate 1000.0)

(def duration 30.0)

(def expected-samples (long (* sampling-rate duration)))

Synthetic Signal Generation

`synthetic-rsp`

[opts]

Generate a synthetic respiratory signal using a sinusoidal model.

Args:

opts: map with optional keys:
- :sampling-rate (default 1000.0 Hz)
- :duration (default 30.0 seconds)
- :respiratory-rate (default 15.0 breaths per minute)
- :noise (default 0.0 — Gaussian noise amplitude; 0 for clean)
- :seed (default nil — RNG seed for reproducibility)

Returns: double-array of respiratory signal samples

(def rsp-signal (rsp/synthetic-rsp {:sampling-rate sampling-rate
                                    :duration duration
                                    :respiratory-rate 15.0
                                    :seed 42}))

(count rsp-signal)

Cleaning

`rsp-clean`

[signal sampling-rate opts]

Clean a respiratory signal by bandpass filtering.

Methods:

:khodadad2018 (default) — 2nd-order Butterworth bandpass 0.05–3 Hz

Args:

signal: double-array of raw respiratory samples
sampling-rate: sampling rate in Hz
opts: map with optional keys:
- :method (default :khodadad2018)

Returns: cleaned double-array

(def rsp-cleaned (rsp/rsp-clean rsp-signal sampling-rate {:method :khodadad2018}))

(count rsp-cleaned)

Peak and Trough Detection

`rsp-findpeaks`

[signal sampling-rate opts]

Find peaks (exhalation onsets) and troughs (inhalation onsets).

Args:

signal: double-array of cleaned respiratory signal
sampling-rate: sampling rate in Hz
opts: map with optional keys:
- :method (default :khodadad2018)
- :peak-distance (default 1.0 — minimum seconds between peaks)
- :amplitude-min (default 0.3 — outlier threshold)

Returns: map with :peaks and :troughs (both int-arrays)

(def peaks-troughs (rsp/rsp-findpeaks rsp-cleaned sampling-rate {}))

The result contains both :peaks and :troughs.

(and (contains? peaks-troughs :peaks)
     (contains? peaks-troughs :troughs))

true

At 15 breaths/min over 30 s we expect roughly 7–8 peaks.

(def peaks (:peaks peaks-troughs))

(def troughs (:troughs peaks-troughs))

(<= 5 (count peaks) 12)

true

Breath-to-Breath Intervals and Breathing Rate

`peaks->bb-intervals`

[trough-indices sampling-rate]

Convert trough indices to breath-to-breath intervals in milliseconds.

Args:

trough-indices: int-array of trough (inhalation onset) sample indices
sampling-rate: sampling rate in Hz

Returns: double-array of BB intervals in ms

(def bb (rsp/peaks->bb-intervals troughs sampling-rate))

All BB intervals are positive.

(> (dfn/reduce-min bb) 0.0)

true

`bb->breathing-rate`

[bb-intervals-ms]

Convert breath-to-breath intervals (ms) to instantaneous breathing rate (BPM).

Args:

bb-intervals-ms: double-array of BB intervals in milliseconds

Returns: double-array of breathing rate values in BPM

(def br (rsp/bb->breathing-rate bb))

Mean breathing rate should be close to the 15 BPM target.

(let [mean-br (/ (dfn/sum br) (count br))]
  (< (Math/abs (- mean-br 15.0)) 3.0))

true

Respiratory Rate Variability

`rrv-time`

[bb-intervals-ms]

Compute time-domain Respiratory Rate Variability (RRV) indices.

Analogous to HRV time-domain analysis, applied to breath-to-breath intervals.

Args:

bb-intervals-ms: double-array of BB intervals in milliseconds

Returns: map of RRV indices: :mean-bb, :sdbb, :rmssd, :sdsd, :cvbb, :cvsd, :median-bb, :mad-bb, :min-bb, :max-bb, :mean-br, :sd-br, :min-br, :max-br

(def rrv (rsp/rrv-time bb))

(every? #(contains? rrv %)
  [:mean-bb :sdbb :rmssd :sdsd :cvbb :cvsd
   :median-bb :mad-bb :min-bb :max-bb
   :mean-br :sd-br :min-br :max-br])

true

Amplitude, Phase, Symmetry

`rsp-amplitude`

[signal peaks troughs opts]

Compute respiratory amplitude (continuous signal).

Standard: peak value minus preceding trough value. Prepost: peak value minus average of surrounding troughs.

Args:

signal: double-array of cleaned respiratory signal
peaks: int-array of peak indices
troughs: int-array of trough indices
opts: map with optional keys:
- :method (default :standard) — :standard or :prepost

Returns: double-array of amplitude interpolated to signal length

(def amplitude (rsp/rsp-amplitude rsp-cleaned peaks troughs {:method :standard}))

(count amplitude)

`rsp-phase`

[peaks troughs n-samples]

Compute respiratory phase (inspiration/expiration) and completion.

Inspiration (1): trough → peak. Expiration (0): peak → trough.

Args:

peaks: int-array of peak indices
troughs: int-array of trough indices
n-samples: desired output length

Returns: map with: :phase — int-array (1 = inspiration, 0 = expiration) :phase-completion — double-array (0.0 → 1.0 within each phase)

(def phase-result (rsp/rsp-phase peaks troughs expected-samples))

Contains :phase (int-array) and :phase-completion (double-array).

(and (= (count (:phase phase-result)) expected-samples)
     (= (count (:phase-completion phase-result)) expected-samples))

true

`rsp-symmetry`

[signal peaks troughs]

Compute respiratory cycle symmetry (Cole & Voytek, 2019).

Peak-trough: time_to_peak / cycle_duration (trough-to-trough). Values near 0.5 indicate symmetric breathing.

Args:

signal: double-array of cleaned respiratory signal
peaks: int-array of peak indices
troughs: int-array of trough indices

Returns: map with :peak-trough (double-array interpolated to signal length)

(def symmetry (rsp/rsp-symmetry rsp-cleaned peaks troughs))

For a sinusoidal signal, symmetry should be near 0.5.

(let [sym-vals (:peak-trough symmetry)
      mean-sym (/ (dfn/sum sym-vals) (count sym-vals))]
  (< (Math/abs (- mean-sym 0.5)) 0.15))

true

Rate

`rsp-rate`

[troughs sampling-rate n-samples]

Compute instantaneous breathing rate as a continuous signal.

Converts trough-to-trough intervals to BPM and interpolates to signal length using Akima spline.

Args:

troughs: int-array of trough indices
sampling-rate: sampling rate in Hz
n-samples: desired output length

Returns: double-array of breathing rate in BPM

(def rate (rsp/rsp-rate troughs sampling-rate expected-samples))

(count rate)

Mean rate should be close to the 15 BPM target.

(let [mean-rate (/ (dfn/sum rate) (count rate))]
  (< (Math/abs (- mean-rate 15.0)) 3.0))

true

RVT

`rsp-rvt`

[signal peaks troughs sampling-rate]

Compute Respiratory Volume per Time (Power2020 method).

RVT = amplitude / inter-peak-interval. Used for identifying global fMRI confounds of breathing.

Args:

signal: double-array of cleaned respiratory signal
peaks: int-array of peak indices
troughs: int-array of trough indices
sampling-rate: sampling rate in Hz

Returns: double-array of RVT interpolated to signal length

(def rvt (rsp/rsp-rvt rsp-cleaned peaks troughs sampling-rate))

(count rvt)

source: notebooks/ripple_book/rsp_api_reference.clj