Skip to main content

qualia_core_db/medical/reconstruction/
inference.rs

1//! Source-bound quantitative & non-visual inference over calibrated medical values,
2//! 1D/ND spectroscopy bins, and calibrated time-series waveforms with analytical
3//! error propagation and strict BLAKE3 provenance stamping.
4use super::spectral_fft::fft_1d;
5use crate::medical::dicom_frames::{LinearTransform, ValueUnits};
6use crate::medical::dicom_geometry::PatientImagePlane;
7use crate::solvers::transforms::fourier::Cplx;
8
9#[derive(Debug, Clone, Copy, PartialEq, Eq)]
10pub enum InferenceError {
11    UnspecifiedUnits,
12    SourceIdentityMismatch,
13    FrameNumberMismatch,
14    EmptySeries,
15    DimensionMismatch,
16    NonFiniteValue,
17    InvalidCalibration(&'static str),
18    MissingSpatialFrameOfReference,
19    OutOfStoredRange,
20}
21
22impl std::fmt::Display for InferenceError {
23    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
24        write!(f, "quantitative inference error: {self:?}")
25    }
26}
27impl std::error::Error for InferenceError {}
28
29#[derive(Clone, Copy, Debug)]
30pub struct UncertaintyBudget {
31    pub stored_measurement_std: f64,
32    pub slope_std: f64,
33    pub intercept_std: f64,
34    pub epistemic_std: f64,
35    pub aleatoric_std: f64,
36}
37
38impl Default for UncertaintyBudget {
39    fn default() -> Self {
40        Self {
41            stored_measurement_std: 0.0,
42            slope_std: 0.0,
43            intercept_std: 0.0,
44            epistemic_std: 0.0,
45            aleatoric_std: 0.0,
46        }
47    }
48}
49
50#[derive(Clone, Copy, Debug)]
51pub enum NonVisualDomain<'a> {
52    ScalarSeries,
53    Spectroscopy { axis_values: &'a [f64], axis_units: &'a str },
54    Waveform { sample_rate_hz: f64 },
55}
56
57#[derive(Clone, Debug)]
58pub struct InferenceProvenance {
59    pub source_blake3: [u8; 32],
60    pub derivation_blake3: [u8; 32],
61    pub frame_number: u32,
62    pub algorithm_id: &'static str,
63    pub units_description: String,
64    pub slope: f64,
65    pub intercept: f64,
66    pub sample_count: usize,
67    pub mean_calibrated: f64,
68    pub std_calibrated: f64,
69    pub min_calibrated: f64,
70    pub max_calibrated: f64,
71    pub propagated_uncertainty_rms: f64,
72    pub spectral_centroid: Option<f64>,
73    pub integral_trapezoid: Option<f64>,
74    pub dominant_frequency_hz: Option<f64>,
75}
76
77fn validate_units<'a>(units: ValueUnits<'a>) -> Result<String, InferenceError> {
78    match units {
79        ValueUnits::Unspecified => Err(InferenceError::UnspecifiedUnits),
80        ValueUnits::RescaleType(s) => {
81            let t = s.trim();
82            if t.is_empty() || t.eq_ignore_ascii_case("US") {
83                Err(InferenceError::UnspecifiedUnits)
84            } else {
85                Ok(t.to_string())
86            }
87        }
88        ValueUnits::Code { scheme, value, meaning } => {
89            if scheme.trim().is_empty() || value.trim().is_empty() {
90                Err(InferenceError::UnspecifiedUnits)
91            } else {
92                Ok(match meaning {
93                    Some(m) => format!("{scheme}:{value} ({m})"),
94                    None => format!("{scheme}:{value}"),
95                })
96            }
97        }
98    }
99}
100
101fn validate_budget(b: &UncertaintyBudget) -> Result<(), InferenceError> {
102    let fields = [
103        b.stored_measurement_std,
104        b.slope_std,
105        b.intercept_std,
106        b.epistemic_std,
107        b.aleatoric_std,
108    ];
109    if fields.iter().any(|&v| !v.is_finite() || v < 0.0) {
110        return Err(InferenceError::InvalidCalibration("uncertainty components must be finite non-negative"));
111    }
112    Ok(())
113}
114
115/// Calibrate raw stored DICOM values via source-bound `LinearTransform<'a>`, propagate
116/// measurement + calibration + model uncertainty into `calibrated_out` / `uncertainty_out`,
117/// and compute scalar / spectroscopy / waveform summaries with BLAKE3 provenance.
118pub fn calibrate_and_infer_into<'a>(
119    stored_samples: &[f64],
120    transform: &LinearTransform<'a>,
121    expected_source_blake3: [u8; 32],
122    expected_frame_number: u32,
123    domain: NonVisualDomain<'a>,
124    optional_plane: Option<&PatientImagePlane<'a>>,
125    uncertainty: UncertaintyBudget,
126    algorithm_id: &'static str,
127    calibrated_out: &mut [f64],
128    uncertainty_out: &mut [f64],
129) -> Result<InferenceProvenance, InferenceError> {
130    if stored_samples.is_empty() {
131        return Err(InferenceError::EmptySeries);
132    }
133    if calibrated_out.len() < stored_samples.len() || uncertainty_out.len() < stored_samples.len() {
134        return Err(InferenceError::DimensionMismatch);
135    }
136    if transform.source_blake3() != expected_source_blake3 {
137        return Err(InferenceError::SourceIdentityMismatch);
138    }
139    if transform.frame_number() != expected_frame_number {
140        return Err(InferenceError::FrameNumberMismatch);
141    }
142    if !transform.slope().is_finite() || transform.slope() == 0.0 || !transform.intercept().is_finite() {
143        return Err(InferenceError::InvalidCalibration("zero or non-finite slope/intercept"));
144    }
145    if let Some(plane) = optional_plane {
146        if plane.frame_of_reference_uid().is_none() {
147            return Err(InferenceError::MissingSpatialFrameOfReference);
148        }
149    }
150    validate_budget(&uncertainty)?;
151    let units_description = validate_units(transform.units())?;
152
153    match domain {
154        NonVisualDomain::ScalarSeries => {}
155        NonVisualDomain::Spectroscopy { axis_values, axis_units } => {
156            if axis_values.len() != stored_samples.len()
157                || axis_units.trim().is_empty()
158                || axis_values.iter().any(|v| !v.is_finite())
159            {
160                return Err(InferenceError::DimensionMismatch);
161            }
162        }
163        NonVisualDomain::Waveform { sample_rate_hz } => {
164            if !sample_rate_hz.is_finite() || sample_rate_hz <= 0.0 {
165                return Err(InferenceError::InvalidCalibration("waveform sample_rate_hz must be positive finite"));
166            }
167        }
168    }
169
170    let n = stored_samples.len();
171    let mut staged_val = Vec::with_capacity(n);
172    let mut staged_unc = Vec::with_capacity(n);
173    let slope = transform.slope();
174
175    for &x in stored_samples {
176        if !x.is_finite() {
177            return Err(InferenceError::NonFiniteValue);
178        }
179        let y = transform.apply(x).map_err(|_| InferenceError::OutOfStoredRange)?;
180        let var = (slope * uncertainty.stored_measurement_std).powi(2)
181            + (x * uncertainty.slope_std).powi(2)
182            + uncertainty.intercept_std.powi(2)
183            + uncertainty.epistemic_std.powi(2)
184            + uncertainty.aleatoric_std.powi(2);
185        staged_val.push(y);
186        staged_unc.push(var.sqrt());
187    }
188
189    let mean_calibrated = staged_val.iter().sum::<f64>() / n as f64;
190    let var_cal = staged_val.iter().map(|v| (v - mean_calibrated).powi(2)).sum::<f64>() / n as f64;
191    let std_calibrated = var_cal.sqrt();
192    let min_calibrated = staged_val.iter().copied().fold(f64::INFINITY, f64::min);
193    let max_calibrated = staged_val.iter().copied().fold(f64::NEG_INFINITY, f64::max);
194    let rms_unc = (staged_unc.iter().map(|u| u * u).sum::<f64>() / n as f64).sqrt();
195
196    let (spectral_centroid, integral_trapezoid, dominant_frequency_hz) = match domain {
197        NonVisualDomain::ScalarSeries => (None, None, None),
198        NonVisualDomain::Spectroscopy { axis_values, .. } => {
199            let mut mass = 0.0;
200            let mut w_axis = 0.0;
201            let mut trap = 0.0;
202            for i in 0..n {
203                let w = staged_val[i].max(0.0);
204                mass += w;
205                w_axis += w * axis_values[i];
206                if i + 1 < n {
207                    let dx = (axis_values[i + 1] - axis_values[i]).abs();
208                    trap += 0.5 * (staged_val[i] + staged_val[i + 1]) * dx;
209                }
210            }
211            let centroid = if mass > 1e-18 { Some(w_axis / mass) } else { None };
212            (centroid, Some(trap), None)
213        }
214        NonVisualDomain::Waveform { sample_rate_hz } => {
215            let dt = 1.0 / sample_rate_hz;
216            let mut trap = 0.0;
217            for i in 0..n.saturating_sub(1) {
218                trap += 0.5 * (staged_val[i] + staged_val[i + 1]) * dt;
219            }
220            let cx: Vec<Cplx> = staged_val.iter().map(|&v| (v - mean_calibrated, 0.0)).collect();
221            let dom_hz = if n >= 2 {
222                let spec = fft_1d(&cx).map_err(|_| InferenceError::NonFiniteValue)?;
223                let mut best_k = 1usize;
224                let mut best_p = -1.0;
225                for (k, &(re, im)) in spec.iter().enumerate().take(n / 2 + 1).skip(1) {
226                    let p = re * re + im * im;
227                    if p > best_p {
228                        best_p = p;
229                        best_k = k;
230                    }
231                }
232                if best_p > 1e-18 {
233                    Some(best_k as f64 * sample_rate_hz / n as f64)
234                } else {
235                    Some(0.0)
236                }
237            } else {
238                None
239            };
240            (None, Some(trap), dom_hz)
241        }
242    };
243
244    let mut hasher = blake3::Hasher::new();
245    hasher.update(&expected_source_blake3);
246    hasher.update(algorithm_id.as_bytes());
247    hasher.update(units_description.as_bytes());
248    hasher.update(&transform.slope().to_le_bytes());
249    hasher.update(&transform.intercept().to_le_bytes());
250    for (&v, &u) in staged_val.iter().zip(staged_unc.iter()) {
251        hasher.update(&v.to_le_bytes());
252        hasher.update(&u.to_le_bytes());
253    }
254    calibrated_out[..n].copy_from_slice(&staged_val);
255    uncertainty_out[..n].copy_from_slice(&staged_unc);
256
257    Ok(InferenceProvenance {
258        source_blake3: expected_source_blake3,
259        derivation_blake3: *hasher.finalize().as_bytes(),
260        frame_number: expected_frame_number,
261        algorithm_id,
262        units_description,
263        slope,
264        intercept: transform.intercept(),
265        sample_count: n,
266        mean_calibrated,
267        std_calibrated,
268        min_calibrated,
269        max_calibrated,
270        propagated_uncertainty_rms: rms_unc,
271        spectral_centroid,
272        integral_trapezoid,
273        dominant_frequency_hz,
274    })
275}