Skip to main content

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}