RetrievalExecutionPlan#

class scikitplot.corpus.RetrievalExecutionPlan(retrieval=None, transform=None, keep_original=True, max_queries=8, fusion=None, rerank=None, rerank_depth=None, compress=None, top_k=None, budgets=(), deadline_seconds=None, on_error='degrade', clock=None)[source]#

Run retrieval through typed, bounded stages.

Parameters:

retrievalobject or None, default=None: Passed to index.search as config (a RetrievalConfig); None uses the index’s own.
transformcallable or None, default=None: transform(query) -> sequence of str: rewrites, sub-queries or variants. Empty strings are refused, exact duplicates are run once.
keep_originalbool, default=True: Run the original query first, whatever transform returns.
max_queriesint, default=8: Queries retrieve runs at most; further ones are dropped and the transform stage reports degraded.
fusionFusionPolicy or None, default=None: Fuses the queries’ rankings (the leg of query i is named "q{i}"); None is FusionPolicy(). Not used with one query. A policy with top_k=0 is refused; one that weighs every query 0 makes fuse report degraded.
rerankcallable or None, default=None: rerank(query, hits) -> sequence of float, one finite score per hit, higher is better; ties keep the fused order.
rerank_depthint or None, default=None: Hits passed to rerank; None passes all. When set, top_k must be set too and be at most rerank_depth, so no returned hit is ranked by two scales.
compresscallable or None, default=None: compress(query, hits) -> sequence, one entry per hit, each a sequence of (start, end) character ranges of hit.doc.text, ordered and non-overlapping; an empty entry keeps nothing of that hit (see CharBudgetCompressor).
top_kint or None, default=None: Hits returned; None returns every hit retrieve found.
budgetsmapping of str to StageBudget, default=(): {"retrieve": StageBudget(...)}: the one stage that makes several calls. The other stages make one call each, which a budget checked before calls cannot bound; they are refused here.
deadline_secondsfloat or None, default=None: Seconds after the plan starts beyond which no stage or query starts (fuse, an in-process computation, always runs).
on_error{“degrade”, “raise”}, default=”degrade”: What an exception from a component (or from index.search) does: "degrade" reports the stage failed and keeps the previous stage’s output; "raise" propagates it.
clockcallable or None, default=None: clock() -> seconds; None is time.perf_counter.

Raises:

TypeError, ValueError: For a field of the wrong type or out of range.

Parameters:

retrieval (Any)
transform (Callable[[str], Sequence[str]] | None)
keep_original (bool)
max_queries (int)
fusion (FusionPolicy | None)
rerank (Callable[[str, Sequence[PlannedHit]], Sequence[float]] | None)
rerank_depth (int | None)
compress (Callable[[str, Sequence[PlannedHit]], Sequence[Any]] | None)
top_k (int | None)
budgets (Mapping[str, StageBudget] | tuple[tuple[str, StageBudget], ...])
deadline_seconds (float | None)
on_error (str)
clock (Callable[[], float] | None)

See also

scikitplot.corpus.RetrievalIndex.search: What retrieve calls.
scikitplot.corpus.FusionPolicy: How the queries’ rankings are fused.
scikitplot.corpus.evaluate_retrieval: Measures plan.bind(index).

Notes

User. An empty plan, RetrievalExecutionPlan().run(index, q), returns the hits of index.search(q) in the same order, and its status.

Developer. A stage with nothing to do is skipped (fuse with one query, rerank with no hits), not success, so a report never claims work that was not done.

Examples

>>> plan = RetrievalExecutionPlan(
...     top_k=3, budgets={"retrieve": StageBudget(max_calls=4)}
... )
>>> plan.budget("retrieve")
StageBudget(max_calls=4, max_seconds=None)

bind(index, **kwargs)[source]#

Return query -> self.run(index, query, **kwargs).

Parameters:

indexobject: Anything with search.
**kwargs: Passed to run on every call.

Returns:

callable: For evaluate_retrieval.

Parameters:

index (Any)
kwargs (Any)

Return type:

Callable[[str], ExecutionResult]

budget(stage)[source]#

Return the budget of stage, or None.

Parameters:: stage (StageKind | str)
Return type:: StageBudget | None

budgets: Mapping[str, StageBudget] | tuple[tuple[str, StageBudget], ...] = ()#

clock: Callable[[], float] | None = None#

compress: Callable[[str, Sequence[PlannedHit]], Sequence[Any]] | None = None#

deadline_seconds: float | None = None#

fusion: FusionPolicy | None = None#

keep_original: bool = True#

max_queries: int = 8#

on_error: str = 'degrade'#

rerank: Callable[[str, Sequence[PlannedHit]], Sequence[float]] | None = None#

rerank_depth: int | None = None#

retrieval: Any = None#

run(index, query, *, query_embedding=None, embed_query=None, filter=None)[source]#

Run the plan for query.

Parameters:

indexobject: Anything with search(query, **kwargs) returning an iterable of hits (RetrievalIndex). Each hit carries an identity (hit.doc.doc_id, hit.doc_id or hit.node_id) and a real score; a query whose hits do not fails. Bare (id, score) pairs are not hits.
querystr: The query.
query_embeddingarray-like or None, default=None: Embedding of query itself, passed with it to index.search.
embed_querycallable or None, default=None: embed_query(text) -> embedding for the queries the transform produced (and for query when query_embedding is None). Without it, those queries are searched with no embedding, and a dense leg reports why it could not run.
filterFilter, mapping or None, default=None: Passed to every index.search call.

Returns:

ExecutionResult

Raises:

TypeError: If query is not a str or index has no search; with on_error="raise", a component’s output of the wrong type.
ValueError: If query is empty; with on_error="raise", a component’s output out of range.
Exception: With on_error="raise", whatever a component or index.search raised.

Parameters:

index (Any)
query (str)
query_embedding (Any)
embed_query (Callable[[str], Any] | None)
filter (Any)

Return type:

ExecutionResult

top_k: int | None = None#

transform: Callable[[str], Sequence[str]] | None = None#