Utilities

evalica.Winner

Bases: Enum

The outcome of the pairwise comparison.

Source code in evalica/evalica.pyi

class Winner(Enum):
    """The outcome of the pairwise comparison."""
    X = ...
    """The first element won."""
    Y = ...
    """The second element won."""
    Draw = ...
    """There is a tie."""

Draw = ... class-attribute instance-attribute

There is a tie.

X = ... class-attribute instance-attribute

The first element won.

Y = ... class-attribute instance-attribute

The second element won.

evalica.WINNERS = [Winner.X, Winner.Y, Winner.Draw] module-attribute

Known values of Winner.

evalica.indexing(xs, ys, index=None)

Map the input elements into their numerical representations.

Parameters:

Name	Type	Description	Default
xs	Collection[T]	The left-hand side elements.	required
ys	Collection[T]	The right-hand side elements.	required
index	dict[T, int] | None	The pre-computed index.	None

Returns:

Type	Description
tuple[list[int], list[int], dict[T, int]]	The tuple containing the numerical representations of the input elements and the corresponding index.

Source code in evalica/__init__.py

def indexing(
        xs: Collection[T],
        ys: Collection[T],
        index: dict[T, int] | None = None,
) -> tuple[list[int], list[int], dict[T, int]]:
    """
    Map the input elements into their numerical representations.

    Args:
        xs: The left-hand side elements.
        ys: The right-hand side elements.
        index: The pre-computed index.

    Returns:
        The tuple containing the numerical representations of the input elements and the corresponding index.

    """
    if index is None:
        index = {}
        xy_index = index
    else:
        xy_index = MappingProxyType(index)  # type: ignore[assignment]

    def get_index(x: T) -> int:
        if (idx := xy_index.get(x)) is None:
            idx = xy_index[x] = len(xy_index)

        return idx

    xs_indexed = [get_index(x) for x in xs]
    ys_indexed = [get_index(y) for y in ys]

    return xs_indexed, ys_indexed, index

evalica.matrices(xs_indexed, ys_indexed, winners, index, weights=None)

Build win and tie matrices from the given elements.

Parameters:

Name	Type	Description	Default
xs_indexed	Collection[int]	The left-hand side elements.	required
ys_indexed	Collection[int]	The right-hand side elements.	required
winners	Collection[Winner]	The winner elements.	required
index	dict[T, int]	The index.	required
weights	Collection[float] | None	The example weights.	None

Returns:

Type	Description
MatricesResult[T]	The win and tie matrices.

Source code in evalica/__init__.py

def matrices(
        xs_indexed: Collection[int],
        ys_indexed: Collection[int],
        winners: Collection[Winner],
        index: dict[T, int],
        weights: Collection[float] | None = None,
) -> MatricesResult[T]:
    """
    Build win and tie matrices from the given elements.

    Args:
        xs_indexed: The left-hand side elements.
        ys_indexed: The right-hand side elements.
        winners: The winner elements.
        index: The index.
        weights: The example weights.

    Returns:
        The win and tie matrices.

    """
    weights = _wrap_weights(weights, len(xs_indexed))

    win_matrix, tie_matrix = matrices_pyo3(
        xs=xs_indexed,
        ys=ys_indexed,
        winners=winners,
        weights=weights,
        total=len(index),
    )

    return MatricesResult(
        win_matrix=win_matrix,
        tie_matrix=tie_matrix,
        index=index,
    )

evalica.MatricesResult dataclass

Bases: Generic[T]

The win and tie matrices.

Attributes:

Name	Type	Description
win_matrix	NDArray[float64]	The matrix representing wins between the elements.
tie_matrix	NDArray[float64]	The matrix representing ties between the elements; it is always symmetric.
index	dict[T, int]	The index.

Source code in evalica/__init__.py

@dataclass(frozen=True)
class MatricesResult(Generic[T]):
    """
    The win and tie matrices.

    Attributes:
        win_matrix: The matrix representing wins between the elements.
        tie_matrix: The matrix representing ties between the elements; it is always symmetric.
        index: The index.

    """

    win_matrix: npt.NDArray[np.float64]
    tie_matrix: npt.NDArray[np.float64]
    index: dict[T, int]

evalica.pairwise_frame(scores)

Create a data frame out of the estimated pairwise scores.

Parameters:

Name	Type	Description	Default
scores	Series[T]	The element scores.	required

Returns:

Type	Description
DataFrame	The data frame representing pairwise scores between the elements.

Source code in evalica/__init__.py

def pairwise_frame(scores: pd.Series[T]) -> pd.DataFrame:  # type: ignore[type-var]
    """
    Create a data frame out of the estimated pairwise scores.

    Args:
        scores: The element scores.

    Returns:
        The data frame representing pairwise scores between the elements.

    """
    return pd.DataFrame(pairwise_scores(scores.to_numpy()), index=scores.index, columns=scores.index)

evalica.pairwise_scores(scores, solver='pyo3')

Estimate the pairwise scores.

Parameters:

Name	Type	Description	Default
scores	NDArray[float64]	The element scores.	required
solver	Literal['naive', 'pyo3']	The solver.	'pyo3'

Returns:

Type	Description
NDArray[float64]	The matrix representing pairwise scores between the elements.

Source code in evalica/__init__.py

def pairwise_scores(
        scores: npt.NDArray[np.float64],
        solver: Literal["naive", "pyo3"] = "pyo3",
) -> npt.NDArray[np.float64]:
    """
    Estimate the pairwise scores.

    Args:
        scores: The element scores.
        solver: The solver.

    Returns:
        The matrix representing pairwise scores between the elements.

    """
    if scores.ndim != 1:
        raise ScoreDimensionError(scores.ndim)

    if solver == "naive":
        return pairwise_scores_naive(scores)

    return pairwise_scores_pyo3(scores)

evalica.__version__ = ... module-attribute

The version of Evalica.