AnnoyBackend#

class scikitplot.corpus.AnnoyBackend(*, metric='angular', n_trees=10, search_k=-1, impl='auto', dtype=None, index_dtype=None)[source]#

ANN backend over a scikit-plots Annoy Index (default backend).

Works with both shipped Annoy index classes, which expose the same add_item / build / get_nns_by_vector contract:

• scikitplot.annoy.Index — the high-level, mixin-composed class (adds a validated bulk add_items path).

• scikitplot.annoy._annoy.Index — the Cython class, which additionally accepts dtype (embedding precision) and index_dtype (id width).

Parameters:

metricstr, optional

Annoy distance metric. "angular" (default) yields cosine-like ranking; the angular distance is converted back to exact cosine similarity for the unified score contract.

n_treesint, optional

Number of trees built (accuracy/size trade-off).

search_kint, optional

Query-time node budget passed to Annoy; -1 lets Annoy choose.

implstr, optional

Which index class to use: "auto" (default; high-level first, else Cython), "highlevel", or "cython".

dtypestr or None, optional

Embedding precision (e.g. "float32", "float64"). Forwarded only to implementations that accept it (the Cython class); silently ignored otherwise.

index_dtypestr or None, optional

Item-id integer width (e.g. "int32", "uint64") for very large corpora. Cython class only; ignored otherwise.

Parameters:

• metric (str)

• n_trees (int)

• search_k (int)

• impl (str)

• dtype (str)

• index_dtype (str | None)

Notes

Developer note: Annoy’s "angular" metric operates on internally normalised vectors, so for two vectors with cosine similarity c the reported distance is d = sqrt(2 * (1 - c)). Cosine is recovered exactly as c = 1 - d**2 / 2 — the correct inverse (a plain 1 - d/2 is not).

build(embeddings)[source]#

Build the index from an (n_docs, dim) embedding matrix.

Parameters:

embeddingsnumpy.ndarray

Row-major float32 matrix. Rows are not required to be unit-normalised; each backend normalises internally as needed for cosine similarity.

Parameters:

embeddings (Any)

Return type:

None

capabilities()[source]#

Return every declared capability as a mapping.

Returns:

dict

Suitable for a capability report or a build manifest.

Return type:

dict[str, Any]

dependency_modules: ClassVar[str | tuple[str, ...] | None] = ('scikitplot.annoy', 'scikitplot.annoy._annoy')#

property dimension: int | None#

Vector length this index was built with, None before build.

property discarded_options: dict[str, Any]#

Options this backend requested and the index class refused.

Returns:

dict

Empty when everything requested was honoured. A non-empty result means the index is not built the way the caller asked, which an index object alone could never tell them.

dtype: str = 'float32'#

Element type of the indexed vectors.

classmethod is_available()[source]#

Return whether this backend’s optional dependencies are discoverable.

Return type:

bool

memory_profile: str = 'in_memory'#

"in_memory", "mmap" or "hybrid".

metric: str = 'cosine'#

Distance/similarity metric this backend computes.

name: ClassVar[str] = 'annoy'#

query(vector, k)[source]#

Return up to k (row_index, cosine_score) pairs.

Results are sorted by descending cosine_score in [-1, 1] with deterministic, index-ascending tie breaking. A zero-norm query returns an empty list (cosine is undefined). Non-finite queries raise.

Parameters:

• vector (Any)

• k (int)

Return type:

list[tuple[int, float]]

score_semantics: str = 'cosine_similarity'#

Meaning of the score in query results.

"cosine_similarity" – range [-1, 1], higher is better. "bounded_inverse_distance" – range (0, 1], higher is better, but not a similarity: it is 1 / (1 + d) and is not comparable with a cosine score. Declaring this is what lets a threshold be validated against the scale it will actually be applied to (finding F-R06-02).

supports_persistence: bool = True#

Whether this backend’s index can be persisted and reloaded.

True since ANNIndexArtifact landed: an artifact writes the native payload alongside a versioned ordinal->doc_id sidecar and the embedding manifest, so a reloaded index can prove its rows still name the documents they named at write time. Before that, R06 found zero persistence surface in this module and the declaration was False – accurately.

thread_safety: str = 'concurrent_read'#

"single_thread", "concurrent_read" or "full".