.. DO NOT EDIT. .. THIS FILE WAS AUTOMATICALLY GENERATED BY SPHINX-GALLERY. .. TO MAKE CHANGES, EDIT THE SOURCE PYTHON FILE: .. "auto_examples/annoy/plot_cython_index_api.py" .. LINE NUMBERS ARE GIVEN BELOW. .. only:: html .. note:: :class: sphx-glr-download-link-note :ref:`Go to the end ` to download the full example code or to run this example in your browser via JupyterLite or Binder. .. rst-class:: sphx-glr-example-title .. _sphx_glr_auto_examples_annoy_plot_cython_index_api.py: Index (cython) python-api with examples ======================================= An example showing the :py:class:`~scikitplot.annoy._annoy.Index` class. .. important:: Some parameters are placeholders only and are not processed:: * dtype * index_dtype * wrapper_dtype * random_dtype .. GENERATED FROM PYTHON SOURCE LINES 21-33 .. code-block:: Python import numpy as np import random; random.seed(0) from pprint import pprint # from annoy import Annoy, AnnoyIndex # from scikitplot.cexternals._annoy import Annoy, AnnoyIndex # from scikitplot.annoy import Annoy, AnnoyIndex, Index from scikitplot.annoy._annoy import Index print(Index.__doc__) .. rst-class:: sphx-glr-script-out .. code-block:: none Index(f: Optional[int] = None, metric: Optional[str] = None, int n_neighbors: int = 5, *, on_disk_path: Optional[str] = None, bool prefault: bool = False, seed: Optional[int] = None, verbose: Optional[int] = None, int schema_version: int = 0, str dtype: str = 'float32', str index_dtype: str = 'int32', str wrapper_dtype: str = 'uint64', str random_dtype: str = 'uint64', **kwargs) Annoy Approximate Nearest Neighbors Index. This is a Cython-powered Python wrapper around the Annoy C++ library. Parameters ---------- f : int or None, default=None Embedding dimension. If 0 or None, dimension is inferred from first vector added. Must be positive for immediate index construction. metric : str or None, default=None Distance metric. Supported values: * "angular", "cosine" → cosine-like distance * "euclidean", "l2", "lstsq" → L2 distance * "manhattan", "l1", "cityblock", "taxicab" → L1 distance * "dot", "@", ".", "dotproduct", "inner", "innerproduct" → negative dot product * "hamming" → bitwise Hamming distance If None and f > 0, defaults to "angular" with FutureWarning. n_neighbors : int, default=5 Default number of neighbors for queries (estimator parameter). on_disk_path : str or None, default=None Path for on-disk building. If provided, enables memory-efficient building for large indices. prefault : bool, default=False Whether to prefault pages when loading (may improve query latency). seed : int or None, default=None Random seed for tree construction. If None, uses Annoy's default. Value 0 is treated as "use default" and emits a UserWarning. verbose : int or None, default=None Verbosity level (clamped to [-2, 2]). Level >= 1 enables logging. schema_version : int, default=0 Pickle schema version marker (does not affect on-disk format). dtype : str, default='float32' Data type: float16, float32, float64, float80, float128 index_dtype : str, default='int32' Index type: int32, int64 wrapper_dtype : str, default='uint64' Wrapper type (for Hamming): uint32, uint64 random_dtype : str, default='uint64' Random seed type **kwargs Future extensibility Attributes ---------- f : int Embedding dimension (0 means "unset / lazy"). metric : str or None Canonical metric name, or None if not configured. ptr : AnnoyIndexInterface* Pointer to C++ index (NULL if not constructed). # State Indicators (Internal) _f_valid : bool True if f has been set (> 0) _metric_valid : bool True if metric has been configured _index_constructed : bool True if C++ index exists (ptr != NULL) Examples -------- >>> index = Index(f=128, metric='angular', seed=42) >>> index.add_item(0, [0.1] * 128) >>> index.add_item(1, [0.2] * 128) >>> index.build(n_trees=10) >>> neighbors, distances = index.get_nns_by_item(0, n=5, include_distances=True) set dtype: >>> # Standard usage (float32) >>> index = Index(f=128, metric='angular', dtype='float32') >>> >>> # High precision (float64) >>> index = Index(f=128, metric='euclidean', dtype='float64') >>> >>> # Half precision (float16) - future >>> # index = Index(f=128, metric='angular', dtype='float16') .. GENERATED FROM PYTHON SOURCE LINES 34-38 .. code-block:: Python index = Index() index .. raw:: html
Annoy⍰
Parameters
ParameterValue
f0
metricNone
n_neighbors5
seedNone
verboseNone
on_disk_pathNone
prefaultFalse
schema_version0
dtype'float32'
index_dtype'int32'
wrapper_dtype'uint64'
random_dtype'uint64'


.. GENERATED FROM PYTHON SOURCE LINES 39-42 .. code-block:: Python index.set_params(**index.get_params()) .. raw:: html
Annoy⍰
Parameters
ParameterValue
f0
metricNone
n_neighbors5
seedNone
verboseNone
on_disk_pathNone
prefaultFalse
schema_version0
dtype'float32'
index_dtype'int32'
wrapper_dtype'uint64'
random_dtype'uint64'


.. GENERATED FROM PYTHON SOURCE LINES 43-47 .. code-block:: Python a = index.clone() a .. raw:: html
Annoy⍰
Parameters
ParameterValue
f0
metricNone
n_neighbors5
seedNone
verboseNone
on_disk_pathNone
prefaultFalse
schema_version0
dtype'float32'
index_dtype'int32'
wrapper_dtype'uint64'
random_dtype'uint64'


.. GENERATED FROM PYTHON SOURCE LINES 48-51 .. code-block:: Python Index(10, metric= '.') .. raw:: html
Annoy⍰
Parameters
ParameterValue
f10
metric'.'
n_neighbors5
seedNone
verboseNone
on_disk_pathNone
prefaultFalse
schema_version0
dtype'float32'
index_dtype'int32'
wrapper_dtype'uint64'
random_dtype'uint64'


.. GENERATED FROM PYTHON SOURCE LINES 52-55 .. code-block:: Python Index(10, metric= 'l1') .. raw:: html
Annoy⍰
Parameters
ParameterValue
f10
metric'l1'
n_neighbors5
seedNone
verboseNone
on_disk_pathNone
prefaultFalse
schema_version0
dtype'float32'
index_dtype'int32'
wrapper_dtype'uint64'
random_dtype'uint64'


.. GENERATED FROM PYTHON SOURCE LINES 56-59 .. code-block:: Python Index(10, metric= 'l2') .. raw:: html
Annoy⍰
Parameters
ParameterValue
f10
metric'l2'
n_neighbors5
seedNone
verboseNone
on_disk_pathNone
prefaultFalse
schema_version0
dtype'float32'
index_dtype'int32'
wrapper_dtype'uint64'
random_dtype'uint64'


.. GENERATED FROM PYTHON SOURCE LINES 60-63 .. code-block:: Python Index(10, metric= 'hamming') .. raw:: html
Annoy⍰
Parameters
ParameterValue
f10
metric'hamming'
n_neighbors5
seedNone
verboseNone
on_disk_pathNone
prefaultFalse
schema_version0
dtype'float32'
index_dtype'int32'
wrapper_dtype'uint64'
random_dtype'uint64'


.. GENERATED FROM PYTHON SOURCE LINES 64-81 .. code-block:: Python import numpy as np # Create index index = Index(128) # Add normalized vectors for i in range(1000): v = np.random.randn(128) v = v / np.linalg.norm(v) # Normalize index.add_item(i, v) # Build and query index.build(10) neighbors, distances = index.get_nns_by_item(0, 10, include_distances=True) neighbors, distances .. rst-class:: sphx-glr-script-out .. code-block:: none /home/circleci/.pyenv/versions/3.11.14/lib/python3.11/site-packages/sphinx_gallery/gen_rst.py:801: FutureWarning: The default metric will be removed in a future version. Please pass metric='angular' explicitly. ([0, 409, 627, 786, 228, 780, 636, 536, 325, 127], [0.0003452669770922512, 1.2368390560150146, 1.2540233135223389, 1.2635881900787354, 1.2723208665847778, 1.2764437198638916, 1.2816716432571411, 1.2914178371429443, 1.2927879095077515, 1.301866054534912]) .. GENERATED FROM PYTHON SOURCE LINES 82-85 .. code-block:: Python index.get_params() .. rst-class:: sphx-glr-script-out .. code-block:: none {'f': 128, 'metric': 'angular', 'n_neighbors': 5, 'seed': None, 'verbose': None, 'on_disk_path': None, 'prefault': False, 'schema_version': 0, 'dtype': 'float32', 'index_dtype': 'int32', 'wrapper_dtype': 'uint64', 'random_dtype': 'uint64'} .. GENERATED FROM PYTHON SOURCE LINES 86-90 .. code-block:: Python with index.clone() as idx: pprint(idx.get_state(), sort_dicts=False) .. rst-class:: sphx-glr-script-out .. code-block:: none {'__version__': '1.0', 'params': {'f': 128, 'metric': 'angular', 'n_neighbors': 5, 'seed': None, 'verbose': None, 'on_disk_path': None, 'prefault': False, 'schema_version': 0, 'dtype': 'float32', 'index_dtype': 'int32', 'wrapper_dtype': 'uint64', 'random_dtype': 'uint64'}, 'constructed': True, 'n_items': 0, 'n_trees': 0, 'index_data': None} .. GENERATED FROM PYTHON SOURCE LINES 91-95 .. tags:: level: beginner purpose: showcase .. rst-class:: sphx-glr-timing **Total running time of the script:** (0 minutes 0.169 seconds) .. _sphx_glr_download_auto_examples_annoy_plot_cython_index_api.py: .. only:: html .. container:: sphx-glr-footer sphx-glr-footer-example .. container:: binder-badge .. image:: images/binder_badge_logo.svg :target: https://mybinder.org/v2/gh/scikit-plots/scikit-plots/main?urlpath=lab/tree/notebooks/auto_examples/annoy/plot_cython_index_api.ipynb :alt: Launch binder :width: 150 px .. container:: lite-badge .. image:: images/jupyterlite_badge_logo.svg :target: ../../lite/lab/index.html?path=auto_examples/annoy/plot_cython_index_api.ipynb :alt: Launch JupyterLite :width: 150 px .. container:: sphx-glr-download sphx-glr-download-jupyter :download:`Download Jupyter notebook: plot_cython_index_api.ipynb ` .. container:: sphx-glr-download sphx-glr-download-python :download:`Download Python source code: plot_cython_index_api.py ` .. container:: sphx-glr-download sphx-glr-download-zip :download:`Download zipped: plot_cython_index_api.zip ` .. include:: plot_cython_index_api.recommendations .. only:: html .. rst-class:: sphx-glr-signature `Gallery generated by Sphinx-Gallery `_