Giter Club home page Giter Club logo

skillratings's Introduction

skillratings

Skillratings provides a collection of well-known (and lesser known) skill rating algorithms, that allow you to assess a player's skill level instantly.
You can easily calculate skill ratings instantly in 1 vs 1 matches, Team vs Team Matches, Free-For-Alls, Multiple-Team Matches, or in Tournaments / Rating Periods.
This library is incredibly lightweight (no dependencies by default), user-friendly, and of course, blazingly fast.

Currently supported algorithms:

Most of these are known from their usage in online multiplayer games.
Click on the documentation for the modules linked above for more information about the specific rating algorithms, and their advantages and disadvantages.

Table of Contents

Installation

If you are on Rust 1.62 or higher use cargo add to install the latest version:

cargo add skillratings

Alternatively, you can add the following to your Cargo.toml file manually:

[dependencies]
skillratings = "0.27"

Serde support

Serde support is gated behind the serde feature. You can enable it like so:

Using cargo add:

cargo add skillratings --features serde

By editing Cargo.toml manually:

[dependencies]
skillratings = {version = "0.27", features = ["serde"]}

Usage and Examples

Below you can find some basic examples of the use cases of this crate.
There are many more rating algorithms available with lots of useful functions that are not covered here.
For more information, please head over to the documentation.

Player-vs-Player

Every rating algorithm included here can be used to rate 1v1 games.
We use Glicko-2 in this example here.

use skillratings::{
    glicko2::{glicko2, Glicko2Config, Glicko2Rating},
    Outcomes,
};

// Initialise a new player rating.
// The default values are: 1500, 350, and 0.06.
let player_one = Glicko2Rating::new();

// Or you can initialise it with your own values of course.
// Imagine these numbers being pulled from a database.
let (some_rating, some_deviation, some_volatility) = (1325.0, 230.0, 0.05932);
let player_two = Glicko2Rating {
    rating: some_rating,
    deviation: some_deviation,
    volatility: some_volatility,
};

// The outcome of the match is from the perspective of player one.
let outcome = Outcomes::WIN;

// The config allows you to specify certain values in the Glicko-2 calculation.
let config = Glicko2Config::new();

// The glicko2 function will calculate the new ratings for both players and return them.
let (new_player_one, new_player_two) = glicko2(&player_one, &player_two, &outcome, &config);

// The first players rating increased by ~112 points.
assert_eq!(new_player_one.rating.round(), 1612.0);

Team-vs-Team

Some algorithms like TrueSkill or Weng-Lin allow you to rate team-based games as well.
This example shows a 3v3 game using TrueSkill.

use skillratings::{
    trueskill::{trueskill_two_teams, TrueSkillConfig, TrueSkillRating},
    Outcomes,
};

// We initialise Team One as a Vec of multiple TrueSkillRatings.
// The default values for the rating are: 25, 25/3 ≈ 8.33.
let team_one = vec![
    TrueSkillRating {
        rating: 33.3,
        uncertainty: 3.3,
    },
    TrueSkillRating {
        rating: 25.1,
        uncertainty: 1.2,
    },
    TrueSkillRating {
        rating: 43.2,
        uncertainty: 2.0,
    },
];

// Team Two will be made up of 3 new players, for simplicity.
// Note that teams do not necessarily have to be the same size.
let team_two = vec![
    TrueSkillRating::new(),
    TrueSkillRating::new(),
    TrueSkillRating::new(),
];

// The outcome of the match is from the perspective of team one.
let outcome = Outcomes::LOSS;

// The config allows you to specify certain values in the TrueSkill calculation.
let config = TrueSkillConfig::new();

// The trueskill_two_teams function will calculate the new ratings for both teams and return them.
let (new_team_one, new_team_two) = trueskill_two_teams(&team_one, &team_two, &outcome, &config);

// The rating of the first player on team one decreased by around ~1.2 points.
assert_eq!(new_team_one[0].rating.round(), 32.0);

Free-For-Alls and Multiple Teams

The Weng-Lin and TrueSkill algorithms also support rating matches with multiple Teams.
Here is an example showing a 3-Team game with 3 players each.

use skillratings::{
    weng_lin::{weng_lin_multi_team, WengLinConfig, WengLinRating},
    MultiTeamOutcome,
};

// Initialise the teams as Vecs of WengLinRatings.
// Note that teams do not necessarily have to be the same size.
// The default values for the rating are: 25, 25/3 ≈ 8.33.
let team_one = vec![
    WengLinRating {
        rating: 25.1,
        uncertainty: 5.0,
    },
    WengLinRating {
        rating: 24.0,
        uncertainty: 1.2,
    },
    WengLinRating {
        rating: 18.0,
        uncertainty: 6.5,
    },
];

let team_two = vec![
    WengLinRating {
        rating: 44.0,
        uncertainty: 1.2,
    },
    WengLinRating {
        rating: 32.0,
        uncertainty: 2.0,
    },
    WengLinRating {
        rating: 12.0,
        uncertainty: 3.2,
    },
];

// Using the default rating for team three for simplicity.
let team_three = vec![
    WengLinRating::new(),
    WengLinRating::new(),
    WengLinRating::new(),
];

// Every team is assigned a rank, depending on their placement. The lower the rank, the better.
// If two or more teams tie with each other, assign them the same rank.
let rating_groups = vec![
    (&team_one[..], MultiTeamOutcome::new(1)),      // team one takes the 1st place.
    (&team_two[..], MultiTeamOutcome::new(3)),      // team two takes the 3rd place.
    (&team_three[..], MultiTeamOutcome::new(2)),    // team three takes the 2nd place.
];

// The weng_lin_multi_team function will calculate the new ratings for all teams and return them.
let new_teams = weng_lin_multi_team(&rating_groups, &WengLinConfig::new());

// The rating of the first player of team one increased by around ~2.9 points.
assert_eq!(new_teams[0][0].rating.round(), 28.0);

Expected outcome

Every rating algorithm has an expected_score function that you can use to predict the outcome of a game.
This example is using Glicko (not Glicko-2!) to demonstrate.

use skillratings::glicko::{expected_score, GlickoRating};

// Initialise a new player rating.
// The default values are: 1500, and 350.
let player_one = GlickoRating::new();

// Initialising a new rating with custom numbers.
let player_two = GlickoRating {
    rating: 1812.0,
    deviation: 195.0,
};

// The expected_score function will return two floats between 0 and 1 for each player.
// A value of 1 means guaranteed victory, 0 means certain loss.
// Values near 0.5 mean draws are likely to occur.
let (exp_one, exp_two) = expected_score(&player_one, &player_two);

// The expected score for player one is ~0.25.
// If these players would play 100 games, player one is expected to score around 25 points.
// (Win = 1 point, Draw = 0.5, Loss = 0)
assert_eq!((exp_one * 100.0).round(), 25.0);

Rating period

Every rating algorithm included here has a ..._rating_period that allows you to calculate a player's new rating using a list of results.
This can be useful in tournaments, or if you only update ratings at the end of a certain rating period, as the name suggests.
We are using the Elo rating algorithm in this example.

use skillratings::{
    elo::{elo_rating_period, EloConfig, EloRating},
    Outcomes,
};

// We initialise a new Elo Rating here.
// The default rating value is 1000.
let player = EloRating { rating: 1402.1 };

// We need a list of results to pass to the elo_rating_period function.
let mut results = Vec::new();

// And then we populate the list with tuples containing the opponent,
// and the outcome of the match from our perspective.
results.push((EloRating::new(), Outcomes::WIN));
results.push((EloRating { rating: 954.0 }, Outcomes::DRAW));
results.push((EloRating::new(), Outcomes::LOSS));

// The elo_rating_period function calculates the new rating for the player and returns it.
let new_player = elo_rating_period(&player, &results, &EloConfig::new());

// The rating of the player decreased by around ~40 points.
assert_eq!(new_player.rating.round(), 1362.0);

Switching between different rating systems

If you want to switch between different rating systems, for example to compare results or to do scientific analyisis, we provide Traits to make switching as easy and fast as possible.
All you have to do is provide the right Config for your rating system.

Disclaimer: For more accurate and fine-tuned calculations it is recommended that you use the rating system modules directly.
The Traits are primarily meant to be used for comparisions between systems.

In the following example, we are using the RatingSystem (1v1) Trait with Glicko-2:

use skillratings::{
    glicko2::{Glicko2, Glicko2Config},
    Outcomes, Rating, RatingSystem,
 ;

// Initialise a new player rating with a rating value and uncertainty value.
// Not every rating system has an uncertainty value, so it may be discarded.
// Some rating systems might consider other values too (volatility, age, matches played etc.).
// If that is the case, we will use the default values for those.
let player_one = Rating::new(Some(1200.0), Some(120.0));
// Some rating systems might use widely different scales for measuring a player's skill.
// So if you always want the default values for every rating system, use None instead.
let player_two = Rating::new(None, None);

// The config needs to be specific to the rating system.
// When you swap rating systems, make sure to update the config.
let config = Glicko2Config::new();

// We want to rate 1v1 matches here so we are using the `RatingSystem` trait.
// You may also need to use a type annotation here for the compiler.
let rating_system: Glicko2 = RatingSystem::new(config);

// The outcome of the match is from the perspective of player one.
let outcome = Outcomes::WIN;

// Calculate the expected score of the match.
let expected_score = rating_system.expected_score(&player_one, &player_two);
// Calculate the new ratings.
let (new_one, new_two) = rating_system.rate(&player_one, &player_two, &outcome);

// After that, access new ratings and uncertainties with the functions below.
assert_eq!(new_one.rating().round(), 1241.0);
// Note that because not every rating system has an uncertainty value,
// the uncertainty function returns an Option<f64>.
assert_eq!(new_one.uncertainty().unwrap().round(), 118.0);

Contributing

Contributions of any kind are always welcome!

Found a bug or have a feature request? Submit a new issue.
Alternatively, open a pull request if you want to add features or fix bugs.
Leaving other feedback is of course also appreciated.

Thanks to everyone who takes their time to contribute.

License

This project is licensed under either the MIT License, or the Apache License, Version 2.0.

skillratings's People

Contributors

asyncth avatar atomflunder avatar cyqsimon avatar jspspike avatar

Stargazers

 avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar

Watchers

 avatar

skillratings's Issues

Add partial play weights to the full TrueSkill calculations

TrueSkill has the capability for partial play weights, accounting for players who have not played the whole match. These can range from 0.0 (no participation) to 1.0 (full match).

This crate should probably implement these, although I am undecided on how to best do it to be as user-friendly as possible. Passing a partial play weight in every time could be pretty annoying to the user, since in 99.9% of cases, it will be set to 1.0.

Rust doesn't use default values for arguments unfortunately, I think those would come in useful here.

// How it is currently done:
pub fn trueskill_multi_team(
    teams_and_ranks: &[(&[TrueSkillRating], MultiTeamOutcome)],
    config: &TrueSkillConfig,
) -> Vec<Vec<TrueSkillRating>>

// This seems annoying?
// Would also interfere with the RatingSystem Trait
pub fn trueskill_multi_team(
    teams_and_ranks: &[(&[(TrueSkillRating, f64)], MultiTeamOutcome)],
    config: &TrueSkillConfig,
) -> Vec<Vec<TrueSkillRating>>

Maybe it's useful to offer 2 different functions, one with and one without weights? Does seem a bit "bloaty" to me though.

Also, I think this only makes sense to implement for the full trueskill_multi_team and match_quality_multi_team functions, and not the 1-vs-1 and Team-vs-Team shortcuts.
For the match quality, the Matrix implementation also has to be updated in two places in the create_rotated_a_matrix function.
Not sure about the expected_score_multi_team function at the moment.

I think the technical implementation will be fairly straight-forward, but the design choices will be more difficult here. I also wouldn't call this issue urgent, but it would be nice to have eventually, before an eventual 1.0 release.

Support for more than two teams in Weng-Lin

Probably shouldn't be that difficult to do, my primary reason to want this is to be able to calculate ratings for free-for-all matches. I probably can implement this myself, not sure what the API should look like though.

Support multiple teams in TrueSkill algorithms

TrueSkill has the capability of supporting multiple teams just like the WengLin algorithm, and we should implement this.

This means that these functions should be implemented for the TrueSkill algorithm:

  • trueskill_multi_team (Done)
  • draw_probability_multi_team (Done)
  • expected_score_multi_team (Done)

Resources:

Doc comment of `WengLinConfig::beta` is probably incorrect

use skillratings::weng_lin::{self, WengLinConfig, WengLinRating};

fn main() {
    let config = WengLinConfig::default();

    let player = WengLinRating {
        rating: 25.0 + config.beta,
        uncertainty: f64::EPSILON,
    };
    let player_2 = WengLinRating {
        rating: 25.0,
        uncertainty: f64::EPSILON,
    };

    println!(
        "{}",
        weng_lin::expected_score(&player, &player_2, &config).0
    );
}

Output:

0.6697615493266569

That's not 80%

[feat. req.] Inverse update (undo)?

In some cases the user may wish to retroactively invalidate a game and reverse the effects it had on the ratings of the players involved. For example when:

  • a game's result was recorded incorrectly;
  • a player was retroactively disqualified;
  • the tournament in which the game was played was cancelled;
  • etc.

So I think it would be a good idea to provide the inverse of an "update" function, an "undo" if you will.

As far as I know the update algorithm for Elo is invertible, but I'm not sure about other rating systems. Do you think this is something that can be implemented without substantial effort?

`glicko_rating_period` is probably supposed to imply `decay_deviation`

As far as I understand it, Glicko paper requires to increase RD at the beginning of every rating period in Step 1 before changing it again in Step 2, regardless of whether the player played games in previous rating period or not, since it is said that Step 1 should be done for each player and Step 2 specifies RD as a rating deviation from Step 1:

Step 1. Determine the rating and RD for each player at the start of the new rating period based on their rating and RD at the end of the previous period.

[In Step 2] Assume that the player’s pre-period rating is r, and the ratings deviation is RD determined from Step 1.

Which I believe means that glicko_rating_period needs to run step 1 as well, the same equation that decay_deviation uses. This would be similar to Glicko-2 where Step 6 is ran in both glicko2 and glicko2_rating_period.

Recommend Projects

  • React photo React

    A declarative, efficient, and flexible JavaScript library for building user interfaces.

  • Vue.js photo Vue.js

    🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.

  • Typescript photo Typescript

    TypeScript is a superset of JavaScript that compiles to clean JavaScript output.

  • TensorFlow photo TensorFlow

    An Open Source Machine Learning Framework for Everyone

  • Django photo Django

    The Web framework for perfectionists with deadlines.

  • D3 photo D3

    Bring data to life with SVG, Canvas and HTML. 📊📈🎉

Recommend Topics

  • javascript

    JavaScript (JS) is a lightweight interpreted programming language with first-class functions.

  • web

    Some thing interesting about web. New door for the world.

  • server

    A server is a program made to process requests and deliver data to clients.

  • Machine learning

    Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.

  • Game

    Some thing interesting about game, make everyone happy.

Recommend Org

  • Facebook photo Facebook

    We are working to build community through open source technology. NB: members must have two-factor auth.

  • Microsoft photo Microsoft

    Open source projects and samples from Microsoft.

  • Google photo Google

    Google ❤️ Open Source for everyone.

  • D3 photo D3

    Data-Driven Documents codes.