Skip to content

Commit 41891ae

Browse files
atomflunderatomflunder
committed
Overhaul documentation
1 parent 018ee29 commit 41891ae

File tree

4 files changed

+158
-21
lines changed

4 files changed

+158
-21
lines changed

‎CHANGELOG.md‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,10 @@
22

33
This is a broad overview of the changes that have been made over the lifespan of this library.
44

5+
## v0.25.1 - 2023-10-05
6+
7+
- Overhaul documentation
8+
59
## v0.25.0 - 2023-06-04
610

711
- Add Rating, RatingSystem, RatingPeriodSystem, TeamRatingSystem, and MultiTeamRatingSystem traits

‎Cargo.toml‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
[package]
22
name = "skillratings"
3-
version = "0.25.0"
3+
version = "0.25.1"
44
edition = "2021"
55
description = "Calculate a player's skill rating using algorithms like Elo, Glicko, Glicko-2, TrueSkill and many more."
66
readme = "README.md"

‎README.md‎

Lines changed: 61 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -27,11 +27,26 @@ Currently supported algorithms:
2727
Most of these are known from their usage in chess and various other games.
2828
Click on the documentation for the modules linked above for more information about the specific rating algorithms, and their advantages and disadvantages.
2929

30+
## Table of Contents
31+
32+
- [Installation](#installation)
33+
- [Serde Support](#serde-support)
34+
- [Usage and Examples](#usage-and-examples)
35+
- [Player vs. Player](#player-vs-player)
36+
- [Team vs. Team](#team-vs-team)
37+
- [Free-For-Alls and Multiple Teams](#free-for-alls-and-multiple-teams)
38+
- [Expected Outcome](#expected-outcome)
39+
- [Rating Period](#rating-period)
40+
- [Switching between different rating systems](#switching-between-different-rating-systems)
41+
- [Contributing](#contributing)
42+
- [License](#license)
43+
44+
3045
## Installation
3146

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

34-
```
49+
```bash
3550
cargo add skillratings
3651
```
3752

@@ -48,7 +63,7 @@ Serde support is gated behind the `serde` feature. You can enable it like so:
4863

4964
Using `cargo add`:
5065

51-
```
66+
```bash
5267
cargo add skillratings --features serde
5368
```
5469

@@ -278,6 +293,50 @@ let new_player = elo_rating_period(&player, &results, &EloConfig::new());
278293
assert_eq!(new_player.rating.round(), 1362.0);
279294
```
280295

296+
### Switching between different rating systems
297+
298+
If you want to switch between different rating systems, for example to compare results or do scientific analyisis,
299+
we provide the `Rating`, `RatingSystem` (1v1), `RatingPeriodSystem` (1v1 Tournaments), `TeamRatingSystem` (Team vs. Team)
300+
and `MultiTeamRatingSystem` (FFA) traits to make switching as easy as possible.
301+
302+
In the following example, we are using the `RatingSystem` (1v1) Trait with Glicko-2:
303+
304+
```rust
305+
use skillratings::{
306+
glicko2::{Glicko2, Glicko2Config},
307+
Outcomes, Rating, RatingSystem,
308+
};
309+
310+
// Initialise a new player rating with a rating value and uncertainty value.
311+
// Not every rating system has an uncertainty value, so it may be discarded.
312+
let player_one = Rating::new(Some(1200.0), Some(120.0));
313+
// If you want the default values for the rating system, use None instead.
314+
let player_two = Rating::new(None, None);
315+
316+
// The config needs to be specific to the rating system.
317+
// When you swap rating systems, make sure to update the config.
318+
let config = Glicko2Config::new();
319+
320+
// You may also need to use a type annotation here for the compiler.
321+
let rating_system: Glicko2 = RatingSystem::new(config);
322+
323+
// The outcome of the match is from the perspective of player one.
324+
let outcome = Outcomes::WIN;
325+
326+
// All rating systems share a `rate` function for performing the actual calculations,
327+
// plus an `expected_score` function for calculating the expected performances.
328+
// Some rating systems might have additional functions,
329+
// which are only available when you use them directly.
330+
let expected_score = rating_system.expected_score(&player_one, &player_two);
331+
let (new_one, new_two) = rating_system.rate(&player_one, &player_two, &outcome);
332+
333+
// After that, you can access the players rating and uncertainty with the functions below.
334+
assert_eq!(new_one.rating().round(), 1241.0);
335+
// Note that because not every rating system has an uncertainty value,
336+
// the uncertainty function returns an Option<f64>.
337+
assert_eq!(new_one.uncertainty().unwrap().round(), 118.0);
338+
```
339+
281340
## Contributing
282341

283342
Contributions of any kind are always welcome!

‎src/lib.rs‎

Lines changed: 92 additions & 18 deletions
Original file line numberDiff line numberDiff line change
@@ -16,26 +16,42 @@
1616

1717
//! Skillratings provides a collection of well-known (and lesser known) skill rating algorithms, that allow you to assess a player's skill level instantly.
1818
//! You can easily calculate skill ratings instantly in 1vs1 matches, Team vs Team matches, or in tournaments / rating periods.
19-
//! This library is incredibly lightweight (no dependencies by default), user-friendly, and of course, *blazingly fast*.
20-
//!
21-
//! Currently we support these skill rating systems:
22-
//! - **[`Elo`](crate::elo)**
23-
//! - **[`Glicko`](crate::glicko)**
24-
//! - **[`Glicko-2`](crate::glicko2)**
25-
//! - **[`TrueSkill`](crate::trueskill)**
26-
//! - **[`Weng-Lin`](crate::weng_lin)**
27-
//! - **[`FIFA Men's World Ranking`](crate::fifa)**
28-
//! - **[`Sticko`](crate::sticko)**
29-
//! - **[`Glicko-Boost`](crate::glicko_boost)**
30-
//! - **[`USCF (US Chess Federation)`](crate::uscf)**
31-
//! - **[`EGF (European Go Federation)`](crate::egf)**
32-
//! - **[`DWZ (Deutsche Wertungszahl)`](crate::dwz)**
33-
//! - **[`Ingo`](crate::ingo)**
19+
//! This library is incredibly lightweight (no dependencies by default), user-friendly, and of course, *blazingly fast*.
20+
//!
21+
//! Currently supported algorithms:
22+
//!
23+
//! - [Elo](https://docs.rs/skillratings/latest/skillratings/elo/)
24+
//! - [Glicko](https://docs.rs/skillratings/latest/skillratings/glicko/)
25+
//! - [Glicko-2](https://docs.rs/skillratings/latest/skillratings/glicko2/)
26+
//! - [TrueSkill](https://docs.rs/skillratings/latest/skillratings/trueskill/)
27+
//! - [Weng-Lin (Bayesian Approximation System)](https://docs.rs/skillratings/latest/skillratings/weng_lin/)
28+
//! - [FIFA Men's World Ranking](https://docs.rs/skillratings/latest/skillratings/fifa/)
29+
//! - [Sticko (Stephenson Rating System)](https://docs.rs/skillratings/latest/skillratings/sticko/)
30+
//! - [Glicko-Boost](https://docs.rs/skillratings/latest/skillratings/glicko_boost/)
31+
//! - [USCF (US Chess Federation Ratings)](https://docs.rs/skillratings/latest/skillratings/uscf/)
32+
//! - [EGF (European Go Federation Ratings)](https://docs.rs/skillratings/latest/skillratings/egf/)
33+
//! - [DWZ (Deutsche Wertungszahl)](https://docs.rs/skillratings/latest/skillratings/dwz/)
34+
//! - [Ingo](https://docs.rs/skillratings/latest/skillratings/ingo/)
3435
//!
3536
//! Most of these are known from their usage in chess and various other games.
3637
//! Click on the documentation for the modules linked above for more information about the specific rating algorithms, and their advantages and disadvantages.
3738
//!
38-
//! # Installation
39+
//! ## Table of Contents
40+
//!
41+
//! - [Installation](#installation)
42+
//! - [Serde Support](#serde-support)
43+
//! - [Usage and Examples](#usage-and-examples)
44+
//! - [Player vs. Player](#player-vs-player)
45+
//! - [Team vs. Team](#team-vs-team)
46+
//! - [Free-For-Alls and Multiple Teams](#free-for-alls-and-multiple-teams)
47+
//! - [Expected Outcome](#expected-outcome)
48+
//! - [Rating Period](#rating-period)
49+
//! - [Switching between different rating systems](#switching-between-different-rating-systems)
50+
//! - [Contributing](#contributing)
51+
//! - [License](#license)
52+
//!
53+
//!
54+
//! ## Installation
3955
//!
4056
//! If you are on Rust 1.62 or higher use `cargo add` to install the latest version:
4157
//!
@@ -50,7 +66,7 @@
5066
//! skillratings = "0.25"
5167
//! ```
5268
//!
53-
//! ## Serde support
69+
//! ### Serde support
5470
//!
5571
//! Serde support is gated behind the `serde` feature. You can enable it like so:
5672
//!
@@ -67,7 +83,7 @@
6783
//! skillratings = {version = "0.25", features = ["serde"]}
6884
//! ```
6985
//!
70-
//! # Usage and Examples
86+
//! ## Usage and Examples
7187
//!
7288
//! Below you can find some basic examples of the use cases of this crate.
7389
//! There are many more rating algorithms available with lots of useful functions that are not covered here.
@@ -285,6 +301,64 @@
285301
//! // The rating of the player decreased by around ~40 points.
286302
//! assert_eq!(new_player.rating.round(), 1362.0);
287303
//! ```
304+
//!
305+
//! ### Switching between different rating systems
306+
//!
307+
//! If you want to switch between different rating systems, for example to compare results or do scientific analyisis,
308+
//! we provide the `Rating`, `RatingSystem` (1v1), `RatingPeriodSystem` (1v1 Tournaments), `TeamRatingSystem` (Team vs. Team)
309+
//! and `MultiTeamRatingSystem` (FFA) traits to make switching as easy as possible.
310+
//!
311+
//! In the following example, we are using the `RatingSystem` (1v1) Trait with Glicko-2:
312+
//!
313+
//! ```rust
314+
//! use skillratings::{
315+
//! glicko2::{Glicko2, Glicko2Config},
316+
//! Outcomes, Rating, RatingSystem,
317+
//! };
318+
//!
319+
//! // Initialise a new player rating with a rating value and uncertainty value.
320+
//! // Not every rating system has an uncertainty value, so it may be discarded.
321+
//! let player_one = Rating::new(Some(1200.0), Some(120.0));
322+
//! // If you want the default values for the rating system, use None instead.
323+
//! let player_two = Rating::new(None, None);
324+
//!
325+
//! // The config needs to be specific to the rating system.
326+
//! // When you swap rating systems, make sure to update the config.
327+
//! let config = Glicko2Config::new();
328+
//!
329+
//! // You may also need to use a type annotation here for the compiler.
330+
//! let rating_system: Glicko2 = RatingSystem::new(config);
331+
//!
332+
//! // The outcome of the match is from the perspective of player one.
333+
//! let outcome = Outcomes::WIN;
334+
//!
335+
//! // All rating systems share a `rate` function for performing the actual calculations,
336+
//! // plus an `expected_score` function for calculating the expected performances.
337+
//! // Some rating systems might have additional functions,
338+
//! // which are only available when you use them directly.
339+
//! let expected_score = rating_system.expected_score(&player_one, &player_two);
340+
//! let (new_one, new_two) = rating_system.rate(&player_one, &player_two, &outcome);
341+
//!
342+
//! // After that, you can access the players rating and uncertainty with the functions below.
343+
//! assert_eq!(new_one.rating().round(), 1241.0);
344+
//! // Note that because not every rating system has an uncertainty value,
345+
//! // the uncertainty function returns an Option<f64>.
346+
//! assert_eq!(new_one.uncertainty().unwrap().round(), 118.0);
347+
//! ```
348+
//!
349+
//! ## Contributing
350+
//!
351+
//! Contributions of any kind are always welcome!
352+
//!
353+
//! Found a bug or have a feature request? [Submit a new issue](https://github.com/atomflunder/skillratings/issues/).
354+
//! Alternatively, [open a pull request](https://github.com/atomflunder/skillratings/pulls) if you want to add features or fix bugs.
355+
//! Leaving other feedback is of course also appreciated.
356+
//!
357+
//! Thanks to everyone who takes their time to contribute.
358+
//!
359+
//! ## License
360+
//!
361+
//! This project is licensed under either the [MIT License](/LICENSE-MIT), or the [Apache License, Version 2.0](/LICENSE-APACHE).
288362
289363
#[cfg(feature = "serde")]
290364
use serde::de::DeserializeOwned;

0 commit comments

Comments
 (0)