2 Quickstart

A minimal introduction to Ripple — just enough code to preprocess a MALDI-TOF spectrum, analyze a cardiovascular signal, and compute breathing rate from a respiratory signal. For the math and intuition behind each algorithm, see:

(ns ripple-book.quickstart
  (:require
   ;; Main MALDI processing API:
   [scicloj.ripple.maldi :as maldi]
   ;; Main cardio processing API
   [scicloj.ripple.cardio :as cardio]
   ;; Main respiratory processing API:
   [scicloj.ripple.rsp :as rsp]
   ;; Table processing (https://scicloj.github.io/tablecloth/):
   [tablecloth.api :as tc]
   ;; Annotating kinds of visualizations (https://scicloj.github.io/kindly-noted/):
   [scicloj.kindly.v4.kind :as kind]))

MALDI-TOF Preprocessing

A MALDI-TOF mass spectrum is a sequence of (mass, intensity) pairs. Ripple preprocesses it in one call: square root transform, smoothing, baseline removal, and normalization.

Create a synthetic spectrum with a baseline and two peaks:

(def masses (vec (range 2000.0 4000.0 1.0)))

(def raw-intensities
  (mapv (fn [m]
          (max 0.0
               (+ (* 500 (Math/exp (- (/ (- m 2000) 400.0))))
                  (* 800.0 (Math/exp (- (/ (Math/pow (- m 2500) 2) 200.0))))
                  (* 400.0 (Math/exp (- (/ (Math/pow (- m 3200) 2) 200.0))))
                  (* 10.0 (Math/sin (* m 0.5))))))
        masses))

(def spectrum (tc/dataset {:mass masses :intensity raw-intensities}))

Preprocess

(def preprocessed
  (maldi/preprocess-spectrum-data
   spectrum
   {:should-sqrt-transform true
    :smooth-window 11
    :smooth-polynomial 2
    :baseline-iterations 25
    :should-tic-normalize true
    :tic-target 1.0}))

(tc/row-count preprocessed)

Detect peaks

(def peaks
  (maldi/detect-peaks (:intensity preprocessed)
                      {:half-window-size 20 :snr 2}))

(count peaks)

Bin for machine learning

(def binned
  (maldi/bin-spectrum preprocessed {:range [2000 4000] :step 3}))

(count binned)

Cardiovascular Signal Processing

Ripple processes ECG and PPG signals: filtering, peak detection, RR interval extraction, and heart rate variability (HRV) analysis.

Generate a synthetic ECG signal using the ECGSYN model (McSharry et al. 2003) – 10 seconds, 500 Hz, 72 BPM:

(def sampling-rate 500.0)

(def ecg-raw
  (cardio/synthetic-ecg {:sampling-rate sampling-rate
                         :duration 10.0
                         :heart-rate 72.0
                         :seed 42}))

Clean, detect peaks, compute HRV

(def ecg-cleaned
  (cardio/ecg-clean ecg-raw sampling-rate
                    {:method :neurokit :powerline 50}))

(def r-peaks
  (cardio/ecg-findpeaks ecg-cleaned sampling-rate
                        {:method :neurokit}))

(count r-peaks)

(def rr-intervals
  (cardio/peaks->rr-intervals r-peaks sampling-rate))

(def hrv (cardio/hrv-time rr-intervals))

(:mean-hr hrv)

72.68361497655847

The HRV result is a map of time-domain indices:

(kind/table
 {:column-names ["Index" "Value"]
  :row-vectors [["Mean NN (ms)" (format "%.1f" (:mean-nn hrv))]
                ["SDNN (ms)" (format "%.2f" (:sdnn hrv))]
                ["RMSSD (ms)" (format "%.2f" (:rmssd hrv))]
                ["Mean HR (BPM)" (format "%.1f" (:mean-hr hrv))]]})

Index	Value
Mean NN (ms)	826.5
SDNN (ms)	28.92
RMSSD (ms)	34.38
Mean HR (BPM)	72.7

Respiratory Signal Processing

Ripple processes respiratory signals: filtering, peak/trough detection, breathing rate, and respiratory rate variability (RRV) analysis.

Generate a synthetic respiratory signal — 30 seconds, 100 Hz, 15 breaths/min:

(def rsp-rate 100.0)

(def rsp-raw
  (rsp/synthetic-rsp {:sampling-rate rsp-rate
                      :duration 30.0
                      :respiratory-rate 15.0
                      :noise 0.01
                      :seed 42}))

Clean, detect peaks, compute breathing rate

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

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

(count (:troughs rsp-peaks))

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

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

(:mean-br rrv)

14.956982989293325

The RRV result is a map of time-domain indices:

(kind/table
 {:column-names ["Index" "Value"]
  :row-vectors [["Mean BB (ms)" (format "%.1f" (:mean-bb rrv))]
                ["SDBB (ms)" (format "%.2f" (:sdbb rrv))]
                ["RMSSD (ms)" (format "%.2f" (:rmssd rrv))]
                ["Mean BR (BPM)" (format "%.1f" (:mean-br rrv))]]})

Index	Value
Mean BB (ms)	4011.7
SDBB (ms)	27.87
RMSSD (ms)	41.23
Mean BR (BPM)	15.0

source: notebooks/ripple_book/quickstart.clj