@ebowwa/quant-rust 0.1.0

package/src/prediction/calibration.rs

@@ -0,0 +1,317 @@
+//! # Forecast Calibration and Scoring
+//!
+//! Tools for evaluating probability forecasts.
+
+/// A single prediction with outcome
+#[derive(Debug, Clone, Copy)]
+pub struct Prediction {
+    /// Predicted probability (0-1)
+    pub predicted: f64,
+    /// Actual outcome (0 or 1)
+    pub actual: f64,
+}
+
+impl Prediction {
+    /// Create a new prediction
+    pub fn new(predicted: f64, actual: bool) -> Self {
+        Self {
+            predicted,
+            actual: if actual { 1.0 } else { 0.0 },
+        }
+    }
+}
+
+/// A calibration bucket for a range of predicted probabilities
+#[derive(Debug, Clone)]
+pub struct CalibrationBucket {
+    /// Range of predicted probabilities (min, max)
+    pub predicted_range: (f64, f64),
+    /// Number of predictions in this bucket
+    pub count: usize,
+    /// Average predicted probability
+    pub avg_predicted: f64,
+    /// Average actual frequency (observed)
+    pub avg_actual: f64,
+}
+
+/// Result of calibration analysis
+#[derive(Debug, Clone)]
+pub struct CalibrationResult {
+    /// Calibration buckets
+    pub buckets: Vec<CalibrationBucket>,
+    /// Brier score (lower is better, 0 = perfect)
+    pub brier_score: f64,
+    /// Log loss (lower is better)
+    pub log_loss: f64,
+    /// Mean absolute calibration error
+    pub calibration_error: f64,
+}
+
+const EPSILON: f64 = 1e-15;
+
+/// Calculate Brier score for probability forecasts.
+///
+/// Brier score = mean((predicted - actual)^2)
+///
+/// Lower is better: 0 = perfect, 0.25 = random for binary
+///
+/// # Arguments
+/// * `predictions` - Slice of predictions
+///
+/// # Returns
+/// Brier score
+///
+/// # Example
+/// ```
+/// use quant_rust::prediction::calibration::{brier_score, Prediction};
+/// let predictions = vec![
+///     Prediction::new(0.8, true),
+///     Prediction::new(0.3, false),
+/// ];
+/// let score = brier_score(&predictions);
+/// assert!(score < 0.25); // Better than random
+/// ```
+pub fn brier_score(predictions: &[Prediction]) -> f64 {
+    if predictions.is_empty() {
+        return 0.0;
+    }
+
+    let sum_squared_errors: f64 = predictions
+        .iter()
+        .map(|p| (p.predicted - p.actual).powi(2))
+        .sum();
+
+    sum_squared_errors / predictions.len() as f64
+}
+
+/// Calculate log loss for probability forecasts.
+///
+/// Log loss = -mean(actual * log(pred) + (1-actual) * log(1-pred))
+///
+/// Lower is better. Penalizes confident wrong predictions heavily.
+///
+/// # Arguments
+/// * `predictions` - Slice of predictions
+///
+/// # Returns
+/// Log loss
+///
+/// # Example
+/// ```
+/// use quant_rust::prediction::calibration::{log_loss, Prediction};
+/// let predictions = vec![
+///     Prediction::new(0.9, true),
+///     Prediction::new(0.1, false),
+/// ];
+/// let loss = log_loss(&predictions);
+/// assert!(loss < 0.5); // Good predictions
+/// ```
+pub fn log_loss(predictions: &[Prediction]) -> f64 {
+    if predictions.is_empty() {
+        return 0.0;
+    }
+
+    let sum_log_loss: f64 = predictions
+        .iter()
+        .map(|p| {
+            // Clamp to prevent log(0)
+            let pred = p.predicted.clamp(EPSILON, 1.0 - EPSILON);
+            let actual = p.actual;
+            -(actual * pred.ln() + (1.0 - actual) * (1.0 - pred).ln())
+        })
+        .sum();
+
+    sum_log_loss / predictions.len() as f64
+}
+
+/// Calculate calibration metrics.
+///
+/// Groups predictions into buckets and compares predicted vs observed frequencies.
+///
+/// # Arguments
+/// * `predictions` - Slice of predictions
+///
+/// # Returns
+/// CalibrationResult with buckets and scores
+///
+/// # Example
+/// ```
+/// use quant_rust::prediction::calibration::{calculate_calibration, Prediction};
+/// let predictions = vec![
+///     Prediction::new(0.1, false),
+///     Prediction::new(0.1, false),
+///     Prediction::new(0.1, true), // 33% actual in 10% bucket
+///     Prediction::new(0.9, true),
+///     Prediction::new(0.9, true),
+///     Prediction::new(0.9, false), // 67% actual in 90% bucket
+/// ];
+/// let result = calculate_calibration(&predictions);
+/// assert!(result.buckets.len() > 0);
+/// ```
+pub fn calculate_calibration(predictions: &[Prediction]) -> CalibrationResult {
+    const NUM_BUCKETS: usize = 10;
+
+    // Group predictions into buckets
+    let mut buckets: Vec<(Vec<f64>, Vec<f64>)> = vec![(vec![], vec![]); NUM_BUCKETS];
+
+    for p in predictions {
+        // Clamp predicted to [0, 1) to ensure valid bucket index
+        let clamped = p.predicted.clamp(0.0, 0.9999999);
+        let bucket_index = (clamped * NUM_BUCKETS as f64) as usize;
+        let bucket_index = bucket_index.min(NUM_BUCKETS - 1);
+        buckets[bucket_index].0.push(p.predicted);
+        buckets[bucket_index].1.push(p.actual);
+    }
+
+    // Build calibration buckets
+    let mut calibration_buckets: Vec<CalibrationBucket> = Vec::new();
+
+    for i in 0..NUM_BUCKETS {
+        let (predicted, actual) = &buckets[i];
+        if !predicted.is_empty() {
+            let avg_predicted: f64 = predicted.iter().sum::<f64>() / predicted.len() as f64;
+            let avg_actual: f64 = actual.iter().sum::<f64>() / actual.len() as f64;
+
+            calibration_buckets.push(CalibrationBucket {
+                predicted_range: (
+                    i as f64 / NUM_BUCKETS as f64,
+                    (i + 1) as f64 / NUM_BUCKETS as f64,
+                ),
+                count: predicted.len(),
+                avg_predicted,
+                avg_actual,
+            });
+        }
+    }
+
+    // Calculate calibration error = mean |predicted - observed|
+    let calibration_error = if calibration_buckets.is_empty() {
+        0.0
+    } else {
+        let sum: f64 = calibration_buckets
+            .iter()
+            .map(|b| (b.avg_predicted - b.avg_actual).abs())
+            .sum();
+        sum / calibration_buckets.len() as f64
+    };
+
+    CalibrationResult {
+        buckets: calibration_buckets,
+        brier_score: brier_score(predictions),
+        log_loss: log_loss(predictions),
+        calibration_error,
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn test_brier_score_perfect() {
+        let predictions = vec![
+            Prediction::new(1.0, true),
+            Prediction::new(0.0, false),
+            Prediction::new(1.0, true),
+        ];
+        assert!((brier_score(&predictions) - 0.0).abs() < 1e-10);
+    }
+
+    #[test]
+    fn test_brier_score_random() {
+        // Random predictions should give ~0.25
+        let predictions = vec![
+            Prediction::new(0.5, true),
+            Prediction::new(0.5, false),
+            Prediction::new(0.5, true),
+            Prediction::new(0.5, false),
+        ];
+        assert!((brier_score(&predictions) - 0.25).abs() < 1e-10);
+    }
+
+    #[test]
+    fn test_brier_score_worst() {
+        // Confident and wrong
+        let predictions = vec![
+            Prediction::new(1.0, false),
+            Prediction::new(0.0, true),
+        ];
+        assert!((brier_score(&predictions) - 1.0).abs() < 1e-10);
+    }
+
+    #[test]
+    fn test_brier_score_empty() {
+        let predictions: Vec<Prediction> = vec![];
+        assert_eq!(brier_score(&predictions), 0.0);
+    }
+
+    #[test]
+    fn test_log_loss_perfect() {
+        let predictions = vec![
+            Prediction::new(0.999, true),
+            Prediction::new(0.001, false),
+        ];
+        let loss = log_loss(&predictions);
+        assert!(loss < 0.01);
+    }
+
+    #[test]
+    fn test_log_loss_worst() {
+        // Confident and wrong
+        let predictions = vec![
+            Prediction::new(0.001, true),
+            Prediction::new(0.999, false),
+        ];
+        let loss = log_loss(&predictions);
+        assert!(loss > 5.0); // Very high loss
+    }
+
+    #[test]
+    fn test_log_loss_empty() {
+        let predictions: Vec<Prediction> = vec![];
+        assert_eq!(log_loss(&predictions), 0.0);
+    }
+
+    #[test]
+    fn test_calibrate_buckets() {
+        let predictions = vec![
+            Prediction::new(0.05, false),
+            Prediction::new(0.05, false),
+            Prediction::new(0.05, true),
+            Prediction::new(0.95, true),
+            Prediction::new(0.95, true),
+            Prediction::new(0.95, false),
+        ];
+        let result = calculate_calibration(&predictions);
+        assert!(result.buckets.len() >= 2);
+
+        // Find 0-10% bucket
+        let low_bucket = result.buckets.iter().find(|b| b.predicted_range.0 == 0.0);
+        assert!(low_bucket.is_some());
+        let low = low_bucket.unwrap();
+        assert_eq!(low.count, 3);
+        assert!((low.avg_actual - 0.333).abs() < 0.01);
+
+        // Find 90-100% bucket
+        let high_bucket = result.buckets.iter().find(|b| b.predicted_range.0 == 0.9);
+        assert!(high_bucket.is_some());
+        let high = high_bucket.unwrap();
+        assert_eq!(high.count, 3);
+        assert!((high.avg_actual - 0.667).abs() < 0.01);
+    }
+
+    #[test]
+    fn test_calibration_error() {
+        // Perfectly calibrated
+        let predictions: Vec<Prediction> = (0..100)
+            .map(|i| {
+                let prob = (i as f64) / 100.0;
+                // Simulate outcomes matching predictions
+                Prediction::new(prob, prob > 0.5)
+            })
+            .collect();
+        let result = calculate_calibration(&predictions);
+        // With deterministic outcomes, calibration should be reasonably good
+        assert!(result.calibration_error < 0.5);
+    }
+}

package/src/prediction/kelly.rs

@@ -0,0 +1,232 @@
+//! # Kelly Criterion for Prediction Markets
+//!
+//! Optimal position sizing for binary outcome bets.
+
+/// Result of Kelly criterion calculation
+#[derive(Debug, Clone, Copy)]
+pub struct KellyResult {
+    /// Optimal fraction of bankroll (0-1)
+    pub kelly_fraction: f64,
+    /// Conservative half-Kelly fraction
+    pub half_kelly: f64,
+    /// Very conservative quarter-Kelly fraction
+    pub quarter_kelly: f64,
+    /// Full bet size in currency units
+    pub full_bet_size: f64,
+    /// Half-Kelly bet size
+    pub half_bet_size: f64,
+    /// Quarter-Kelly bet size
+    pub quarter_bet_size: f64,
+    /// Your estimated edge (your_prob - market_price)
+    pub edge: f64,
+    /// Market odds (win_amount / loss_amount)
+    pub odds: f64,
+}
+
+/// A betting opportunity for multi-bet Kelly
+#[derive(Debug, Clone, Copy)]
+pub struct BetOpportunity {
+    /// Your estimated probability of winning
+    pub your_prob: f64,
+    /// Current market price
+    pub market_price: f64,
+}
+
+/// Calculate Kelly criterion for a binary prediction market bet.
+///
+/// # Arguments
+/// * `your_prob` - Your estimated probability of winning (0-1)
+/// * `market_price` - Current market price to buy shares (0-1)
+/// * `bankroll` - Your total bankroll in currency units
+///
+/// # Returns
+/// KellyResult with optimal sizing at various Kelly fractions
+///
+/// # Example
+/// ```
+/// use quant_rust::prediction::kelly::kelly_criterion;
+/// let result = kelly_criterion(0.6, 0.5, 1000.0);
+/// assert!(result.kelly_fraction > 0.0);
+/// assert!(result.edge > 0.0);
+/// ```
+pub fn kelly_criterion(your_prob: f64, market_price: f64, bankroll: f64) -> KellyResult {
+    // For prediction markets:
+    // - Win: get $1 per share (profit = $1 - price)
+    // - Lose: lose the entire purchase price
+    let win_amount = 1.0 - market_price; // Profit if wins ($1 - purchase price)
+    let loss_amount = market_price; // Loss if loses (entire purchase price)
+
+    // b = win_amount / loss_amount (odds received)
+    let b = if loss_amount > 0.0 {
+        win_amount / loss_amount
+    } else {
+        0.0
+    };
+
+    let q = 1.0 - your_prob;
+
+    // Kelly fraction = (p * b - q) / b = p - q/b
+    // Kelly = your_prob - (1 - your_prob) * market_price / win_amount
+    let kelly_fraction = if win_amount > 0.0 {
+        your_prob - (q * market_price) / win_amount
+    } else {
+        0.0
+    };
+
+    // If negative, no bet recommended
+    let optimal_fraction = kelly_fraction.max(0.0);
+
+    KellyResult {
+        kelly_fraction: optimal_fraction,
+        half_kelly: optimal_fraction / 2.0,
+        quarter_kelly: optimal_fraction / 4.0,
+        full_bet_size: bankroll * optimal_fraction,
+        half_bet_size: bankroll * (optimal_fraction / 2.0),
+        quarter_bet_size: bankroll * (optimal_fraction / 4.0),
+        edge: your_prob - market_price,
+        odds: b,
+    }
+}
+
+/// Calculate fractional Kelly for risk management.
+///
+/// # Arguments
+/// * `your_prob` - Your estimated probability of winning
+/// * `market_price` - Current market price
+/// * `bankroll` - Your total bankroll
+/// * `fraction` - Fraction of full Kelly to use (e.g., 0.25 for quarter)
+///
+/// # Returns
+/// Bet size in currency units
+///
+/// # Example
+/// ```
+/// use quant_rust::prediction::kelly::fractional_kelly;
+/// let size = fractional_kelly(0.6, 0.5, 1000.0, 0.5);
+/// assert!(size > 0.0);
+/// ```
+pub fn fractional_kelly(
+    your_prob: f64,
+    market_price: f64,
+    bankroll: f64,
+    fraction: f64,
+) -> f64 {
+    let kelly = kelly_criterion(your_prob, market_price, bankroll);
+    kelly.full_bet_size * fraction
+}
+
+/// Calculate Kelly for multiple simultaneous independent bets.
+///
+/// For independent bets, if total Kelly exceeds 1, we scale down proportionally.
+///
+/// # Arguments
+/// * `bets` - Slice of betting opportunities
+/// * `bankroll` - Your total bankroll
+///
+/// # Returns
+/// Vector of bet sizes (same order as input)
+///
+/// # Example
+/// ```
+/// use quant_rust::prediction::kelly::{kelly_multiple, BetOpportunity};
+/// let bets = vec![
+///     BetOpportunity { your_prob: 0.6, market_price: 0.5 },
+///     BetOpportunity { your_prob: 0.55, market_price: 0.45 },
+/// ];
+/// let sizes = kelly_multiple(&bets, 1000.0);
+/// assert_eq!(sizes.len(), 2);
+/// ```
+pub fn kelly_multiple(bets: &[BetOpportunity], bankroll: f64) -> Vec<f64> {
+    // Calculate Kelly fraction for each bet
+    let kelly_fractions: Vec<f64> = bets
+        .iter()
+        .map(|bet| {
+            let k = kelly_criterion(bet.your_prob, bet.market_price, 1.0);
+            k.kelly_fraction.max(0.0)
+        })
+        .collect();
+
+    let total_kelly: f64 = kelly_fractions.iter().sum();
+
+    // If total exceeds 1, scale down proportionally
+    if total_kelly > 1.0 {
+        let scale = 1.0 / total_kelly;
+        kelly_fractions
+            .iter()
+            .map(|&k| bankroll * k * scale)
+            .collect()
+    } else {
+        kelly_fractions.iter().map(|&k| bankroll * k).collect()
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn test_kelly_criterion_positive_edge() {
+        // 60% probability at 50% price = positive edge
+        let result = kelly_criterion(0.6, 0.5, 1000.0);
+        assert!(result.kelly_fraction > 0.0);
+        assert!(result.edge > 0.0);
+        assert!((result.edge - 0.1).abs() < 1e-10); // 0.6 - 0.5
+        assert!(result.full_bet_size > 0.0);
+    }
+
+    #[test]
+    fn test_kelly_criterion_negative_edge() {
+        // 40% probability at 50% price = negative edge
+        let result = kelly_criterion(0.4, 0.5, 1000.0);
+        assert_eq!(result.kelly_fraction, 0.0); // No bet recommended
+        assert!(result.edge < 0.0);
+    }
+
+    #[test]
+    fn test_kelly_criterion_no_edge() {
+        // 50% probability at 50% price = no edge
+        let result = kelly_criterion(0.5, 0.5, 1000.0);
+        assert_eq!(result.kelly_fraction, 0.0);
+        assert_eq!(result.edge, 0.0);
+    }
+
+    #[test]
+    fn test_kelly_fractions() {
+        let result = kelly_criterion(0.7, 0.5, 1000.0);
+        assert_eq!(result.half_kelly, result.kelly_fraction / 2.0);
+        assert_eq!(result.quarter_kelly, result.kelly_fraction / 4.0);
+    }
+
+    #[test]
+    fn test_fractional_kelly() {
+        let full = kelly_criterion(0.6, 0.5, 1000.0).full_bet_size;
+        let half = fractional_kelly(0.6, 0.5, 1000.0, 0.5);
+        assert!((full * 0.5 - half).abs() < 1e-10);
+    }
+
+    #[test]
+    fn test_kelly_multiple() {
+        let bets = vec![
+            BetOpportunity { your_prob: 0.6, market_price: 0.5 },
+            BetOpportunity { your_prob: 0.55, market_price: 0.45 },
+        ];
+        let sizes = kelly_multiple(&bets, 1000.0);
+        assert_eq!(sizes.len(), 2);
+        assert!(sizes[0] > 0.0);
+        assert!(sizes[1] > 0.0);
+    }
+
+    #[test]
+    fn test_kelly_multiple_scaling() {
+        // Create bets that would exceed 100% allocation
+        let bets = vec![
+            BetOpportunity { your_prob: 0.8, market_price: 0.3 },
+            BetOpportunity { your_prob: 0.8, market_price: 0.3 },
+            BetOpportunity { your_prob: 0.8, market_price: 0.3 },
+        ];
+        let sizes = kelly_multiple(&bets, 1000.0);
+        let total: f64 = sizes.iter().sum();
+        // Total should be at most bankroll (scaled down if needed)
+        assert!(total <= 1000.0 + 1e-10);
+    }
+}