# PH-tree

The PH-tree is a tree data structure used for spatial indexing of multi-dimensional data (keys) such as geographical coordinates, points, feature vectors, rectangles or bounding boxes.
The PH-tree is space partitioning index with a structure similar to that of a quadtree or octree. However, unlike quadtrees, it uses a splitting policy based on tries and similar to Crit bit trees that is based on the bit-representation of the keys. The bit-based splitting policy, when combined with the use of different internal representations for nodes, provides scalability with high-dimensional data. The bit-representation splitting policy also imposes a maximum depth, thus avoiding degenerated trees and the need for rebalancing.

## Overview

The basic PH-tree is a spatial index that maps keys, which are d-dimensional vectors with integers, to user defined values. The PH-tree is a multi-dimensional generalization of a Crit bit tree in the sense that a Crit bit tree is equivalent to a PH-tree with $1$-dimensional keys. Like the Crit bit tree, and unlike most other spatial indexes, the PH-tree is a map rather than a multimap.
A d-dimensional PH-tree is a tree of nodes where each node partitions space by subdividing it into $2^{d}$ quadrants (see below for how potentially large nodes scales with high dimensional data). Each quadrant contains at most one entry, either a key-value pair (leaf quadrant) or a key-subnode pair. For a key-subnode pair, the key represents the center of the subnode. The key is also the common prefix (bit-representation) of all keys in the subnode and its child subnodes. Each node has at least two entries, otherwise it is merged with the parent node.
Some other structural properties of PH-trees are:
* They are $2^{n}$-ary trees.
* They are inherently unbalanced but imbalance is limited due to their depth being limited to the bit width of the keys, e.g. to 32 for a $d$-dimensional key with 32bit integers.
* Insertion or removal operations cause exactly one node to be modified and potentially a second node to be added or removed. This can be useful for concurrent implementations. This also means little variation in modification cost.
* Their structure is independent from insertion/removal order.

## Splitting strategy

Similar to most quadtrees, the PH-tree is a hierarchy of nodes where every node splits the space in all d dimensions. Thus, a node can have up to $2^{d}$ subnodes, one for each quadrant.

### Quadrant numbering

The PH-tree uses the bits of the multi-dimensional keys to determine their position in the tree. All keys that have the same leading bits are stored in the same branch of the tree.
For example, in a node at level L, to determine the quadrant where a key should be inserted (or removed or looked up), it looks at the L's bit of each dimension of the key. For a 3D node with 8 quadrants (forming a cube) the L's bit of the first dimension of the key determines whether the target quadrant is on the left or the right of the cube, the L's bit of the second dimension determines whether it is at the front or the back, and the L's bit of the third dimension determines bottom vs top, see picture.

### 1D example

Example with three 1D keys with 8bit values: $k_{0}=\{1\}_{base\ 10}=\{00000001\}_{base\ 2}$, $k_{1}=\{4\}_{10}=\{00000100\}_{2}$ and $k_{2}=\{35\}_{10}=\{00100011\}_{2}$. Adding $k_{0}$ and $k_{1}$ to an empty tree results in a single node. The two keys first differ in their 6th bit so the node has a level $L=5$ (starting with 0). The node has a 5bit prefix representing the common 5 bits of both keys. The node has two quadrants, each key is stored in one quadrant. Adding a third key $k_{3}$ results in one additional node at $L=2$ with one quadrant containing the original node as subnode and the other quadrant containing the new key $k_{2}$.

### 2D example

With 2D keys every node has $2^{d}=4$ quadrants. The position of the quadrant where a key is stored is extracted from the respective bits of the keys, one bit from each dimension. The four quadrants of the node form a 2D hypercube (quadrants may be empty). The bits that are extracted from the keys form the hypercube address $h$, for $k_{0}\rightarrow h=\{00\}_{2}$ and for $k_{1}\rightarrow h=\{01\}_{2}$. $h$ is effectively the position of the quadrant in the node's hypercube.

## Node structure

The ordering of the entries in a node always follows Z-ordering. Entries in a node can, for example, be stored in fixed size arrays of size $2^{d}$. h is then effectively the array index of a quadrant. This allows lookup, insert and remove with $O(1)$ and there is no need to store h. Space complexity is however $O(2^{d})$ per node, so it is less suitable for high dimensional data.
Another solution is to store entries in a sorted collection, such as dynamic arrays and/or B-trees. This slows down lookup operations to $O(\log {n_{node\_entries}})$ but reduces memory consumption to $O(n_{node\_entries})$.
The original implementation aimed for minimal memory consumption by switching between fixed and dynamic array representation depending on which uses less memory. Other implementations do not switch dynamically but use fixed arrays for $d\lesssim 4$, dynamic arrays for $d\lesssim 8$ and B-trees for high dimensional data.

## Operations

Lookup, insertion and removal operations all work very similar: find the correct node, then perform the operation on the node. Window queries and k-nearest-neighbor searches are more complex.

### Lookup

The Lookup operation determines whether a key exists in the tree. It walks down the tree and checks every node whether it contains a candidate subnode or a user value that matches the key.

### Insert

The Insert operation inserts a new key-value pair into the tree unless they key already exists. The operation traverses the tree like the Lookup function and then inserts the key into the node. There are several cases to consider:
* The quadrant is empty and we can simply insert a new entry into the quadrant and return.
* The quadrant contains a user entry with a key that is identical to the new entry. One way to deal with such a collision is to return a flag that indicates failed insertion. If the tree is implemented as multi-map with a collection as the node's entry, the new value is added to that collection.
* The quadrant contains an entry (user entry or subnode entry) with a different key. This case requires replacing the existing entry with a new subnode that holds the old and the new entry.

### Remove

Removal works inversely to insertion, with the additional constraint that any subnode has to be removed if less than two entries remain. The remaining entry is moved to the parent node.

### Window queries

Window queries are queries that return all keys that lie inside a rectangular axis-aligned hyperbox. They can be defined to be two d-dimensional points $min$ and $max$ that represent the "lower left" and "upper right" corners of the query box. A trivial implementation traverses all entries in a node (starting with the root node) and if an entry matches it either adds it to the result list (if it is a user entry) or recursively traverses it (if it is a subnode).
In order to accurately estimate query time complexity the analysis needs to include the dimensionality $d$. Traversing and comparing all $n_{node\_entries}$ entries in a node has a time complexity of $O(d\cdot n_{node\_entries})$ because each comparison of $d$-dimensional key with $min/max$ takes $O(d)$ time. Since nodes can have up to $2^{d}$ entries, this does not scale well with increasing dimensionality $d$. There are various ways how this approach can be improved by making use of the hypercube address h.

#### Min h & max h

The idea is to find minimum and maximum values for the quadrant's addresses $h$ such that the search can avoid some quadrants that do not overlap with the query box. Let $C$ be the center of a node (this is equal to the node's prefix) and $h_{min}$ and $h_{max}$ be two bit strings with $d$ bits each. Also, let subscript $i$ with $0\leq i<d$ indicate the $i$'s bit of $h_{min}$ and $h_{max}$ and the $i$'th dimension of $min$, $max$ and $C$.
Let $h_{min,i}=(min_{i}\leq C_{i})$ and $h_{max,i}=(max_{i}\geq C_{i})$. $h_{min}$ then has a `$1$` for every dimension where the "lower" half of the node and all quadrants in it does not overlap with the query box. Similarly, $h_{min}$ has a `$0$` for every dimension where the "upper" half does not overlap with the query box.
$h_{min}$ and $h_{max}$ then present the lowest and highest $h$ in a node that need to be traversed. Quadrants with $h<h_{min}$ or $h>h_{max}$ do not intersect with the query box. A proof is available in. With this, the above query function can be improved to:
Calculating $h_{min}$ and $h_{max}$ is $O(2d)=O(d)$. Depending on the distribution of the occupied quadrants in a node this approach will allow avoiding anywhere from no to almost all key comparisons. This reduces the average traversal time but the resulting complexity is still $O(d+d\cdot n_{node\_entries})$.

#### Check quadrants for overlap with query box

Between $h_{min}$ and $h_{max}$ there can still be quadrants that do not overlap with the query box. Idea: $h_{min}$ and $h_{max}$ each have one bit for every dimensions that indicates whether the query box overlaps with the lower/upper half of a node in that dimension. This can be used to quickly check whether a quadrant $h$ overlaps with the query box without having to compare $d$-dimensional keys: a quadrant $h$ overlaps with the query box if for every `$0$` bit in $h$ there is a corresponding `$0$` bit in $h_{min}$ and for every `$1$` bit in $h$ there is a corresponding `$1$` bit in $h_{max}$. On a CPU with 64bit registers it is thus possible to check for overlap of up to $64$-dimensional keys in $O(1)$.
The resulting time complexity is $O(d+n_{node\_entries})$ compared to the $O(d\cdot n_{node\_entries})$ of the full iteration.

#### Traverse quadrants that overlap with query box

For higher dimensions with larger nodes it is also possible to avoid iterating through all $h$ and instead directly calculate the next higher $h$ that overlaps with the query box. The first step puts `$1$`-bits into a given $h_{input}$ for all quadrants that have no overlap with the query box. The second step increments the adapted $h$ and the added `$1$`-bits trigger an overflow so that the non-overlapping quadrants are skipped. The last step removes all the undesirable bits used for triggering the overflow. The logic is described in detail in. The calculation works as follows:
Again, for $d\leq 64$ this can be done on most CPUs in $O(1)$. The resulting time complexity for traversing a node is $O(d+n_{overlapping\_quadrants})$. This works best if most of the quadrants that overlap with the query box are occupied with an entry.

### k-nearest neighbors

k nearest neighbor searches can be implemented using standard algorithms.

## Floating point keys

The PH-tree can only store integer values. Floating point values can trivially be stored as integers casting them as an integer. However, the authors also propose an approach without loss of precision.

### Lossless conversion

Lossless converting of a floating point value into an integer value (and back) without loss if precision can be achieved by simply interpreting the 32 or 64 bits of the floating point value as an integer (with 32 or 64 bits). Due to the way that IEEE 754 encodes floating point values, the resulting integer values have the same ordering as the original floating point values, at least for positive values. Ordering for negative values can be achieved by inverting the non-sign bits.
Example implementations in Java:
Example implementations in C++:
Encoding (and the inverse decoding) is lossless for all floating point values. The ordering works well in practice, including $\pm \infty$ and $-0.0$. However, the integer representation also turns $NaN$ into a normal comparable value (smaller than infinity), infinities are comparable to each other and $0.0$ is larger than $-0.0$. That means that, for example, a query range $[0.0,10.0]$ will not match a value of $-0.0$. In order to match $-0.0$ the query range needs to be $[-0.0,10.0]$.

## Hyperbox keys

In order to store volumes (axis-aligned hyper-boxes) as keys, implementations typically use corner representation which converts the two $d$-dimensional minimum and maximum corners of a box into a single key with $2d$ dimensions, for example by interleaving them: $k=\{min_{0},max_{0},min_{1},max_{1},...,min_{d-1},max_{d-1}\}$.
This works trivially for lookup, insert and remove operations. Window queries need to be converted from $d$-dimensional vectors to $2d$-dimensional vectors. For example, for a window query that matches all boxes that are completely inside the query box, the query keys are:
$k_{min}=\{min_{0},min_{0},min_{1},min_{1},...,min_{d-1},min_{d-1}\}$
$k_{max}=\{max_{0},max_{0},max_{1},max_{1},...,max_{d-1},max_{d-1}\}$
For a window query operation that matches all boxes that intersect with a query box, the query keys are:
$k_{min}=\{-\infty ,min_{0},-\infty ,min_{1},...,-\infty ,min_{d-1}\}$
$k_{max}=\{max_{0},+\infty ,max_{1},+\infty ,...,max_{d-1},+\infty \}$

## Scalability

In high dimensions with less than $2^{d}$ entries, a PH-tree may have only a single node, effectively “degenerating” into a B-Tree with Z-order curve. The add/remove/lookup operations remain $O(\log {n})$ and window queries can use the quadrant filters. However, this cannot avoid the curse of dimensionality, for high dimensional data with $d=50$ or $d=100$ a PH-tree is only marginally better than a full scan.

## Uses

Research has reported fast add/remove/exact-match operations with large and fast changing datasets. Window queries have been shown to work well especially for small windows or large dataset
The PH-tree is mainly suited for in-memory use. The size of the nodes (number of entries) is fixed while persistent storage tends to benefit from indexes with configurable node size to align node size with page size on disk. This is easier with other spatial indexes, such as R-Trees.

## Implementations

* Java: GitHub repository by original inventor
* C++: GitHub repository by original inventor
* C++: GitHub repository
* C++: GitHub repository