Linear Algebra

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

Compute the eigenvalue-based scores.

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
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.	SOLVER
tolerance	float	The convergence tolerance.	1e-06
limit	int	The maximum number of iterations.	100
**kwargs	Any	The additional arguments.	{}

Returns:

Type	Description
EigenResult	The eigenvalue result.

Source code in evalica/__init__.py

def eigen(
    xs: Collection[T_contra],
    ys: Collection[T_contra],
    winners: Collection[Winner],
    index: pd.Index | None = None,
    weights: Collection[float] | None = None,
    win_weight: float = 1.0,
    tie_weight: float = 0.5,
    solver: Literal["naive", "pyo3"] = SOLVER,
    tolerance: float = 1e-6,
    limit: int = 100,
    **kwargs: Any,  # noqa: ANN401, ARG001
) -> EigenResult:
    """
    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.
        **kwargs: The additional arguments.

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

        scores, iterations = _brzo.eigen(
            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,
            solver="naive",
        )

        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

The eigenvalue result.

Attributes:

Name	Type	Description
scores	Series[float]	The element scores.
index	Index	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:
    """
    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: pd.Index
    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=SOLVER, tolerance=1e-06, limit=100, **kwargs)

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_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
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.	SOLVER
tolerance	float	The convergence tolerance.	1e-06
limit	int	The maximum number of iterations.	100
**kwargs	Any	The additional arguments.	{}

Returns:

Type	Description
PageRankResult	The PageRank result.

Source code in evalica/__init__.py

def pagerank(
    xs: Collection[T_contra],
    ys: Collection[T_contra],
    winners: Collection[Winner],
    index: pd.Index | None = None,
    damping: float = 0.85,
    weights: Collection[float] | None = None,
    win_weight: float = 1.0,
    tie_weight: float = 0.5,
    solver: Literal["naive", "pyo3"] = SOLVER,
    tolerance: float = 1e-6,
    limit: int = 100,
    **kwargs: Any,  # noqa: ANN401, ARG001
) -> PageRankResult:
    """
    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.
        **kwargs: The additional arguments.

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

        scores, iterations = _brzo.pagerank(
            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,
            solver="naive",
        )

        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(data=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

The PageRank result.

Attributes:

Name	Type	Description
scores	Series[float]	The element scores.
index	Index	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:
    """
    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: pd.Index
    damping: float
    win_weight: float
    tie_weight: float
    solver: str
    tolerance: float
    iterations: int
    limit: int