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=SOLVER, **kwargs)

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_contra]	The left-hand side elements.	required
ys	Collection[T_contra]	The right-hand side elements.	required
winners	Collection[Winner]	The winner elements.	required
index	Index | 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	SolverName	The solver.	SOLVER
**kwargs	Any	The additional arguments.	{}

Returns:

Type	Description
EloResult	The Elo result.

Source code in evalica/__init__.py

def elo(
    xs: Collection[T_contra],
    ys: Collection[T_contra],
    winners: Collection[Winner],
    index: pd.Index | None = None,
    initial: float = 1000.0,
    base: float = 10.0,
    scale: float = 400.0,
    k: float = 4.0,
    weights: Collection[float] | None = None,
    win_weight: float = 1.0,
    tie_weight: float = 0.5,
    solver: SolverName = SOLVER,
    **kwargs: Any,  # noqa: ANN401, ARG001
) -> EloResult:
    """
    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.
        **kwargs: The additional arguments.

    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":
        if not PYO3_AVAILABLE:
            raise SolverError(solver)

        scores = _brzo.elo(
            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

The Elo result.

Attributes:

Name	Type	Description
scores	Series[float]	The element scores.
index	Index	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	SolverName	The solver.

Source code in evalica/__init__.py

@dataclass(frozen=True)
class EloResult:
    """
    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: pd.Index
    initial: float
    base: float
    scale: float
    k: float
    win_weight: float
    tie_weight: float
    solver: SolverName