metrics

Reconstruction quality metrics for signal compression evaluation.

PRDclassPercent RMS difference metric with optional energy normalization.
TruePRDclassNormalized PRD metric (convenience alias).
compute_signal_metricsfunctionCompute scalar reconstruction metrics on two aligned signals.
compute_ppg_physiokit_metricsfunctionCompute HR/HRV metrics for one PPG signal using physiokit.
summarize_ppg_peak_alignmentfunctionCompare PPG pulse peak timing between paired original/reconstructed signals.
summarize_physiokit_alignmentfunctionCompare physiokit HR/HRV metrics between original and reconstructed signals.
compute_ecg_hr_hrvfunctionDetect R-peaks and compute HR/HRV from a single ECG signal.
summarize_ecg_alignmentfunctionCompare ECG HR/HRV/peak-timing between paired original and reconstructed signals.

PRD(normalized: bool = True, name: str = 'prd', **kwargs={})

Percent RMS difference metric with optional energy normalization.

normalized = normalized

update_state(y_true, y_pred, sample_weight=None)

result()

reset_state()

TruePRD(name: str = 'prd', **kwargs={})

Normalized PRD metric (convenience alias).

compute_signal_metrics(
    original: np.ndarray,
    reconstructed: np.ndarray,
    *,
    noise_power: float | None = None,
) -> dict[str, float]

Compute scalar reconstruction metrics on two aligned signals.

Parameters

Parameters of compute_signal_metrics
Name	Type	Default	Description
`original`	`np.ndarray`	Required	Ground-truth signal (any shape; flattened).
`reconstructed`	`np.ndarray`	Required	Reconstructed signal (same total size).
`noise_power`	`float \| None`	None	Optional estimate of the noise contribution to the ground-truth power, in the same scale as ``mean(original*2)``. When provided, ``prdn_noise_percent`` is added to the result — this is PRD normalized by the clean* signal power ``max(mean(orig^2) - noise_power, eps)`` rather than the raw signal power. It removes the unfair penalty applied to codecs that correctly remove noise from a noisy ground-truth.

compute_ppg_physiokit_metrics(
    signal: np.ndarray,
    *,
    sample_rate: int,
    low_hz: float,
    high_hz: float,
    order: int,
    min_peaks: int,
) -> dict[str, float] | None

Compute HR/HRV metrics for one PPG signal using physiokit.

summarize_ppg_peak_alignment(
    originals: np.ndarray,
    reconstructions: np.ndarray,
    *,
    sample_rate: int,
    low_hz: float = 0.5,
    high_hz: float = 8.0,
    order: int = 3,
    min_peaks: int = 5,
    timing_tolerance_ms: float = 125.0,
) -> tuple[dict[str, float] | None, list[dict[str, Any] | None]]

Compare PPG pulse peak timing between paired original/reconstructed signals.

Peaks are detected through the same physiokit PPG path used for HR/HRV, then matched one-to-one within timing_tolerance_ms. This reports pulse preservation directly: precision catches extra invented pulses, recall catches missed pulses, and timing/IBI errors catch peak shifts that can degrade HRV even when waveform PRD is low.

summarize_physiokit_alignment(
    originals: np.ndarray,
    reconstructions: np.ndarray,
    *,
    sample_rate: int,
    low_hz: float,
    high_hz: float,
    order: int,
    min_peaks: int,
) -> tuple[dict[str, float] | None, list[dict[str, Any] | None]]

Compare physiokit HR/HRV metrics between original and reconstructed signals.

compute_ecg_hr_hrv(
    signal: np.ndarray,
    *,
    sample_rate: int,
    min_peaks_for_hr: int = 2,
    min_peaks_for_hrv: int = 3,
) -> dict[str, Any] | None

Detect R-peaks and compute HR/HRV from a single ECG signal.

Returns None when there are too few peaks to compute even HR. Otherwise returns num_peaks, hr_bpm, mean_rr_ms, peak_locations (sample indices), and — when at least min_peaks_for_hrv peaks are found — sdnn_ms and rmssd_ms.

summarize_ecg_alignment(
    originals: np.ndarray,
    reconstructions: np.ndarray,
    *,
    sample_rate: int,
    min_peaks_for_hr: int = 2,
    min_peaks_for_hrv: int = 3,
    timing_tolerance_ms: float = 10.0,
) -> tuple[dict[str, float] | None, list[dict[str, Any] | None]]

Compare ECG HR/HRV/peak-timing between paired original and reconstructed signals.

Parameters

Parameters of summarize_ecg_alignment
Name	Type	Default	Description
`originals`	`np.ndarray`	Required	Iterable/array of ground-truth signals.
`reconstructions`	`np.ndarray`	Required	Iterable/array of reconstructed signals (same N).
`sample_rate`	`int`	Required	Hz.
`min_peaks_for_hr`	`int`	2	Minimum peaks required to report HR.
`min_peaks_for_hrv`	`int`	3	Minimum peaks required to report HRV (SDNN/RMSSD).
`timing_tolerance_ms`	`float`	10.0	Threshold for "peak timing within tolerance".

Returns

Returns of summarize_ecg_alignment
Type	Description
`dict[str, float] \| None`	``(summary, per_sample)``. ``summary`` is ``None`` if no pair was
`list[dict[str, Any] \| None]`	valid. ``per_sample`` is aligned with the inputs and contains
`tuple[dict[str, float] \| None, list[dict[str, Any] \| None]]`	``None`` for pairs where either side lacked peaks.