Linear Algebra

evalica.eigen(xs, ys, winners, index=None, weights=None, win_weight=1.0, tie_weight=0.5, solver='pyo3', tolerance=1e-06, limit=100)

Compute the eigenvalue-based scores.

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
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'
tolerance	float	The convergence tolerance.	1e-06
limit	int	The maximum number of iterations.	100

Returns:

Type	Description
EigenResult[T]	The eigenvalue result.

Source code in evalica/__init__.py

def eigen(
        xs: Collection[T],
        ys: Collection[T],
        winners: Collection[Winner],
        index: dict[T, int] | None = None,
        weights: Collection[float] | None = None,
        win_weight: float = 1.,
        tie_weight: float = .5,
        solver: Literal["naive", "pyo3"] = "pyo3",
        tolerance: float = 1e-6,
        limit: int = 100,
) -> EigenResult[T]:
    """
    Compute the eigenvalue-based scores.

    Args:
        xs: The left-hand side elements.
        ys: The right-hand side elements.
        winners: The winner elements.
        index: The index.
        weights: The example weights.
        win_weight: The win weight.
        tie_weight: The tie weight.
        solver: The solver.
        tolerance: The convergence tolerance.
        limit: The maximum number of iterations.

    Returns:
        The eigenvalue result.

    """
    assert np.isfinite(win_weight), "win_weight must be finite"
    assert np.isfinite(tie_weight), "tie_weight must be finite"

    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, iterations = eigen_pyo3(
            xs=xs_indexed,
            ys=ys_indexed,
            winners=winners,
            weights=weights,
            total=len(index),
            win_weight=win_weight,
            tie_weight=tie_weight,
            tolerance=tolerance,
            limit=limit,
        )
    else:
        _matrices = matrices(
            xs_indexed=xs_indexed,
            ys_indexed=ys_indexed,
            winners=winners,
            index=index,
            weights=weights,
        )

        matrix = _make_matrix(_matrices.win_matrix, _matrices.tie_matrix, win_weight, tie_weight, tolerance)

        scores, iterations = eigen_naive(
            matrix=matrix,
            tolerance=tolerance,
            limit=limit,
        )

    return EigenResult(
        scores=pd.Series(scores, index=index, name=eigen.__name__).sort_values(ascending=False, kind="stable"),
        index=index,
        win_weight=win_weight,
        tie_weight=tie_weight,
        solver=solver,
        tolerance=tolerance,
        iterations=iterations,
        limit=limit,
    )

evalica.EigenResult dataclass

Bases: Generic[T]

The eigenvalue result.

Attributes:

Name	Type	Description
scores	Series[float]	The element scores.
index	dict[T, int]	The index.
win_weight	float	The win weight.
tie_weight	float	The tie weight.
solver	str	The solver.
tolerance	float	The convergence tolerance.
iterations	int	The actual number of iterations.
limit	int	The maximum number of iterations.

Source code in evalica/__init__.py

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

    Attributes:
        scores: The element scores.
        index: The index.
        win_weight: The win weight.
        tie_weight: The tie weight.
        solver: The solver.
        tolerance: The convergence tolerance.
        iterations: The actual number of iterations.
        limit: The maximum number of iterations.

    """

    scores: pd.Series[float]
    index: dict[T, int]
    win_weight: float
    tie_weight: float
    solver: str
    tolerance: float
    iterations: int
    limit: int

evalica.pagerank(xs, ys, winners, index=None, damping=0.85, weights=None, win_weight=1.0, tie_weight=0.5, solver='pyo3', tolerance=1e-06, limit=100)

Compute the PageRank scores.

Quote

Brin, S., Page, L.: The anatomy of a large-scale hypertextual Web search engine. Computer Networks and ISDN Systems. 30, 107–117 (1998). https://doi.org/10.1016/S0169-7552(98)00110-X.

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
damping	float	The damping (alpha) factor.	0.85
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'
tolerance	float	The convergence tolerance.	1e-06
limit	int	The maximum number of iterations.	100

Returns:

Type	Description
PageRankResult[T]	The PageRank result.

Source code in evalica/__init__.py

def pagerank(
        xs: Collection[T],
        ys: Collection[T],
        winners: Collection[Winner],
        index: dict[T, int] | None = None,
        damping: float = .85,
        weights: Collection[float] | None = None,
        win_weight: float = 1.,
        tie_weight: float = .5,
        solver: Literal["naive", "pyo3"] = "pyo3",
        tolerance: float = 1e-6,
        limit: int = 100,
) -> PageRankResult[T]:
    """
    Compute the PageRank scores.

    Quote:
        Brin, S., Page, L.: The anatomy of a large-scale hypertextual Web search engine.
        Computer Networks and ISDN Systems. 30, 107–117 (1998).
        <https://doi.org/10.1016/S0169-7552(98)00110-X>.

    Args:
        xs: The left-hand side elements.
        ys: The right-hand side elements.
        winners: The winner elements.
        index: The index.
        damping: The damping (alpha) factor.
        weights: The example weights.
        win_weight: The win weight.
        tie_weight: The tie weight.
        solver: The solver.
        tolerance: The convergence tolerance.
        limit: The maximum number of iterations.

    Returns:
        The PageRank result.

    """
    assert np.isfinite(win_weight), "win_weight must be finite"
    assert np.isfinite(tie_weight), "tie_weight must be finite"

    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, iterations = pagerank_pyo3(
            xs=xs_indexed,
            ys=ys_indexed,
            winners=winners,
            weights=weights,
            total=len(index),
            damping=damping,
            win_weight=win_weight,
            tie_weight=tie_weight,
            tolerance=tolerance,
            limit=limit,
        )
    else:
        _matrices = matrices(
            xs_indexed=xs_indexed,
            ys_indexed=ys_indexed,
            winners=winners,
            index=index,
            weights=weights,
        )

        matrix = _make_matrix(_matrices.win_matrix, _matrices.tie_matrix, win_weight, tie_weight, tolerance)

        scores, iterations = pagerank_naive(
            matrix=matrix,
            damping=damping,
            tolerance=tolerance,
            limit=limit,
        )

    return PageRankResult(
        scores=pd.Series(scores, index=index, name=pagerank.__name__).sort_values(ascending=False, kind="stable"),
        index=index,
        damping=damping,
        win_weight=win_weight,
        tie_weight=tie_weight,
        solver=solver,
        tolerance=tolerance,
        iterations=iterations,
        limit=limit,
    )

evalica.PageRankResult dataclass

Bases: Generic[T]

The PageRank result.

Attributes:

Name	Type	Description
scores	Series[float]	The element scores.
index	dict[T, int]	The index.
damping	float	The damping (alpha) factor.
win_weight	float	The win weight.
tie_weight	float	The tie weight.
solver	str	The solver.
tolerance	float	The convergence tolerance.
iterations	int	The actual number of iterations.
limit	int	The maximum number of iterations.

Source code in evalica/__init__.py

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

    Attributes:
        scores: The element scores.
        index: The index.
        damping: The damping (alpha) factor.
        win_weight: The win weight.
        tie_weight: The tie weight.
        solver: The solver.
        tolerance: The convergence tolerance.
        iterations: The actual number of iterations.
        limit: The maximum number of iterations.

    """

    scores: pd.Series[float]
    index: dict[T, int]
    damping: float
    win_weight: float
    tie_weight: float
    solver: str
    tolerance: float
    iterations: int
    limit: int