Add more comparison methods for Rating objects and update documentation.

Author: vivekjoshy

.bumpversion.cfg

@@ -1,5 +1,5 @@
 [bumpversion]
-current_version = 2.3.0
+current_version = 2.4.0
 commit = False
 tag = False
 parse = (?P<major>\d+)\.(?P<minor>\d+)\.(?P<patch>\d+)(\-(?P<release>[a-z]+)\.(?P<build>\d+))?

README.md

@@ -135,6 +135,9 @@ The default model is `PlackettLuce`. You can import alternate models from `opens
 - Full pairing should have more accurate ratings over partial pairing, however in high k games (like a 100+ person marathon race), Bradley-Terry and Thurstone-Mosteller models need to do a calculation of joint probability which involves is a k-1 dimensional integration, which is computationally expensive. Use partial pairing in this case, where players only change based on their neighbors.
 - Plackett-Luce (**default**) is a generalized Bradley-Terry model for k ≥ 3 teams. It scales best.
 
+## Advanced Usage
+You can learn more about how to configure this library to suit your custom needs in the [project documentation](https://openskillpy.readthedocs.io/en/stable/advanced.html).
+
 
 ## Implementations in other Languages
 - [Javascript](https://github.com/philihp/openskill.js)

docs/_static/ordinals.png

@@ -0,0 +1,53 @@
+==============
+Advanced Guide
+==============
+
+.. warning::
+
+  These features have not been tested against real world data to check for their efficacy. You should test the parameters against your own data to ensure they suit your needs.
+
+
+Additive Dynamics Factor
+========================
+If ``sigma`` gets too small, eventually the rating change volatility will decrease. To prevent this you can pass the parameter ``tau`` to :class:`~openskill.rate.rate`. ``tau`` should preferably be a small decimal of two significant digits.
+
+Here are some visuals of how ordinals change with different ``tau`` values:
+
+.. image:: _static/tau.png
+
+You can combine ``tau`` with another parameter ``prevent_sigma_increase`` to ensure the win probability always remains congruent with the actual win rate.
+
+Here is how this looks:
+
+.. image:: _static/ordinals.png
+
+Time Decay
+==========
+
+You can represent the decay of a player's skill over time by increasing ``sigma`` by a little per match not played (or every time interval). First collect data on by how much sigma goes up or down by resetting sigma to it's default value per interval. The value by which ``sigma`` should change must be an average of the change of ``sigma`` over all matches when ``sigma`` is reset per interval.
+
+Here is an example of how to do this:
+
+.. literalinclude:: time_decay.py
+
+This will produce the following output:
+
+.. code-block:: console
+
+    Before Large Decay:
+    Player X: mu=26.986479759996925, sigma=1.879261533806081
+    Player Y: mu=22.87672143851661, sigma=1.879261533806081
+
+    Predict Winner Before Decay:
+    X has a  70.27% chance of winning over Y
+
+    Player X's Rating After Decay:
+    Player X: mu=26.983781247317594, sigma=5.101382249884723
+
+    After Large Decay (1 Year):
+    Player X: mu=28.199913286886318, sigma=4.958583411621401
+    Player Y: mu=22.711677880164803, sigma=1.881565104224607
+
+    Predict Winner After Decay:
+    X has a  58.51% chance of winning over Y
+

docs/_static/tau.png

@@ -18,6 +18,7 @@ Contents
    Contribution Guidelines <contributing>
    Installation <installation>
    User Manual <manual>
+   Advanced Usage <advanced>
    Module Reference <api/modules>
 
 

docs/advanced.rst

@@ -0,0 +1,57 @@
+from openskill import Rating, rate, predict_win
+
+x, y = Rating(), Rating()
+
+mu_precision = 1 + 0.0001 / 365
+sigma_precision = 1 + 1 / 365
+
+# Let player X win 66% of the games.
+for match in range(10000):
+    if match % 3:
+        [[x], [y]] = rate([[x], [y]])
+    else:
+        [[y], [x]] = rate([[y], [x]])
+
+    # Decay Rating - Assume 1 Match Per Day
+    x.mu /= mu_precision
+    y.mu /= mu_precision
+
+    x.sigma *= sigma_precision
+    y.sigma *= sigma_precision
+
+print("Before Large Decay: ")
+print(f"Player X: mu={x.mu}, sigma={x.sigma}")
+print(f"Player Y: mu={y.mu}, sigma={y.sigma}\n")
+
+print("Predict Winner Before Decay:")
+x_percent, y_percent = predict_win([[x], [y]])
+print(f"X has a {x_percent * 100: 0.2f}% chance of winning over Y\n")
+
+# Decay Rating - Assume 365 Days Passed
+for match in range(365):
+
+    # Only player X's rating has decayed.
+    if (x.mu < 25 + 3 * 25 / 3) or (x.mu > 25 - 3 * 25 / 3):
+        x.mu /= mu_precision
+
+    if x.sigma < 25 / 3:
+        x.sigma *= sigma_precision
+
+print("Player X's Rating After Decay: ")
+print(f"Player X: mu={x.mu}, sigma={x.sigma}\n")
+
+# One Match b/w X and Y
+[[x], [y]] = rate([[x], [y]])
+x.mu /= mu_precision
+y.mu /= mu_precision
+x.sigma *= sigma_precision
+y.sigma *= sigma_precision
+
+
+print("After Large Decay (1 Year): ")
+print(f"Player X: mu={x.mu}, sigma={x.sigma}")
+print(f"Player Y: mu={y.mu}, sigma={y.sigma}\n")
+
+print("Predict Winner After Decay:")
+x_percent, y_percent = predict_win([[x], [y]])
+print(f"X has a {x_percent * 100: 0.2f}% chance of winning over Y")

docs/index.rst

@@ -9,4 +9,4 @@
 )
 
 
-__version__ = "2.3.0"
+__version__ = "2.4.0"

docs/time_decay.py

@@ -58,6 +58,114 @@ def __eq__(self, other):
                 "You can only compare Rating objects with each other or a list of two floats."
             )
 
+    def __lt__(self, other):
+        if isinstance(other, Rating):
+            if ordinal(self) < ordinal(other):
+                return True
+            else:
+                return False
+        elif isinstance(other, (list, tuple)):
+            if len(other) == 2:
+                for value in other:
+                    if not isinstance(value, (int, float)):
+                        raise ValueError(
+                            f"The {other.__class__.__name__} contains an "
+                            f"element '{value}' of type '{value.__class__.__name__}'"
+                        )
+                if ordinal(self) < ordinal([other[0], other[1]]):
+                    return True
+                else:
+                    return False
+            else:
+                raise ValueError(
+                    f"The '{other.__class__.__name__}' object has more than two floats."
+                )
+        else:
+            raise ValueError(
+                "You can only compare Rating objects with each other or a list of two floats."
+            )
+
+    def __gt__(self, other):
+        if isinstance(other, Rating):
+            if ordinal(self) > ordinal(other):
+                return True
+            else:
+                return False
+        elif isinstance(other, (list, tuple)):
+            if len(other) == 2:
+                for value in other:
+                    if not isinstance(value, (int, float)):
+                        raise ValueError(
+                            f"The {other.__class__.__name__} contains an "
+                            f"element '{value}' of type '{value.__class__.__name__}'"
+                        )
+                if ordinal(self) > ordinal([other[0], other[1]]):
+                    return True
+                else:
+                    return False
+            else:
+                raise ValueError(
+                    f"The '{other.__class__.__name__}' object has more than two floats."
+                )
+        else:
+            raise ValueError(
+                "You can only compare Rating objects with each other or a list of two floats."
+            )
+
+    def __le__(self, other):
+        if isinstance(other, Rating):
+            if ordinal(self) <= ordinal(other):
+                return True
+            else:
+                return False
+        elif isinstance(other, (list, tuple)):
+            if len(other) == 2:
+                for value in other:
+                    if not isinstance(value, (int, float)):
+                        raise ValueError(
+                            f"The {other.__class__.__name__} contains an "
+                            f"element '{value}' of type '{value.__class__.__name__}'"
+                        )
+                if ordinal(self) <= ordinal([other[0], other[1]]):
+                    return True
+                else:
+                    return False
+            else:
+                raise ValueError(
+                    f"The '{other.__class__.__name__}' object has more than two floats."
+                )
+        else:
+            raise ValueError(
+                "You can only compare Rating objects with each other or a list of two floats."
+            )
+
+    def __ge__(self, other):
+        if isinstance(other, Rating):
+            if ordinal(self) >= ordinal(other):
+                return True
+            else:
+                return False
+        elif isinstance(other, (list, tuple)):
+            if len(other) == 2:
+                for value in other:
+                    if not isinstance(value, (int, float)):
+                        raise ValueError(
+                            f"The {other.__class__.__name__} contains an "
+                            f"element '{value}' of type '{value.__class__.__name__}'"
+                        )
+                if ordinal(self) >= ordinal([other[0], other[1]]):
+                    return True
+                else:
+                    return False
+            else:
+                raise ValueError(
+                    f"The '{other.__class__.__name__}' object has more than two floats."
+                )
+        else:
+            raise ValueError(
+                "You can only compare Rating objects with each other or a list of two floats."
+            )
+
 
 def ordinal(agent: Union[Rating, list, tuple], **options) -> float:
     """
@@ -147,6 +255,9 @@ def rate(teams: List[List[Rating]], **options) -> List[List[Rating]]:
     :param prevent_sigma_increase: A :class:`~bool` that prevents sigma from ever increasing.
     :param options: Pass in a set of custom values for constants defined in the Weng-Lin paper.
     :return: Returns a list of :class:`~openskill.rate.Rating` objects.
+
+    .. note::
+       ``tau`` will default to ``25/300`` in the next major version update.
     """
     original_teams = copy.deepcopy(teams)
     if "tau" in options:

openskill/__init__.py

@@ -9,6 +9,25 @@ def test_rating():
     assert Rating(mu=32.124, sigma=1.421) != Rating()
     assert Rating(mu=32.124, sigma=1.421) != [23.84, 3.443]
 
+    assert Rating() <= Rating()
+    assert Rating() >= Rating()
+    assert Rating(mu=32.124, sigma=1.421) > [23.84, 3.443]
+    assert Rating(mu=32.124, sigma=1.421) > Rating(mu=23.84, sigma=3.443)
+    assert Rating(mu=23.84, sigma=3.443) < [32.124, 1.421]
+    assert [23.84, 3.443] < Rating(mu=32.124, sigma=1.421)
+    assert Rating(mu=23.84, sigma=3.443) < Rating(mu=32.124, sigma=1.421)
+    assert [23.84, 3.443] <= Rating(mu=32.124, sigma=1.421)
+    assert Rating(mu=23.84, sigma=3.443) <= [32.124, 1.421]
+    assert not (Rating(mu=32.124, sigma=1.421) < [23.84, 3.443])
+    assert not (Rating(mu=32.124, sigma=1.421) < Rating(mu=23.84, sigma=3.443))
+    assert not ([23.84, 3.443] > Rating(mu=32.124, sigma=1.421))
+    assert not (Rating(mu=23.84, sigma=3.443) > Rating(mu=32.124, sigma=1.421))
+    assert not (Rating(mu=23.84, sigma=3.443) > [32.124, 1.421])
+    assert not (Rating(mu=32.124, sigma=1.421) <= Rating(mu=23.84, sigma=3.443))
+    assert not (Rating(mu=32.124, sigma=1.421) <= [23.84, 3.443])
+    assert not (Rating(mu=23.84, sigma=3.443) >= Rating(mu=32.124, sigma=1.421))
+    assert not (Rating(mu=23.84, sigma=3.443) >= [32.124, 1.421])
+
     with pytest.raises(ValueError):
         assert Rating(mu=32.124, sigma=1.421) == ["random_string", 5.6]
 
@@ -17,3 +36,39 @@ def test_rating():
 
     with pytest.raises(ValueError):
         assert Rating(mu=32.124, sigma=1.421) == "random_string"
+
+    with pytest.raises(ValueError):
+        assert Rating(mu=32.124, sigma=1.421) < ["random_string", 5.6]
+
+    with pytest.raises(ValueError):
+        assert Rating(mu=32.124, sigma=1.421) < [23.84, 3.443, 5.6]
+
+    with pytest.raises(ValueError):
+        assert Rating(mu=32.124, sigma=1.421) < "random_string"
+
+    with pytest.raises(ValueError):
+        assert Rating(mu=32.124, sigma=1.421) > ["random_string", 5.6]
+
+    with pytest.raises(ValueError):
+        assert Rating(mu=32.124, sigma=1.421) > [23.84, 3.443, 5.6]
+
+    with pytest.raises(ValueError):
+        assert Rating(mu=32.124, sigma=1.421) > "random_string"
+
+    with pytest.raises(ValueError):
+        assert Rating(mu=32.124, sigma=1.421) <= ["random_string", 5.6]
+
+    with pytest.raises(ValueError):
+        assert Rating(mu=32.124, sigma=1.421) <= [23.84, 3.443, 5.6]
+
+    with pytest.raises(ValueError):
+        assert Rating(mu=32.124, sigma=1.421) <= "random_string"
+
+    with pytest.raises(ValueError):
+        assert Rating(mu=32.124, sigma=1.421) >= ["random_string", 5.6]
+
+    with pytest.raises(ValueError):
+        assert Rating(mu=32.124, sigma=1.421) >= [23.84, 3.443, 5.6]
+
+    with pytest.raises(ValueError):
+        assert Rating(mu=32.124, sigma=1.421) >= "random_string"