use crate::error::{BarracudaError, Result};
use crate::special::chi_squared_sf;
#[derive(Debug, Clone)]
pub struct Chi2Decomposed {
pub chi2_total: f64,
pub chi2_per_datum: f64,
pub chi2_per_dof: f64,
pub dof: usize,
pub n_data: usize,
pub contributions: Vec<f64>,
pub residuals: Vec<f64>,
pub pulls: Vec<f64>,
pub p_value: f64,
}
impl Chi2Decomposed {
#[must_use]
pub fn worst_n(&self, n: usize) -> Vec<usize> {
let mut indexed: Vec<(usize, f64)> = self
.contributions
.iter()
.enumerate()
.map(|(i, &c)| (i, c))
.collect();
indexed.sort_by(|a, b| b.1.partial_cmp(&a.1).unwrap_or(std::cmp::Ordering::Equal));
indexed.into_iter().take(n).map(|(i, _)| i).collect()
}
pub fn summary(&self) -> String {
let verdict = if self.p_value > 0.05 {
"ACCEPTABLE"
} else if self.p_value > 0.01 {
"MARGINAL"
} else {
"POOR"
};
format!(
"Chi² Analysis:\n\
─────────────────────────────────\n\
χ²/datum: {:.4}\n\
χ²/dof: {:.4} (ideal ≈ 1.0)\n\
χ² total: {:.4}\n\
dof: {}\n\
p-value: {:.4} → {}\n\
n_data: {}\n\
worst pull: {:.2}σ",
self.chi2_per_datum,
self.chi2_per_dof,
self.chi2_total,
self.dof,
self.p_value,
verdict,
self.n_data,
self.pulls.iter().map(|p| p.abs()).fold(0.0, f64::max)
)
}
}
pub fn chi2_decomposed(
observed: &[f64],
expected: &[f64],
n_params: usize,
) -> Result<Chi2Decomposed> {
let n = observed.len();
if n != expected.len() {
return Err(BarracudaError::InvalidInput {
message: format!(
"observed and expected must have same length: {} vs {}",
n,
expected.len()
),
});
}
if n == 0 {
return Err(BarracudaError::InvalidInput {
message: "observed and expected cannot be empty".to_string(),
});
}
let dof = n.saturating_sub(n_params);
if dof == 0 {
return Err(BarracudaError::InvalidInput {
message: "degrees of freedom must be > 0".to_string(),
});
}
let mut chi2_total = 0.0;
let mut contributions = Vec::with_capacity(n);
let mut residuals = Vec::with_capacity(n);
let mut pulls = Vec::with_capacity(n);
for i in 0..n {
let o = observed[i];
let e = expected[i];
if e <= 0.0 {
return Err(BarracudaError::InvalidInput {
message: format!("expected[{i}] = {e} must be > 0"),
});
}
let residual = o - e;
let sigma = e.sqrt();
let pull = residual / sigma;
let contribution = (residual * residual) / e;
residuals.push(residual);
pulls.push(pull);
contributions.push(contribution);
chi2_total += contribution;
}
let p_value = chi_squared_sf(chi2_total, dof as f64)?;
Ok(Chi2Decomposed {
chi2_total,
chi2_per_datum: chi2_total / n as f64,
chi2_per_dof: chi2_total / dof as f64,
dof,
n_data: n,
contributions,
residuals,
pulls,
p_value,
})
}
pub fn chi2_decomposed_weighted(
observed: &[f64],
expected: &[f64],
uncertainties: &[f64],
n_params: usize,
) -> Result<Chi2Decomposed> {
let n = observed.len();
if n != expected.len() || n != uncertainties.len() {
return Err(BarracudaError::InvalidInput {
message: "observed, expected, and uncertainties must have same length".to_string(),
});
}
if n == 0 {
return Err(BarracudaError::InvalidInput {
message: "arrays cannot be empty".to_string(),
});
}
let dof = n.saturating_sub(n_params);
if dof == 0 {
return Err(BarracudaError::InvalidInput {
message: "degrees of freedom must be > 0".to_string(),
});
}
let mut chi2_total = 0.0;
let mut contributions = Vec::with_capacity(n);
let mut residuals = Vec::with_capacity(n);
let mut pulls = Vec::with_capacity(n);
for i in 0..n {
let o = observed[i];
let e = expected[i];
let sigma = uncertainties[i];
if sigma <= 0.0 {
return Err(BarracudaError::InvalidInput {
message: format!("uncertainties[{i}] = {sigma} must be > 0"),
});
}
let residual = o - e;
let pull = residual / sigma;
let contribution = pull * pull;
residuals.push(residual);
pulls.push(pull);
contributions.push(contribution);
chi2_total += contribution;
}
let p_value = chi_squared_sf(chi2_total, dof as f64)?;
Ok(Chi2Decomposed {
chi2_total,
chi2_per_datum: chi2_total / n as f64,
chi2_per_dof: chi2_total / dof as f64,
dof,
n_data: n,
contributions,
residuals,
pulls,
p_value,
})
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn test_chi2_decomposed_basic() {
let observed = vec![10.0, 20.0, 30.0, 40.0];
let expected = vec![11.0, 19.0, 31.0, 39.0];
let result = chi2_decomposed(&observed, &expected, 0).unwrap();
assert_eq!(result.n_data, 4);
assert_eq!(result.dof, 4);
assert_eq!(result.residuals.len(), 4);
assert_eq!(result.pulls.len(), 4);
assert_eq!(result.contributions.len(), 4);
let sum: f64 = result.contributions.iter().sum();
assert!((result.chi2_total - sum).abs() < 1e-10);
assert!((result.chi2_per_datum - result.chi2_total / 4.0).abs() < 1e-10);
}
#[test]
fn test_chi2_decomposed_perfect_fit() {
let data = vec![10.0, 20.0, 30.0];
let result = chi2_decomposed(&data, &data, 0).unwrap();
assert!((result.chi2_total - 0.0).abs() < 1e-10);
assert!(result.p_value > 0.99); }
#[test]
fn test_chi2_decomposed_with_params() {
let observed = vec![10.0, 20.0, 30.0, 40.0, 50.0];
let expected = vec![11.0, 19.0, 31.0, 39.0, 51.0];
let result = chi2_decomposed(&observed, &expected, 2).unwrap();
assert_eq!(result.dof, 3); }
#[test]
fn test_chi2_worst_n() {
let observed = vec![10.0, 20.0, 100.0, 40.0]; let expected = vec![11.0, 19.0, 30.0, 39.0];
let result = chi2_decomposed(&observed, &expected, 0).unwrap();
let worst = result.worst_n(1);
assert_eq!(worst[0], 2); }
#[test]
fn test_chi2_summary() {
let observed = vec![10.0, 20.0, 30.0];
let expected = vec![11.0, 19.0, 31.0];
let result = chi2_decomposed(&observed, &expected, 0).unwrap();
let summary = result.summary();
assert!(summary.contains("χ²/datum"));
assert!(summary.contains("p-value"));
}
#[test]
fn test_chi2_weighted() {
let observed = vec![10.0, 20.0, 30.0];
let expected = vec![11.0, 19.0, 31.0];
let errors = vec![1.0, 0.5, 2.0];
let result = chi2_decomposed_weighted(&observed, &expected, &errors, 0).unwrap();
assert!((result.pulls[0] - (-1.0 / 1.0)).abs() < 1e-10);
assert!((result.pulls[1] - (1.0 / 0.5)).abs() < 1e-10);
}
#[test]
fn test_chi2_errors() {
assert!(chi2_decomposed(&[1.0, 2.0], &[1.0], 0).is_err());
assert!(chi2_decomposed(&[], &[], 0).is_err());
assert!(chi2_decomposed(&[1.0], &[0.0], 0).is_err());
assert!(chi2_decomposed(&[1.0], &[1.0], 1).is_err());
}
}