1use core::num::NonZeroU64;
10
11use super::uncertainty::EvidenceReference;
12use crate::epistemic::EpistemicState;
13
14#[path = "association_contract.rs"]
15mod contract;
16pub use contract::*;
17
18pub const MAX_ASSOCIATION_HYPOTHESES: usize = 32;
19pub const MAX_ASSOCIATION_EVIDENCE: usize = 64;
20
21#[derive(Clone, Copy, Debug, PartialEq, Eq)]
22pub enum UnassessedReason {
23 NoEvidence,
24 UnknownDependence,
25 MissingDependenceGroup,
26 ModelOutsideCoverage,
27}
28
29#[derive(Clone, Copy, Debug, PartialEq)]
30pub enum AssociationResult {
31 Unassessed(UnassessedReason),
32 Estimated {
35 probability: f64,
36 },
37}
38
39#[derive(Clone, Copy, Debug, PartialEq)]
42pub struct AssociationEstimate<'a, 'data> {
43 hypothesis: AssociationHypothesis,
44 request: AssociationRequest,
45 model: AssociationModelReference,
46 dependence: DependenceAssumption,
47 evidence: &'a [AssociationEvidence<'data>],
48 evaluation_decision: EvidenceReference,
49 policy_decision: EvidenceReference,
50 result: AssociationResult,
51}
52
53impl<'a, 'data> AssociationEstimate<'a, 'data> {
54 pub const fn hypothesis(self) -> AssociationHypothesis {
55 self.hypothesis
56 }
57 pub const fn request(self) -> AssociationRequest {
58 self.request
59 }
60 pub const fn model(self) -> AssociationModelReference {
61 self.model
62 }
63 pub const fn dependence(self) -> DependenceAssumption {
64 self.dependence
65 }
66 pub const fn evidence(self) -> &'a [AssociationEvidence<'data>] {
67 self.evidence
68 }
69 pub const fn evaluation_decision(self) -> EvidenceReference {
70 self.evaluation_decision
71 }
72 pub const fn policy_decision(self) -> EvidenceReference {
73 self.policy_decision
74 }
75 pub const fn result(self) -> AssociationResult {
76 self.result
77 }
78 pub const fn epistemic_state(self) -> EpistemicState {
79 match self.result {
80 AssociationResult::Unassessed(_) => EpistemicState::Unknown,
81 AssociationResult::Estimated { .. } => EpistemicState::InferredBelief,
82 }
83 }
84}
85
86#[derive(Clone, Copy, Debug, PartialEq, Eq)]
87pub enum AssociationError {
88 CapacityExceeded,
89 OutputTooSmall,
90 DuplicateHypothesis,
91 DuplicateEvidence,
92 InvalidEvidence,
93 PermissionUnknown,
94 PermissionDenied,
95 InvalidModelValue,
96 ImpossibleEvidence,
97 NumericalRange,
98}
99
100pub fn estimate_associations<'a, 'data>(
105 request: AssociationRequest,
106 hypotheses: &[AssociationHypothesis],
107 evidence: &'a [AssociationEvidence<'data>],
108 dependence: DependenceAssumption,
109 model: &impl CalibratedAssociationModel,
110 authority: &mut impl AssociationAuthority,
111 output: &mut [Option<AssociationEstimate<'a, 'data>>],
112) -> Result<usize, AssociationError> {
113 if hypotheses.len() > MAX_ASSOCIATION_HYPOTHESES || evidence.len() > MAX_ASSOCIATION_EVIDENCE {
114 return Err(AssociationError::CapacityExceeded);
115 }
116 if output.len() < hypotheses.len() {
117 return Err(AssociationError::OutputTooSmall);
118 }
119 validate_inputs(hypotheses, evidence)?;
120 let reference = model.reference();
121 let decision = require_permission(authority.authorize(
122 AssociationPhase::Evaluate,
123 &request,
124 hypotheses,
125 evidence,
126 reference,
127 dependence,
128 ))?;
129 let mut planned = [None; MAX_ASSOCIATION_HYPOTHESES];
130 let mut proposed_results =
131 [AssociationResult::Unassessed(UnassessedReason::NoEvidence); MAX_ASSOCIATION_HYPOTHESES];
132 for (index, hypothesis) in hypotheses.iter().enumerate() {
133 let result = estimate_one(&request, hypothesis, evidence, dependence, model)?;
134 proposed_results[index] = result;
135 planned[index] = Some(AssociationEstimate {
136 hypothesis: *hypothesis,
137 request,
138 model: reference,
139 dependence,
140 evidence,
141 evaluation_decision: decision,
142 policy_decision: decision,
143 result,
144 });
145 }
146 let final_decision = require_permission(authority.authorize(
147 AssociationPhase::Publish {
148 results: &proposed_results[..hypotheses.len()],
149 evaluation_decision: decision,
150 },
151 &request,
152 hypotheses,
153 evidence,
154 reference,
155 dependence,
156 ))?;
157 for estimate in planned[..hypotheses.len()].iter_mut().flatten() {
159 estimate.policy_decision = final_decision;
160 }
161 output[..hypotheses.len()].copy_from_slice(&planned[..hypotheses.len()]);
162 Ok(hypotheses.len())
163}
164
165fn require_permission(
166 permission: AssociationPermission,
167) -> Result<EvidenceReference, AssociationError> {
168 match permission {
169 AssociationPermission::Approved { decision } => Ok(decision),
170 AssociationPermission::Unknown => Err(AssociationError::PermissionUnknown),
171 AssociationPermission::Denied => Err(AssociationError::PermissionDenied),
172 }
173}
174
175fn validate_inputs(
176 hypotheses: &[AssociationHypothesis],
177 evidence: &[AssociationEvidence<'_>],
178) -> Result<(), AssociationError> {
179 for (i, hypothesis) in hypotheses.iter().enumerate() {
180 if hypotheses[..i]
181 .iter()
182 .any(|other| other.id == hypothesis.id)
183 {
184 return Err(AssociationError::DuplicateHypothesis);
185 }
186 }
187 for (i, item) in evidence.iter().enumerate() {
188 if evidence[..i]
189 .iter()
190 .any(|other| other.observation_id == item.observation_id)
191 {
192 return Err(AssociationError::DuplicateEvidence);
193 }
194 if matches!(item.value, AssociationValue::Scalar { value, .. } if !value.is_finite()) {
195 return Err(AssociationError::InvalidEvidence);
196 }
197 if let Some(uncertainty) = item.uncertainty {
198 if item.field != Some(uncertainty.field()) {
199 return Err(AssociationError::InvalidEvidence);
200 }
201 }
202 }
203 Ok(())
204}
205
206fn estimate_one(
207 request: &AssociationRequest,
208 hypothesis: &AssociationHypothesis,
209 evidence: &[AssociationEvidence<'_>],
210 dependence: DependenceAssumption,
211 model: &impl CalibratedAssociationModel,
212) -> Result<AssociationResult, AssociationError> {
213 use UnassessedReason::*;
214 let unassessed = |reason| Ok(AssociationResult::Unassessed(reason));
215 if evidence.is_empty() {
216 return unassessed(NoEvidence);
217 }
218 if dependence == DependenceAssumption::Unknown {
219 return unassessed(UnknownDependence);
220 }
221 if matches!(dependence, DependenceAssumption::IndependentGroups { .. })
222 && evidence.iter().any(|item| item.dependence_group.is_none())
223 {
224 return unassessed(MissingDependenceGroup);
225 }
226 let Some(prior) = model.prior_probability(request, hypothesis) else {
227 return unassessed(ModelOutsideCoverage);
228 };
229 if !prior.is_finite() || !(0.0..=1.0).contains(&prior) {
230 return Err(AssociationError::InvalidModelValue);
231 }
232 let mut log_yes = prior.ln();
233 let mut log_no = (-prior).ln_1p();
234 if dependence == DependenceAssumption::Joint {
235 let group = AssociationEvidenceGroup {
236 evidence,
237 group: None,
238 };
239 let Some(likelihoods) = model.joint_log_likelihoods(request, hypothesis, group) else {
240 return unassessed(ModelOutsideCoverage);
241 };
242 add_likelihoods(&mut log_yes, &mut log_no, likelihoods)?;
243 } else {
244 let mut previous: Option<NonZeroU64> = None;
245 for _ in 0..evidence.len() {
246 let next = evidence
247 .iter()
248 .filter_map(|item| item.dependence_group)
249 .filter(|id| previous.is_none_or(|previous| *id > previous))
250 .min();
251 let Some(id) = next else {
252 break;
253 };
254 let group = AssociationEvidenceGroup {
255 evidence,
256 group: Some(id),
257 };
258 let Some(likelihoods) = model.joint_log_likelihoods(request, hypothesis, group) else {
259 return unassessed(ModelOutsideCoverage);
260 };
261 add_likelihoods(&mut log_yes, &mut log_no, likelihoods)?;
262 previous = Some(id);
263 }
264 }
265 if log_yes == f64::NEG_INFINITY && log_no == f64::NEG_INFINITY {
266 return Err(AssociationError::ImpossibleEvidence);
267 }
268 let probability = if log_yes >= log_no {
269 1.0 / (1.0 + (log_no - log_yes).exp())
270 } else {
271 let odds = (log_yes - log_no).exp();
272 odds / (1.0 + odds)
273 };
274 if log_yes.is_finite() && log_no.is_finite() && (probability == 0.0 || probability == 1.0) {
277 return Err(AssociationError::NumericalRange);
278 }
279 Ok(AssociationResult::Estimated { probability })
280}
281
282fn add_likelihoods(
283 yes: &mut f64,
284 no: &mut f64,
285 likelihoods: BinaryLogLikelihoods,
286) -> Result<(), AssociationError> {
287 for value in [
288 likelihoods.given_association,
289 likelihoods.given_no_association,
290 ] {
291 if value.is_nan() || value == f64::INFINITY {
292 return Err(AssociationError::InvalidModelValue);
293 }
294 }
295 *yes = add_log(*yes, likelihoods.given_association)?;
296 *no = add_log(*no, likelihoods.given_no_association)?;
297 Ok(())
298}
299
300fn add_log(left: f64, right: f64) -> Result<f64, AssociationError> {
301 if left == f64::NEG_INFINITY || right == f64::NEG_INFINITY {
302 return Ok(f64::NEG_INFINITY);
303 }
304 let sum = left + right;
305 if !sum.is_finite() {
306 return Err(AssociationError::NumericalRange);
307 }
308 Ok(sum)
309}
310
311#[cfg(test)]
312#[path = "association_tests.rs"]
313mod tests;