User Manual

Table of Contents

• Introduction
• Implementation
  • Builders
  • Module
• Examples
  • Simple builder
  • Builder with edge weights

Nearest_neighbors_graph_builder

Authors: F. Cazals and T. Dreyfus and C. Roth

Introduction

This package provides operations to build a nearest neighbors graph (NN graph for short), basically a Boost Graph from the BGL library, with weights on the edges representing distances.

The NN graph may be defined by linking all vertices to a subset of its neighbors, k closest or in a given range r. All proimity queries rely on an underlying spatial search engine, as explained in the package Spatial_search .

In a BGL graph, vertices and edges do not carry information a priori. To add pieces of information, one uses so-called property maps.

Implementation

Builders

Consider a Boost Graph G from the BGL library such that each vertex is associated to a point. To be precise, it is assumed that the bundle property of the vertex is a point. The package provides a concept of NearestNeighborsGraphBuilder for building such a graph from a range of points [begin,end) and a spatial search engine (search_engine).

In the following, we assume that one is given a search engine either returning the neighbors of a sample within a distance range, or returning the k nearest neighbors of a sample. Three operations are defined:

• 1) inserting a range of point [begin, end) into a graph G – one vertex is created for each point;

NearestNeighborsGraphBuilder(begin, end, G);

• 2) connecting a vertex u in G to its neighbors, using a search engine :

NearestNeighborsGraphBuilder(u, search_engine, G);

• 3) repeating the last operation for every vertices of G :

NearestNeighborsGraphBuilder(search_engine, G);

It is possible to enforce symmetry, i.e. the presence of an edge between two vertices u and v iff both vertices are mutually nearest neighbors. This is achieved by turning the functor's attribute tag compute_sym to true. In that case, the second operation is called once for u and once for v. The third operation needs to be called only once since all vertices are visited.

It should be stressed that the search engine data structure is a model provided by the package Spatial_search. The base parameters for finding the nearest neighbors of a point are provided by the search engine. In particular, selecting the k nearest neighbors (default) or all the neighbors within a range is an option of the search engine. Note that there is no default value for the number of neighbors in the first case.

The package provides two models of builders :

• SBL::GT::Nearest_neighbors_graph_builder , a simple builder with no prior knowledge on the NNG.

• SBL::GT::Nearest_neighbors_graph_builder_with_edge_weight , a builder assuming that the type of NNG handles weights over the edges, so that distances between vertices bounding an edge can be stored. This is particularly useful when the distance function is heavy to compute, so that it is only computed during the build operation of the NNG.

Module

This package provides the module SBL::Modules::T_Nearest_neighbors_graph_builder_module< ModuleTraits > to build a NNG from an input set of points. The template parameter ModuleTraits must define three types :

• Nearest_neighbors_graph : the type representing the NNG, derived from the Boost Graph library;

• Nearest_neighbors_distance : the distance functor between two points (it has to define itself the types Point representing a point, and FT representing the coordinates type;

• Nearest_neighbors_query< Distance > : a template class for the spatial search engine, parametrized by a distance functor between vertices of the NNG;

When dealing with points in a high dimensional space, storing and duplicating the input points may be expensive. To overcome this limit, we always use the vertex representation of the points in the NNG, so that only vertices may be copied and duplicated. This results on a search engine defined over the vertices of the NNG rather than the points themselves. This also explains why the search engine is templated by a distance functor between vertices. This distance functor between vertices is defined internally to the module based on the input distance functor between points.

The main options of the module T_Nearest_neighbors_graph_builder_module are:
–num-neighbors int: Target number of neighbors for each vertex.
–distance-range int: Distance range specification.
–nng-sym bool: Symmetric NNG ie connects two vertices iff they are mutual nearest neighbors.
–nng-connected int: Attempt connecting the NNG by iteratively increasing the number of neighbors; halt if NNG is connected, or if the prescribed num of neighbors is reached.
–nng-file int: Skip calculations by loading the NNG from a file.

Examples

Simple builder

This example shows how to build the NNG of 2D points built on 100x100 grid, setting four neighbors per point.

Builder with edge weights

This example performs the same task as previous but with a NNG able to store the distances between pairs of points linked bya nedge in he NNG.