# Chapter 14. Spatial graphs

## 1. Metrics

### 1.1. `igraph_metric_t` — Metric functions for use with spatial computation.

    typedef enum {
        IGRAPH_METRIC_EUCLIDEAN = 0,
        IGRAPH_METRIC_L2 = IGRAPH_METRIC_EUCLIDEAN,
        IGRAPH_METRIC_MANHATTAN = 1,
        IGRAPH_METRIC_L1 = IGRAPH_METRIC_MANHATTAN
    } igraph_metric_t;

Values:

`IGRAPH_METRIC_EUCLIDEAN`: | The Euclidean distance, i.e. L2 metric.
`IGRAPH_METRIC_MANHATTAN`: | The Manhattan distance, i.e. L1 metric.

## 2. Spatial graph generators

### 2.1. `igraph_delaunay_graph` — Computes the Delaunay graph of a spatial point set.

    igraph_error_t igraph_delaunay_graph(igraph_t *graph, const igraph_matrix_t *points);

### Warning

This function is experimental and its signature is not considered final yet. We reserve the right to change the function signature without changing the major version of igraph. Use it at your own risk.

This function constructs the graph corresponding to the Delaunay triangulation of an n-dimensional spatial point set.

The current implementation uses Qhull.

Reference:

Barber, C. Bradford, David P. Dobkin, and Hannu Huhdanpaa. The Quickhull Algorithm for Convex Hulls. ACM Transactions on Mathematical Software 22, no. 4 (1996): 469–83. https://doi.org/10.1145/235815.235821.

Arguments:

`graph`: | A pointer to the graph that will be created.
`points`: | A matrix containing the points that will be used to create the graph. Each row is a point, dimensionality is inferred from the column count. There must not be duplicate points.

Returns:

`` | Error code.

Time complexity: According to Theorem 3.2 in the Qhull paper, O(n log n) for d <= 3 and O(n^floor(d/2) / floor(d/2)!) where n is the number of points and d is the dimensionality of the point set.

### 2.2. `igraph_nearest_neighbor_graph` — Computes the nearest neighbor graph for a spatial point set.

    igraph_error_t igraph_nearest_neighbor_graph(igraph_t *graph,
            const igraph_matrix_t *points,
            igraph_metric_t metric,
            igraph_int_t k,
            igraph_real_t cutoff,
            igraph_bool_t directed);

### Warning

This function is experimental and its signature is not considered final yet. We reserve the right to change the function signature without changing the major version of igraph. Use it at your own risk.

This function constructs the `k` nearest neighbor graph of a given point set. Each point is connected to at most `k` spatial neighbors within a radius of `cutoff`.

Arguments:

`graph`: | A pointer to the graph that will be created.
`points`: | A matrix containing the points that will be used to create the graph. Each row is a point, dimensionality is inferred from the column count.
`metric`: | The distance metric to use. See `igraph_metric_t`.
`k`: | At most how many neighbors will be added for each vertex, set to a negative value to ignore.
`cutoff`: | Maximum distance at which connections will be made, set to a negative value or `IGRAPH_INFINITY` to ignore.
`directed`: | Whether to create a directed graph.

Returns:

`` | Error code.

Time complexity: O(n log(n)) where n is the number of points.

### 2.3. `igraph_gabriel_graph` — The Gabriel graph of a point set.

    igraph_error_t igraph_gabriel_graph(igraph_t *graph, const igraph_matrix_t *points);

### Warning

This function is experimental and its signature is not considered final yet. We reserve the right to change the function signature without changing the major version of igraph. Use it at your own risk.

In the Gabriel graph of a point set, two points A and B are connected if there is no other point C within the closed ball of which AB is a diameter. The Gabriel graph is connected, and in 2D it is planar. igraph supports computing the Gabriel graph of arbitrary dimensional point sets.

The Gabriel graph is a special case of lune-based and circle-based β-skeletons with `β=1`.

Arguments:

`graph`: | A pointer to the graph to be created.
`points`: | The point set that will be used. Each row is a point, dimensionality is inferred from column count.

Returns:

`` | Error Code.

See also:

`` | The Gabriel graph is a special case of `igraph_lune_beta_skeleton()` and `igraph_circle_beta_skeleton()` where `β = 1`.

Time Complexity: Around O(n^floor(d/2) log n), where n is the number of points and d is the dimensionality of the point set.

### 2.4. `igraph_relative_neighborhood_graph` — The relative neighborhood graph of a point set.

    igraph_error_t igraph_relative_neighborhood_graph(igraph_t *graph, const igraph_matrix_t *points);

### Warning

This function is experimental and its signature is not considered final yet. We reserve the right to change the function signature without changing the major version of igraph. Use it at your own risk.

The relative neighborhood graph is constructed from a set of points in space. Two points A and B are connected if and only if there is no other point C so that AC < AB and BC < AB, with the inequalities being strict.

Most authors define the relative neighborhood graph to coincide with a lune-based β-skeleton for `β = 2`. In igraph, there is a subtle difference: the `β = 2` skeleton connects points A and B when there is no point C so that AC <= AB and BC <= AB. Therefore, three points forming an equilateral triangle are connected in the relative neighborhood graph, but disconnected in the `β = 2` skeleton.

With these definitions, the relative neighborhood graph is always connected, while the `β = 2` skeleton is always triangle-free.

Arguments:

`graph`: | A pointer to the graph that will be created.
`points`: | The point set that will be used, each row is a point. Dimensionality is inferred from the column number.

Returns:

`` | Error code.

See also:

`` | `igraph_lune_beta_skeleton()` to compute the lune based β-skeleton for `β = 2` or other β values.

Time Complexity: Around O(n^floor(d/2) log n), where n is the number of points and d is the dimensionality of the point set.

### 2.5. `igraph_lune_beta_skeleton` — The lune based β-skeleton of a spatial point set.

    igraph_error_t igraph_lune_beta_skeleton(igraph_t *graph, const igraph_matrix_t *points, igraph_real_t beta);

### Warning

This function is experimental and its signature is not considered final yet. We reserve the right to change the function signature without changing the major version of igraph. Use it at your own risk.

This function constructs the lune-based β-skeleton of an n-dimensional spatial point set.

A larger β results in a larger region, and a sparser graph. Values of β < 1 are only supported in 2D, and are considerably slower.

The Gabriel graph is a special case of beta skeleton where `β = 1`.

The Relative Neighborhood graph is a special case of beta skeleton where β approaches

Arguments:

`graph`: | A pointer to the graph that will be created.
`points`: | A matrix containing the points that will be used to create the graph. Each row is a point, dimensionality is inferred from the column count.

Returns:

`` | Error code.

Time Complexity: Around O(n^floor(d/2) log n), where n is the number of points and d is the dimensionality of the point set.

### 2.6. `igraph_circle_beta_skeleton` — The circle based β-skeleton of a 2D spatial point set.

    igraph_error_t igraph_circle_beta_skeleton(igraph_t *graph, const igraph_matrix_t *points, igraph_real_t beta);

### Warning

This function is experimental and its signature is not considered final yet. We reserve the right to change the function signature without changing the major version of igraph. Use it at your own risk.

This function constructs the circle based β-skeleton of a 2D spatial point set.

A larger `beta` value results in a larger region, and a sparser graph. Values of beta < 1 are considerably slower

Arguments:

`graph`: | A pointer to the graph that will be created.
`points`: | An n-by-2 matrix containing the points that will be used to create the graph. Each row is a point.
`beta`: | A positive real value used to parameterize the graph.

Returns:

`` | Error code.

Time Complexity: Around O(n^floor(d/2) log n), where n is the number of points and d is the dimensionality of the point set.

### 2.7. `igraph_beta_weighted_gabriel_graph` — A Gabriel graph, with edges weighted by the β value at which it disappears.

    igraph_error_t igraph_beta_weighted_gabriel_graph(
        igraph_t *graph,
        igraph_vector_t *weights,
        const igraph_matrix_t *points,
        igraph_real_t max_beta);

### Warning

This function is experimental and its signature is not considered final yet. We reserve the right to change the function signature without changing the major version of igraph. Use it at your own risk.

This function generates a Gabriel graph, and for each edge of this graph it computes the threshold β value at which the edge ceases to be part of the lune-based β-skeleton. For edges that continue to be part of β-skeletons for arbitrarily large β, `IGRAPH_INFINITΥ` is returned.

The `max_beta` cutoff parameter controls the largest β value to consider For edges that persist above this β value, `IGRAPH_INFINITΥ` is returned. This parameter serves to improve performance: the smaller this cutoff, the faster the computation. Pass `IGRAPH_INFINITY` to use no cutoff.

Arguments:

`graph`: | A pointer to the graph that will be created.
`weights`: | Will contain the edge weights corresponding to the edge indices from the graph.
`points`: | A matrix containing the points that will be used. Each row is a point, dimensionality is inferred from the column count. There must be no duplicate points.
`max_beta`: | Maximum value of beta to search to, higher values will be represented as `IGRAPH_INFINITY`.

Returns:

`` | Error code.

See also:

`` | `igraph_lune_beta_skeleton()` or `igraph_circle_beta_skeleton()` to generate a graph with a given value of beta; `igraph_gabriel_graph()` to only generate a Gabriel graph, without edge weights.

Time Complexity: Around O(n^floor(d/2) log n), where n is the number of points and d is the dimensionality of the point set. Though large values of max_beta can cause long run times if there are edges that disappear only at large betas.

## 3. Properties of spatial graphs

### 3.1. `igraph_spatial_edge_lengths` — Edge lengths based on spatial vertex coordinates.

    igraph_error_t igraph_spatial_edge_lengths(
            const igraph_t *graph,
            igraph_vector_t *lengths,
            const igraph_matrix_t *points,
            igraph_metric_t metric);

### Warning

This function is experimental and its signature is not considered final yet. We reserve the right to change the function signature without changing the major version of igraph. Use it at your own risk.

The length of each edge is computed based on spatial coordinates. The length can be employed by several igraph functions, such as `igraph_voronoi()`, `igraph_betweenness()`, `igraph_closeness()` and others.

Arguments:

`graph`: | The graph whose edge lengths are to be computed.
`lengths`: | An initialized vector. Length will be stored here, in the order of edge IDs. It will be resized as needed.
`points`: | A matrix of vertex coordinates. Each row contains the coordinates of the corresponding vertex, in the order of vertex IDs. Arbitrary dimensional point sets are supported.
`metric`: | The distance metric to use. See `igraph_metric_t` for valid values.

Returns:

`` | Error code.

See also:

`` | `igraph_nearest_neighbor_graph()` computes a k nearest neighbor graph and `igraph_delaunay_graph()` computes a Delaunay graph based on a set of spatial points.

Time complexity: O(|E| d) where |E| is the number of edges and d is the dimensionality of the point set.

## 4. Non-graph related spatial processing

### 4.1. `igraph_convex_hull_2d` — Determines the convex hull of a given set of points in the 2D plane.

    igraph_error_t igraph_convex_hull_2d(
            const igraph_matrix_t *data,
            igraph_vector_int_t *resverts,
            igraph_matrix_t *rescoords);

The convex hull is determined by the Graham scan algorithm. See the following reference for details:

Thomas H. Cormen, Charles E. Leiserson, Ronald L. Rivest, and Clifford Stein. Introduction to Algorithms, Second Edition. MIT Press and McGraw-Hill, 2001. ISBN 0262032937. Pages 949-955 of section 33.3: Finding the convex hull.

Arguments:

`data`: | vector containing the coordinates. The length of the vector must be even, since it contains X-Y coordinate pairs.
`resverts`: | the vector containing the result, e.g. the vector of vertex indices used as the corners of the convex hull. Supply `NULL` here if you are only interested in the coordinates of the convex hull corners.
`rescoords`: | the matrix containing the coordinates of the selected corner vertices. Supply `NULL` here if you are only interested in the vertex indices.

Returns:

`` | Error code: `IGRAPH_ENOMEM`: not enough memory

Time complexity: O(n log(n)) where n is the number of vertices.