Function variation_of_information_score

crates/openquant/src/codependence.rs:340–404

(
    x: &[f64],
    y: &[f64],
    n_bins: Option<usize>,
    normalize: bool,
)

    d_cov_yy /= denom;

    let denom = (d_cov_xx.sqrt() * d_cov_yy.sqrt()).sqrt();
    if denom == 0.0 {
        return Err(CodependenceError::ZeroDistanceVariance);
    }

    Ok(d_cov_xy.sqrt() / denom)
}

/// Histogram bin count that minimises the bias of entropy estimates (Hacine-Gharbi et al.,
/// 2012).
///
/// With `corr_coef = None` uses the univariate (marginal entropy) rule; with the sample
/// correlation `rho` of two series uses the bivariate (joint entropy) rule
/// `round(sqrt(1 + sqrt(1 + 24 N / (1 - rho^2))) / sqrt(2))`. A correlation within `1e-4` of
/// `+-1` falls back to the univariate rule.
///
/// # Errors
///
/// - [`CodependenceError::InputTooShort`] if `num_obs` is zero.
/// - [`CodependenceError::InvalidBins`] if the rule does not yield a positive count (a `NaN`
///   correlation).
///
/// ```
/// use openquant::codependence::get_optimal_number_of_bins;
///
/// # fn main() -> Result<(), openquant::codependence::CodependenceError> {
/// assert_eq!(get_optimal_number_of_bins(1_000, None)?, 15);
/// assert_eq!(get_optimal_number_of_bins(1_000, Some(0.9))?, 13);
/// # Ok(())
/// # }
/// ```
pub fn get_optimal_number_of_bins(
    num_obs: usize,
    corr_coef: Option<f64>,
) -> CodependenceResult<usize> {
    if num_obs == 0 {
        return Err(CodependenceError::InputTooShort);
    }

    let n = num_obs as f64;
    let univariate = || {
        let z = (8.0 + 324.0 * n + 12.0 * (36.0 * n + 729.0 * n * n).sqrt()).cbrt();
        (z / 6.0 + 2.0 / (3.0 * z) + 1.0 / 3.0).round()
    };
    // Arm order keeps a NaN correlation on the bivariate branch, as before.
    // At |corr| = 1 the bivariate formula divides by zero, so both signs fall back.
    let bins = match corr_coef {
        None => univariate(),
        Some(corr) if (corr.abs() - 1.0).abs() <= 1e-4 => univariate(),
        Some(corr) => {
            let inner = (1.0 + 24.0 * n / (1.0 - corr * corr)).sqrt();
            (2.0_f64).powf(-0.5) * (1.0 + inner).sqrt()
        }
    };

    let bins = bins.round() as isize;
    if bins <= 0 {
        return Err(CodependenceError::InvalidBins);