README.Rmd

---
output: github_document
---

<!-- README.md is generated from README.Rmd. Please edit that file -->

```{r, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>",
  fig.path = "man/figures/README-",
  out.width = "100%"
)
```

# h3o

<!-- badges: start -->
[![R-CMD-check](https://github.com/JosiahParry/h3o/actions/workflows/R-CMD-check.yaml/badge.svg)](https://github.com/JosiahParry/h3o/actions/workflows/R-CMD-check.yaml)
<!-- badges: end -->

h3o is a system-dependency free package to interact with the H3 Geospatial Indexing system by Uber. h3o utilizes the Rust library h3o with is a pure rust implementation of H3 and does not link or use Uber's H3 C library. h3o R interface is powered by [extendr](https://extendr.github.io/) and should be able to compile on any machine. 

## Installation

You can install the development version of h3o from [GitHub](https://github.com/) with:

``` r
# install.packages("remotes")
remotes::install_github("JosiahParry/h3o")
```

## Example

To illustrate the basic usage, we can first create an sf object of random points. 

```{r}
pnts <- tibble::tibble(
  x = runif(100, -5, 10),
  y = runif(100, 40, 50)
) |> 
  sf::st_as_sf(
    coords = c("x", "y"), 
    crs = 4326
  )

```

h3o utilizes vctrs to create H3 class vectors so that they can work seemlessly within
a tidyverse workflow. 

h3o is intended to work with the sf package for geometric operations. 
H3 vectors can be created from `POINT` geometry columns (`sfc` objects).

```{r example}
library(h3o)

pnts |> 
  dplyr::mutate(h3 = h3_from_points(geometry, 5))

```
Additionally, H3 vectors also have an `st_as_sfc()` method which lets us convert vectors of H3 cell indexes into `POLYGON`s. 

```{r}
h3_cells <- pnts |> 
  dplyr::mutate(
    h3 = h3_from_points(geometry, 4),
    # replace geometry
    geometry = sf::st_as_sfc(h3)
    )

# plot the hexagons
plot(sf::st_geometry(h3_cells))
```

H3 cell centroids can be returned using `h3_to_points()`. If `sf` is avilable the results will
be returned as an `sfc` (sf column) object. Otherwise it will return a list of `sfg` (sf geometries). 

```{r}
# fetch h3 column
h3s <- h3_cells$h3

# get there centers
h3_centers <- h3_to_points(h3s) 

# plot the hexagons with the centers
plot(sf::st_geometry(h3_cells))
plot(h3_centers, pch = 16, add = TRUE, col = "black")
```


## sf compatibility

h3o was designed with sf in mind. H3 is a geospatial indexing system so it is important to be able to go back and from from H3 and sf objects. H3 object can be created from sfc objects and vice versa.sfc objects can also be created using the `sf::sf_as_sfc()` method for `H3` or `H3Edge` vectors.

`H3Edge` vectors represent the boundaries of H3 cells. They can be created with `h3_edges()`, `h3_shared_edge_pairwise()`, and `h3_shared_edge_sparse()`.

```{r}
cell_edges <- h3_edges(h3s[1:3])
cell_edges
```

We've created a list of each cell's edges. We can flatten them using `flatten_edges()`.

```{r}
cell_edges <- flatten_edges(cell_edges)
cell_edges
```

These can be cast to sfc objects using its `st_as_sfc()` method.

```{r}
sf::st_as_sfc(cell_edges)
```

Additionally, you can get the vertexes of H3 cell indexes using `h3_to_vertexes()` which returns an `sfc_MULTIPOINT`.

```{r}
h3_to_vertexes(h3s)
```


## Bench marks: 

Since h3o is written in Rust, it is very fast. 

Creating polygons 

```{r}
h3_strs <- as.character(h3s)
bench::mark(
  h3o = sf::st_as_sfc(h3s),
  h3jsr = h3jsr::cell_to_polygon(h3_strs)
)
```

Converting points to cells

```{r}
bench::mark(
  h3o = h3_from_points(pnts$geometry, 3),
  h3jsr = h3jsr::point_to_cell(pnts$geometry, 3),
  check = FALSE
)
```

Retrieve edges

```{r}
bench::mark(
  h3o = h3_edges(h3s),
  h3jsr = h3jsr::get_udedges(h3_strs),
  check = FALSE
)
```

Get origins and destinations from edges.

```{r}
# get edges for a single location
eds <- h3_edges(h3s[1])[[1]]
# strings for h3jsr
eds_str <- as.character(eds)

bench::mark(
  h3o = h3_edge_cells(eds),
  h3jsr = h3jsr::get_udends(eds_str),
  check = FALSE
)
```