Crate nypc_perf 

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

This library implements a Bradley-Terry model based performance 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).

Structs

BattleResult

Represents the outcome of battles between two players. wij is the number of wins of i over j, wji is the number of wins of j over i. The scale matter, since we have the normal prior. Higher number means higher observance.

PerfCalc

Builder for configuring and running the performance calculation algorithm This builder is used to configure the number of iterations and the convergence threshold. The default settings are:

Rating

Represents a player’s rating. If fixed, the value is fixed and cannot be changed. If not fixed, the value is a variable and can be changed. The value is the log-performance rating of the player.