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 = "#>",
  message = FALSE,
  warning = FALSE,
  fig.path = "man/figures/README-",
  out.width = "100%"
)
```

# overtureR <a href="https://arthurgailes.github.io/overtureR/"><img src="man/figures/logo.png" align="right" height="139" alt="overtureR website" /></a>


<!-- badges: start -->
[![Lifecycle: experimental](https://img.shields.io/badge/lifecycle-stable-green.svg)](https://lifecycle.r-lib.org/articles/stages.html#stable)
[![CRAN status](https://www.r-pkg.org/badges/version/overtureR)](https://CRAN.R-project.org/package=overtureR)
[![R-CMD-check](https://github.com/arthurgailes/overtureR/actions/workflows/R-CMD-check.yaml/badge.svg)](https://github.com/arthurgailes/overtureR/actions/workflows/R-CMD-check.yaml)
[![Codecov test coverage](https://codecov.io/gh/arthurgailes/overtureR/branch/master/graph/badge.svg)](https://app.codecov.io/gh/arthurgailes/overtureR?branch=master)
<!-- badges: end -->

## Installation

```{r eval=FALSE}
install.packages("overtureR")

# devtools::install_github("arthurgailes/overtureR")
```

## Key Features

* Query global [Overture Maps](https://overturemaps.org/) data directly in R
* Conduct analysis on massive dataset without loading into memory using  [dbplyr's](https://dbplyr.tidyverse.org/) lazy evaluation
* Seamless `dplyr` and `sf` integration
* Merge with your local `sf` data within `duckdb` or with `sf`
* Local downloading for offline use and performance

## Usage

Replicating `duckdb` examples from the [Overture docs](https://docs.overturemaps.org/getting-data/duckdb/)

```{r ggtheme, include=FALSE}
library(ggplot2)
map_theme <- theme_minimal() +
  theme(
    plot.title = element_text(face = "bold", size = 16, hjust = 0.5),
    plot.subtitle = element_text(size = 12, hjust = 0.5, margin = margin(b = 20)),
    plot.caption = element_text(size = 8, margin = margin(t = 10)),
    legend.position = "none",
    legend.title = element_text(face = "bold"),
    legend.text = element_blank(),
    panel.grid = element_blank(),
    axis.text = element_blank(),
    axis.title = element_blank(),
    plot.background = element_rect(fill = "grey90", color = NA), 
    panel.background = element_rect(fill = "grey90", color = NA), 
    legend.background = element_rect(fill = "grey90", color = NA),
    panel.border = element_blank()
  )

theme_set(map_theme)
```


```{r counties, warning=FALSE}
library(overtureR)
library(dplyr)
library(ggplot2)

counties <- open_curtain("division_area") |>
  # in R, filtering on variables must come before removing them via select
  filter(subtype == "county" & country == "US" & region == "US-PA") |>
  transmute(
    id,
    division_id,
    primary = names$primary,
    geometry
  ) |>
  collect()

# Plot the results
ggplot(counties) +
  geom_sf(aes(fill = as.numeric(sf::st_area(geometry))), color = "white", size = 0.2) +
  viridis::scale_fill_viridis(option = "plasma", guide = FALSE) +
  labs(
    title = "Pennsylvania Counties by Area",
    caption = "Data: Overture Maps"
  ) 
```

```{r mountains}
library(overtureR)
library(dplyr)

# lazily load the full `mountains` dataset
mountains <- open_curtain(type = "*", theme = "places") |>
  transmute(
    id,
    primary_name = names$primary,
    x = bbox$xmin,
    y = bbox$ymin,
    main_category = categories$primary,
    primary_source = sources[[1]]$dataset,
    confidence,
    geometry # currently no duckdb spatial implementation
  ) |>
  filter(main_category == "mountain" & confidence > .90)

head(mountains)
```

## Downloading data locally

The record_overture function allows you to download Overture Maps data to a local directory, maintaining the same partition structure as in S3. This is useful for offline analysis or when you need to work with the data repeatedly. Here's an example:

```{r record}
library(overtureR)
library(ggplot2)
library(dplyr)
library(rayshader)

# Define a bounding box for New York City
broadway <- c(xmin = -73.9901, ymin = 40.755488, xmax = -73.98, ymax = 40.76206)

# Download building data for NYC to a local directory
local_buildings <- open_curtain("building", broadway) |> 
  record_overture(output_dir = tempdir(), overwrite = TRUE)

# The downloaded data is returned as a `dbplyr` object, same as the original (but faster!)
broadway_buildings <- local_buildings |> 
  filter(!is.na(height)) |> 
  mutate(height = round(height)) |> 
  collect() 

p <- ggplot(broadway_buildings) +
  geom_sf(aes(fill = height)) +
  scale_fill_distiller(palette = "Oranges", direction = 1) +
  # guides(fill = FALSE) +
  labs(title = "Buildings on Broadway", caption = "Data: Overture Maps", fill = "")

# Convert to 3D and render
plot_gg(
  p,
  multicore = TRUE,
  width = 6, height = 5, scale = 250,
  windowsize = c(1032, 860),
  zoom = 0.55, 
  phi = 40, theta = 0,
  solid = FALSE,
  offset_edges = TRUE,
  sunangle = 75
)

render_snapshot(clear=TRUE)

```


## Roadmap

- Read pmtiles
- Add partition, chunking to record_overture
- Add beta/alpha datasets
- Add mapping vignette
- Add performance vignette
- Download overture files via open_curtain