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%"
)
```

# bullseye 🎯

<!-- badges: start -->
[![Lifecycle: experimental](https://img.shields.io/badge/lifecycle-experimental-orange.svg)](https://lifecycle.r-lib.org/articles/stages.html#experimental)
<!-- badges: end -->

The goal of bullseye is to make it easy to build and serve point-in-polygon queries quickly. Under the hood, it uses the great new packages [geoarrow](https://paleolimbot.github.io/geoarrow/) and [rsgeo](https://rsgeo.josiahparry.com/).

## Installation

You can install the development version of bullseye like so:

``` r
remotes::install_github("mjbroerman/bullseye)
```

## Example

Given an address, the US Census free API service will assign coordinates and FIPS code to it. [tidygeocoder](https://jessecambon.github.io/tidygeocoder/) will help.

In medical research, however, sharing personal identifying information (PII) with third-parties is not allowed. [Nominatim](https://github.com/mediagis/nominatim-docker), powered by OpenStreetMap will assign coordinates for you. For the FIPS codes, `bullseye` will help.

Currently `bullseye` can only build from census resources. The plan is to expand this arbitrary directories containing geometries. 

Here we retrieve Alabama census block groups.

```{r}
library(bullseye)
library(geoarrow)
library(dplyr)


# create db
poly_db_name <- "test_cen.parquet"
main_pipeline(base_url = "https://www2.census.gov/geo/tiger/TIGER2021/BG/",
              filename = poly_db_name,  
              n_limit = 2,
              save = FALSE) # default is TRUE, but vignettes disallow saving.
```

Once built, we can query.

```{r}
# simulate points
data("al_coord")
al_coord |> head()

# load db
filepath <- system.file("extdata", poly_db_name, package = "bullseye")
test_db <- geoarrow::read_geoparquet_sf(filepath)

# query db
res <- combined_spatial_join(pts_sf = al_coord,
                      polys_sf = test_db,
                      prefilter_col = "STATEFP", 
                      return_col = "GEOID")

res
```

If a point is not in the polygon database, an `NA` is returned. 

```{r plot, fig.width=8, fig.height=8}
library(ggplot2)

res |> 
  ggplot(aes(color = is.na(GEOID))) +
  geom_sf() +
  theme_minimal()

# whoops is the join working?

ids <- res |> 
  select(GEOID) |> 
  count(GEOID, sort = TRUE) |> 
  slice(7:10) |> 
  pull(GEOID)

res |> 
  filter(GEOID %in% ids) |> 
  ggplot(aes(color = GEOID)) +
  geom_sf() +
  theme_minimal()


```

## API

Do this as an API.

TODO: issue is that `call_that` generated API can't find the `plumber.R` But API works. 

```{r eval=FALSE}
library(callthat)
library(httr2)

api_conn <- call_that_plumber_start(
  system.file("plumber/sample-api", package = "bullseye")
)

df <- data.frame(
  id = c(1, 2),
  lat = c(31.58037, 33.98386),
  lng = c(-87.51496, -86.36208)
)

# Create and tailor the request

# req <- request(api_conn) |>
#   req_method("POST") |>
#   req_body_json(data = df) |>
#   req_headers("Content-Type" = "application/json")

# this does the above, but with call_that
post_coord <- call_that_api_post(
      api_conn, 
      endpoint = "compute", 
      body = jsonlite::toJSON(df)
)



# Perform the request

# req |>
#   req_perform() |>
#   resp_body_json()

post_coord |> 
  resp_body_json()

call_that_plumber_stop(api_conn)
```

## Deploy

But that's not all! `bullseye` comes with a Dockerfile. So just navigate to the project folder, and build and run. 

```
docker build -t bullseye_image .
docker run --rm -p 8000:8000 bullseye_image
```