A library for calculating player performance ratings based on battle results.

This library implements a Bradley-Terry model based rating system that estimates player performance levels from head-to-head battle outcomes. The algorithm uses Newton-Raphson iteration to find maximum likelihood estimates of player ratings that best explain the observed win/loss patterns.

Usage

use nypc_perf::{BattleResult, PerfCalc, Rating};

// Create battle results between players
let battles = vec![
    BattleResult {
        i: 0,           // Player 0
        j: 1,           // Player 1
        wij: 2.0,       // Player 0 won twice against Player 1
        wji: 1.0,       // Player 1 won once against Player 0
    },
    BattleResult {
        i: 0,
        j: 2,
        wij: 1.0,
        wji: 0.0,
    }
];

// Initialize performance ratings to 0
let mut perf = vec![Rating::new(0.0), Rating::new(0.0), Rating::new_fixed(0.0)];

// Run the rating calculation
let result = PerfCalc::new()
    .max_iters(100)     // Maximum iterations (default: 100)
    .epsilon(1e-6)      // Convergence threshold (default: 1e-6)
    .run(&mut perf, &battles);

// Check if calculation converged
match result {
    Ok(iters) => println!("Converged after {} iterations", iters),
    Err(err) => println!("Did not converge, final error: {}", err)
}

// perf now contains the estimated log-performance ratings
// Higher values indicate better performance

Mathematical Model

The library uses the Bradley-Terry model. Under this model, the probability of player i winning against player j is:

P(i beats j) = 1 / (1 + exp(βⱼ - βᵢ))

where βᵢ is the log-performance rating of player i.

The algorithm finds values of βᵢ that maximize the likelihood of the observed battle outcomes, with normal prior. For more details on the mathematical foundations and implementation, see docs/rating.pdf.

Performance

The algorithm typically converges within 10-20 iterations for moderately sized problems (100s of players, 10000s of battles).