ratingslib.ratings.keener module

Keener rating system

class Keener(version=ratings.KEENER, normalization: bool = True)

Bases: RatingSystem

This method has been proposed by James P. Keener in 1993 for football teams ranking in uneven paired competition 1. Keener’s method is based on the theory of nonnegative matrices and forms a smoothed matrix of scores generated by Laplace’s rule of succession.

Parameters

  • version (str, default=ratings.KEENER) – A string that shows the version of rating system. The available versions can be found in ratingslib.utils.enums.ratings class.

  • normalization (bool, default = True) – If True then the result will be normalized according to the total times each item occurs in the dataset. For example in sport teams set normalization = True if the teams haven’t played same number of games.

A

The Keener matrix. It has shape (n, n) where n = the total number of items.

Type

numpy.ndarray

S

The matrix containing the cumulative number of points scored by each item to any other item. It has shape (n, n) where n = the total number of items.

Type

numpy.ndarray

References

1

Keener, J. P., 1993. The Perron-Frobenius theorem and the ranking of football teams. SIAM Review, 35(1), pp. 80-93

Examples

The following example demonstrates Keener rating system, for the 20 first soccer matches that took place during the 2018-2019 season of English Premier League.

>>> from ratingslib.datasets.filenames import dataset_path, FILENAME_EPL_2018_2019_20_GAMES
>>> from ratingslib.ratings.keener import Keener
>>> filename = dataset_path(FILENAME_EPL_2018_2019_20_GAMES)
>>> Keener(normalization=False).rate_from_file(filename)
              Item    rating  ranking
0          Arsenal  0.047220       17
1      Bournemouth  0.052874        4
2         Brighton  0.049183       11
3          Burnley  0.048576       14
4          Cardiff  0.048243       16
5          Chelsea  0.052800        5
6   Crystal Palace  0.049870       10
7          Everton  0.051214        7
8           Fulham  0.046829       18
9     Huddersfield  0.046068       20
10       Leicester  0.050701        8
11       Liverpool  0.053796        1
12        Man City  0.053511        2
13      Man United  0.050322        9
14       Newcastle  0.048939       13
15     Southampton  0.048969       12
16       Tottenham  0.052569        6
17         Watford  0.053265        3
18        West Ham  0.046730       19
19          Wolves  0.048320       15
static compute(A: ndarray)
computation_phase()

To be overridden in subclasses.

create_keener_matrix(data_df: DataFrame, items_df: DataFrame, columns_dict: Optional[Dict[str, Any]] = None) → Tuple[ndarray, ndarray]

Construction of Keener matrix and points matrix S

h_skew(x)

Skewing function

preparation_phase(data_df: DataFrame, items_df: DataFrame, columns_dict: Optional[Dict[str, Any]] = None)

To be overridden in subclasses.

rate(data_df: DataFrame, items_df: DataFrame, sort: bool = False, columns_dict: Optional[Dict[str, Any]] = None) → DataFrame

This method computes ratings for a pairwise data. (e.g. soccer teams games). To be overridden in subclasses.

Parameters

  • data_df (pandas.DataFrame) – The pairwise data.

  • items_df (pandas.DataFrame) – Set of items (e.g. teams) to be rated

  • sort (bool, default=True.) – If true, the output is sorted by rating value

  • columns_dict (Optional[Dict[str, str]]) – The column names of data file. See ratingslib.datasets.parameters.COLUMNS_DICT for more details.

Returns

items_df – The set of items with their rating and ranking.

Return type

pandas.DataFrame