Elo

evalica.elo(xs, ys, winners, index=None, initial=1000.0, base=10.0, scale=400.0, k=4.0, weights=None, win_weight=1.0, tie_weight=0.5, solver='pyo3')

Compute the Elo scores.

Quote

Elo, A.E.: The rating of chessplayers, past and present. Arco Pub, New York (1978).

Parameters:

Name	Type	Description	Default
xs	Collection[T]	The left-hand side elements.	required
ys	Collection[T]	The right-hand side elements.	required
winners	Collection[Winner]	The winner elements.	required
index	dict[T, int] | None	The index.	None
initial	float	The initial score of each element.	1000.0
base	float	The base of the exponent.	10.0
scale	float	The scale factor.	400.0
k	float	The K-factor.	4.0
weights	Collection[float] | None	The example weights.	None
win_weight	float	The win weight.	1.0
tie_weight	float	The tie weight.	0.5
solver	Literal['naive', 'pyo3']	The solver.	'pyo3'

Returns:

Type	Description
EloResult[T]	The Elo result.

Source code in evalica/__init__.py

def elo(
        xs: Collection[T],
        ys: Collection[T],
        winners: Collection[Winner],
        index: dict[T, int] | None = None,
        initial: float = 1000.,
        base: float = 10.,
        scale: float = 400.,
        k: float = 4.,
        weights: Collection[float] | None = None,
        win_weight: float = 1.0,
        tie_weight: float = 0.5,
        solver: Literal["naive", "pyo3"] = "pyo3",
) -> EloResult[T]:
    """
    Compute the Elo scores.

    Quote:
        Elo, A.E.: The rating of chessplayers, past and present. Arco Pub, New York (1978).

    Args:
        xs: The left-hand side elements.
        ys: The right-hand side elements.
        winners: The winner elements.
        index: The index.
        initial: The initial score of each element.
        base: The base of the exponent.
        scale: The scale factor.
        k: The K-factor.
        weights: The example weights.
        win_weight: The win weight.
        tie_weight: The tie weight.
        solver: The solver.

    Returns:
        The Elo result.

    """
    xs_indexed, ys_indexed, index = indexing(xs, ys, index)

    assert index is not None, "index is None"

    weights = _wrap_weights(weights, len(xs_indexed))

    if solver == "pyo3":
        scores = elo_pyo3(
            xs=xs_indexed,
            ys=ys_indexed,
            winners=winners,
            weights=weights,
            total=len(index),
            initial=initial,
            base=base,
            scale=scale,
            k=k,
            win_weight=win_weight,
            tie_weight=tie_weight,
        )
    else:
        scores = elo_naive(
            xs=xs_indexed,
            ys=ys_indexed,
            winners=winners,
            weights=weights,
            total=len(index),
            initial=initial,
            base=base,
            scale=scale,
            k=k,
            win_weight=win_weight,
            tie_weight=tie_weight,
        )

    return EloResult(
        scores=pd.Series(scores, index=index, name=elo.__name__).sort_values(ascending=False, kind="stable"),
        index=index,
        initial=initial,
        base=base,
        scale=scale,
        k=k,
        win_weight=win_weight,
        tie_weight=tie_weight,
        solver=solver,
    )

evalica.EloResult dataclass

Bases: Generic[T]

The Elo result.

Attributes:

Name	Type	Description
scores	Series[float]	The element scores.
index	dict[T, int]	The index.
initial	float	The initial score of each element.
base	float	The base of the exponent.
scale	float	The scale factor.
k	float	The K-factor.
win_weight	float	The win weight.
tie_weight	float	The tie weight.
solver	str	The solver.

Source code in evalica/__init__.py

@dataclass(frozen=True)
class EloResult(Generic[T]):
    """
    The Elo result.

    Attributes:
        scores: The element scores.
        index: The index.
        initial: The initial score of each element.
        base: The base of the exponent.
        scale: The scale factor.
        k: The K-factor.
        win_weight: The win weight.
        tie_weight: The tie weight.
        solver: The solver.

    """

    scores: pd.Series[float]
    index: dict[T, int]
    initial: float
    base: float
    scale: float
    k: float
    win_weight: float
    tie_weight: float
    solver: str