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 anti-commute 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 n-th 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 = ['2009-09-10', '2009-09-13', '2009-09-13']
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.

\[\Delta R = R_\text{label1} - R_\text{label2} + \text{bias}.\]

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 margin-dependent 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)