Paired comparisons may arise from records of sports matches, social interactions, or from any set of preferences between pairs of objects. In these settings we can model the "strengths" of each participant, predict future contests, and infer the "depth-of-competition" and "luck" present in the hierarchies considered.
The models implemented in this package are based on this paper:
M. Jerdee, M. E. J. Newman, Luck, skill, and depth of competition in games and social hierarchies, Preprint arxiv:2312.04711 (2023).
The model and implementation is fully Bayesian, and makes use of the pystan wrapper for STAN to implement Hamiltonian Monte Carlo to make inferences.
pairwise-ranking may be installed through pip:
pip install pairwise-rankingOnce installed, the package can be imported as
import rankingNote that this is not import pairwise-ranking.
Files can be in a .gml network format, or read from a .txt file of a list of matches or one of an adjacency matrix of head-to-head records. See the /data directory for examples of properly formatted data.
Once a match_list has been loaded from a data set, the package may be used to rank participants, make predictions, and compute the depth and luck:
# Load data set
match_list = ranking.read_match_list("data/gml_files/dogs.gml")
# Find scores (requires sampling, which can take a while)
scores = ranking.scores(match_list)
print(scores)
# Get ranks (uses cached samples when possible)
ranks = ranking.ranks(match_list)
print(ranks)
# Find probability (and error) of an outcome betwen a pair
player1 = 'MER'
player2 = 'STE'
probability, probability_error = ranking.probability(match_list,player1,player2)
print(f"Probability {probability:.4f}+/-{probability_error:.4f} that {player1} beats {player2}")
# Infer the depth and luck of the hierarchy
params = ranking.depth_and_luck(match_list)
print(f"Depth: {params['depth']:.3f}, Luck: {params['luck']:.3f}")See the file example.py for examples of more advanced usage options and our readthedocs page for further documentation and data set sources.