Usage¶
elora
is a computer model to generate rankings and predictions from paired comparison time series data.
It has obvious applications to sports, but the framework is general and can be used for numerous other purposes including consumer surveys and asset pricing.
Overview¶
This is a brief overview of the elora
Python package.
See Theory for an explanation of the underlying math.
1. Initialization¶
First, import the Elora class.
from elora import Elora
Next, create a Elora class object and specify its constructor arguments.
elora_instance = Elora(k, scale=scale, commutes=commutes)
Parameters¶
k (float) – At bare minimum, you’ll need to specify the rating update factor k which is the first and only positional argument. The k factor controls the magnitude of each rating update, with larger k values making the model more responsive to each comparison outcome. Its value should be chosen by minimizing the model’s predictive error.
scale (float, optional) – The scale parameter sets the standard deviation \(\sigma\) of the normal distribution \(\mathcal{N}(\mu, \sigma^2)\) used to model paired comparison outcomes. If you make the scale parameter small, the predicted outcomes become more deterministic, and if you make it large the predictions become more uncertain. The default value is 1.
commutes (bool, optional) – This parameter describes the expected behavior of the estimated values under label interchange. If commutes=False, it is assumed that the comparisons anticommute under label interchange (default behavior), and if commutes=True, it is assumed they commute. For example, point totals require commutes=True and point spreads require commutes=False.
2. Training data¶
Each elora
training input is a tuple of the form (time, label1, label2)
and each training output is a single number value
.
This training data is passed to the model as four array_like objects of equal length:
times is an array_like object of type np.datetime64 (or compatible string). It specifies the time at which the comparison was made.
labels1 and labels2 are array_like objects of type string. They specify the first and second label names of the entities involved in the comparison.
values is an array_like object of type float. It specifies the numeric value of the comparison, e.g. the value of the point spread or point total.
Warning
It is assumed that the elements of each array match up, i.e. the nth element of each array should correspond to the same comparison. It is not necessary that the comparisons are time ordered.
For example, the data used to train the model might look like the following:
times = ['20090910', '20090913', '20090913']
labels1 = ['PIT', 'ATL', 'BAL']
labels2 = ['TEN', 'MIA', 'KC']
values = [3, 12, 14]
3. Model calibration¶
The model is calibrated by calling the fit function on the training data.
elora_instance.fit(times, labels1, labels2, values, biases=0)
Optionally, when training the model you can specify biases
(float or array_like of floats). These are numbers which add to (or subtract from) the rating difference of each comparison, i.e.
These factors can be used to account for transient advantages and disadvantages such as weather and temporary injuries.
Positive bias numbers increase the expected value of the comparison, and negative values decrease it.
If biases
is a single number, the bias factor is assumed to be constant for all comparisons.
Otherwise, there must be a bias factor for every training input.
Note
The model automatically accounts for global spread bias such as that associated with home field advantage. To take advantage of this functionality, the label entries should be ordered such that the bias is alligned with the first (or second) label.
4. Making predictions¶
Once the model is fit to the training data, there are a number of different functions which can be called to generate predictions for new comparisons at arbitrary points in time.
At its most basic level, the model estimates for each comparison (matchup) the parameters \(\mu\) and \(\sigma\) of the normal distribution \(\mathcal{N}(\mu, \sigma^2)\) used to model that matchup outcome. Once these parameters are known, the statistical properties of the comparison such as its mean value, PDF, and CDF are easily evaluated:
elora_instance.mean(times, labels1, labels2, biases=biases)
elora_instance.pdf(x, times, labels1, labels2, biases=biases)
elora_instance.cdf(x, times, labels1, labels2, biases=biases)
…as well as arbitrary percentiles (or quantiles) of the distribution
elora_instance.percentile([10, 50, 90], times, labels1, labels2, biases=biases)
and it can even draw samples from the estimated survival function probability distribution
elora_instance.sample(times, labels1, labels2, biases=biases, size=100)
Perhaps one of the most useful applications of the model is using its mean and median predictions to create rankings. This is aided by the rank function
elora_instance.rank(time)
which ranks the labels at the specified time according to their expected performance against an average opponent, i.e. an opponent with an average rating.
Reference¶
Main class¶

class
elora.Elora.
__init__
(self, k, scale=1, commutes=False)¶ Elo regressor algorithm (elora)
Analytic implemention of margindependent Elo assuming normally distributed outcomes.
Author: J. Scott Moreland
 Parameters
k (float) – prefactor multiplying the rating exhanged between a pair of labels for a given comparison
scale (float) – scale factor for the distribution used to model the outcome of the comparison variable; must be greater than 0
commutes (bool) – true if comparisons commute under label interchange; false otherwise (default is false)

first_update_time
¶ time of the first comparison
 Type
np.datetime64

last_update_time
¶ time of the last comparison
 Type
np.datetime64

median_value
¶ median expected comparison value
 Type
float

labels
¶ unique compared entity labels
 Type
array of string

examples
¶ comparison training examples
 Type
ndarray

record
¶ record of time and rating states
 Type
dict of ndarray
Training function¶

elora.Elora.
fit
(self, times, labels1, labels2, values, biases=0)¶ Calibrates the model based on the training examples.
 Parameters
times (array of np.datetime64) – comparison datetimes
labels1 (array of str) – comparison labels for first entity
labels2 (array of str) – comparison labels for second entity
values (array of float) – comparison value observed outcomes
biases (array of float) – comparison bias correction factors, default value is 0
Prediction functions¶

elora.Elora.
cdf
(self, x, times, labels1, labels2, biases=0)¶ Computes the comulative distribution function (CDF) for each comparison, i.e. prob(value < x).
 Parameters
x (array of float) – threshold of comparison for each value
times (array of np.datetime64) – comparison datetimes
labels1 (array of str) – comparison labels for first entity
labels2 (array of str) – comparison labels for second entity
values (array of float) – comparison value observed outcomes
biases (array of float) – comparison bias correct factors, default value is 0
 Returns
 cumulative distribution function value
for each input
 Return type
y (array of float)

elora.Elora.
sf
(self, x, times, labels1, labels2, biases=0)¶ Computes the survival function (SF) for each comparison, i.e. prob(value > x).
 Parameters
x (array of float) – threshold of comparison for each value
times (array of np.datetime64) – comparison datetimes
labels1 (array of str) – comparison labels for first entity
labels2 (array of str) – comparison labels for second entity
values (array of float) – comparison value observed outcomes
biases (array of float) – comparison bias correct factors, default value is 0
 Returns
survival function value for each input
 Return type
y (array of float)

elora.Elora.
pdf
(self, x, times, labels1, labels2, biases=0)¶ Computes the probability distribution function (PDF) for each comparison, i.e. P(x).
 Parameters
x (array of float) – input values
times (array of np.datetime64) – comparison datetimes
labels1 (array of str) – comparison labels for first entity
labels2 (array of str) – comparison labels for second entity
values (array of float) – comparison value observed outcomes
biases (array of float) – comparison bias correct factors, default value is 0
 Returns
probability density at each input
 Return type
y (array of float)

elora.Elora.
percentile
(self, p, times, labels1, labels2, biases=0)¶ Computes percentiles p of the probability distribution.
 Parameters
p (array of float) – percentiles to evaluate (in range [0, 100])
times (array of np.datetime64) – comparison datetimes
labels1 (array of str) – comparison labels for first entity
labels2 (array of str) – comparison labels for second entity
values (array of float) – comparison value observed outcomes
biases (array of float) – comparison bias correct factors, default value is 0
 Returns
 values of the distribution corresponding to
each percentile
 Return type
x (array of float)

elora.Elora.
quantile
(self, q, times, labels1, labels2, biases=0)¶ Computes quantiles q of the probability distribution. Same as percentiles but accepts values [0, 1].
 Parameters
q (array of float) – quantiles to evaluate (in range [0, 1])
times (array of np.datetime64) – comparison datetimes
labels1 (array of str) – comparison labels for first entity
labels2 (array of str) – comparison labels for second entity
values (array of float) – comparison value observed outcomes
biases (array of float) – comparison bias correct factors, default value is 0
 Returns
 values of the distribution corresponding to
each quantile
 Return type
x (array of float)

elora.Elora.
mean
(self, times, labels1, labels2, biases=0)¶ Computes the mean of the probability distribution.
 Parameters
times (array of np.datetime64) – comparison datetimes
labels1 (array of str) – comparison labels for first entity
labels2 (array of str) – comparison labels for second entity
values (array of float) – comparison value observed outcomes
biases (array of float) – comparison bias correct factors, default value is 0
 Returns
mean of the probability distribution
 Return type
y (array of float)

elora.Elora.
residuals
(self, y_true=None, standardize=False)¶ Computes residuals of the model predictions for each training example
 Parameters
standardize (bool) – if True, the residuals are standardized to unit variance
 Returns
residuals for each example
 Return type
residuals (array of float)

elora.Elora.
rank
(self, time)¶ Ranks labels by comparing mean of each label to the average label.
 Parameters
time (np.datetime64) – time at which the ranking should be computed.
 Returns
 returns a rank sorted list of
(label, rank) pairs, where rank is the comparison value of the specified summary statistic.
 Return type
label rankings (list of tuples)

elora.Elora.
sample
(self, times, labels1, labels2, biases=0, size=1)¶ Draw random samples from the predicted comparison probability distribution.
 Parameters
times (array_like of np.datetime64) – list of datetimes.
labels1 (array_like of string) – list of first entity labels.
labels2 (array_like of string) – list of second entity labels.
biases (array_like of float, optional) – single bias number or list of bias numbers which match the comparison inputs. Default is 0, in which case no bias is used.
size (int, optional) – number of samples to be drawn. default is 1, in which case a single value is returned.
 Returns
random samples for the comparison outcome
 Return type
x (array of float)