qualia_core_db/medical/reconstruction/
inference.rs1use 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
115pub 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}