hyprstream_calibration/joint.rs
1//! Cross-question / joint coverage.
2//!
3//! Conformal coverage guarantees are **marginal**: a 90% prediction set per question does
4//! not imply 90% of batch rows have every question covered. A decision batch answers many
5//! questions against the same state, and downstream consumers (confidence-filtered joins,
6//! SQL composition) compose the answers — so the joint number is reported separately from
7//! the marginals, alongside the product-of-marginals reference that independence would
8//! imply. This module owns that report; it takes per-row coverage indicators produced by
9//! any conformal method.
10
11use serde::{Deserialize, Serialize};
12
13use crate::error::MetricError;
14
15/// Joint-coverage report for a batch of multi-question rows.
16#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
17pub struct JointCoverage {
18 /// Number of rows.
19 pub n: usize,
20 /// Number of questions per row.
21 pub n_questions: usize,
22 /// Per-question marginal coverage.
23 pub marginals: Vec<f64>,
24 /// Fraction of rows in which **every** question's prediction set covered the true
25 /// label.
26 pub joint: f64,
27 /// Product of the marginals — the joint coverage that question independence would
28 /// imply. The gap `joint − independence_reference` measures error correlation
29 /// across questions on the same state.
30 pub independence_reference: f64,
31}
32
33/// Compute joint and marginal coverage from a row-major coverage matrix:
34/// `covered[i][q]` is true when row `i`'s prediction set for question `q` covered the
35/// realized label.
36///
37/// # Errors
38/// [`MetricError::EmptyInput`] on zero rows or zero questions;
39/// [`MetricError::LengthMismatch`] on a ragged matrix.
40pub fn joint_coverage(covered: &[Vec<bool>]) -> Result<JointCoverage, MetricError> {
41 if covered.is_empty() {
42 return Err(MetricError::EmptyInput("joint coverage"));
43 }
44 let n_questions = covered[0].len();
45 if n_questions == 0 {
46 return Err(MetricError::EmptyInput("joint coverage (questions)"));
47 }
48 for row in covered.iter() {
49 if row.len() != n_questions {
50 return Err(MetricError::LengthMismatch {
51 left_name: "covered[0]",
52 left: n_questions,
53 right_name: "covered[i]",
54 right: row.len(),
55 });
56 }
57 }
58 #[allow(clippy::cast_precision_loss)]
59 let n = covered.len() as f64;
60 let mut hits = vec![0usize; n_questions];
61 let mut joint_hits = 0usize;
62 for row in covered {
63 let mut all = true;
64 for (q, &c) in row.iter().enumerate() {
65 hits[q] += usize::from(c);
66 all &= c;
67 }
68 joint_hits += usize::from(all);
69 }
70 #[allow(clippy::cast_precision_loss)]
71 let marginals: Vec<f64> = hits.iter().map(|&h| h as f64 / n).collect();
72 let independence_reference = marginals.iter().product();
73 #[allow(clippy::cast_precision_loss)]
74 Ok(JointCoverage {
75 n: covered.len(),
76 n_questions,
77 marginals,
78 joint: joint_hits as f64 / n,
79 independence_reference,
80 })
81}