index.qmd

---
format: gfm
bibliography: inst/REFERENCES.bib
link-citations: true
nocite: '@*'
default-image-extension: ''
tbl-cap-location: bottom
knitr:
  opts_chunk:
    collapse: true
    comment: "#>"
    warning: false
    message: false
    dev: "ragg_png"
    tidy: "styler"
    fig.path: "man/figures/README-"
    dpi: 150
    out.width: "100%"
---

<!-- index.md is generated from index.qmd. Please edit that file -->

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

<!-- badges: start -->

[![CRAN-status](https://www.r-pkg.org/badges/version/geobounds)](https://CRAN.R-project.org/package=geobounds)
[![CRAN-results](https://badges.cranchecks.info/worst/geobounds.svg)](https://cran.r-project.org/web/checks/check_results_geobounds.html)
[![Downloads](https://cranlogs.r-pkg.org/badges/geobounds)](https://CRAN.R-project.org/package=geobounds)
[![r-universe](https://dieghernan.r-universe.dev/badges/geobounds)](https://dieghernan.r-universe.dev/geobounds)
[![R-CMD-check](https://github.com/dieghernan/geobounds/actions/workflows/check-full.yaml/badge.svg)](https://github.com/dieghernan/geobounds/actions/workflows/check-full.yaml)
[![codecov](https://codecov.io/gh/dieghernan/geobounds/graph/badge.svg)](https://app.codecov.io/gh/dieghernan/geobounds)
[![CodeFactor](https://www.codefactor.io/repository/github/dieghernan/geobounds/badge)](https://www.codefactor.io/repository/github/dieghernan/geobounds)
[![DOI](https://img.shields.io/badge/DOI-%2010.32614/CRAN.package.geobounds%20-blue)](https://doi.org/10.32614/CRAN.package.geobounds)
[![Project Status: Active - The project has reached a stable, usable state and
is being actively
developed.](https://www.repostatus.org/badges/latest/active.svg)](https://www.repostatus.org/#active)

<!-- badges: end -->

## Why this package?

The **geobounds** package provides an **R**-friendly interface for downloading
administrative boundaries from
[**geoBoundaries**](https://www.geoboundaries.org/), the Global Database of
Political Administrative Boundaries. With **geobounds**, you can:

- Download individual country boundaries and global composite boundaries from
  **geoBoundaries**.
- Use **tidyverse** and **sf** workflows in **R** to map, analyze and join
  administrative boundaries with your own data.
- Work in an open-data context where attribution to **geoBoundaries** is
  required.

In short, if you work with administrative boundaries in **R**, **geobounds**
simplifies downloading, cache management and integration with spatial data
workflows.

```{=html}
<div class="callout callout-style-default callout-important callout-titled">
<div class="callout-header d-flex align-content-center">
<div class="callout-icon-container"><i class="callout-icon"></i></div>
<div class="callout-title-container flex-fill">Important</div>
</div>
<div class="callout-body-container callout-body">
<p><a href="https://www.geoboundaries.org/index.html#usage" class="external-link">Attribution</a> is required when sharing
<strong>geoBoundaries</strong> boundaries or derived products.</p>
</div>
</div>
```

## Installation

Install **geobounds** from
[**CRAN**](https://CRAN.R-project.org/package=geobounds):

```{r}
#| eval: false
install.packages("geobounds")
```

::: pkgdown-devel
Check the documentation for the development version at
<https://dieghernan.github.io/geobounds/dev/>

You can install the development version of **geobounds** with:

```{r}
#| eval: false
# install.packages("pak")
pak::pak("dieghernan/geobounds")
```

Alternatively, you can install **geobounds** from
[**r-universe**](https://dieghernan.r-universe.dev/geobounds):

```{r}
#| eval: false
# Install geobounds.
install.packages(
  "geobounds",
  repos = c(
    "https://dieghernan.r-universe.dev",
    "https://cloud.r-project.org"
  )
)
```
:::

## Example usage

```{r}
#| label: simple_plot
#| fig-cap: "ADM1, ADM2 and ADM3 boundaries for Sri Lanka."
library(geobounds)

sri_lanka_adm1 <- gb_get_adm1("Sri Lanka")
sri_lanka_adm2 <- gb_get_adm2("Sri Lanka")
sri_lanka_adm3 <- gb_get_adm3("Sri Lanka")

library(sf)
library(dplyr)

library(ggplot2)

ggplot(sri_lanka_adm3) +
  geom_sf(fill = "#DFDFDF", color = "white") +
  geom_sf(data = sri_lanka_adm2, fill = NA, color = "#F0B323") +
  geom_sf(data = sri_lanka_adm1, fill = NA, color = "black") +
  labs(
    caption = paste(
      "Sources: geoBoundaries, OpenStreetMap and Wambacher,",
      "license: ODbL 1.0"
    )
  ) +
  theme_void()
```

## Release types

**geoBoundaries** provides three release types with different data sources,
validation processes and licensing terms:

- **gbOpen**: Openly licensed boundaries suitable for most uses. The original
  license varies by boundary and may include ODbL, CC BY or CC BY-SA terms.
- **gbHumanitarian**: Boundaries mirrored from UN OCHA. Check the current
  metadata for the applicable source, license and attribution terms.
- **gbAuthoritative**: Boundaries mirrored from UN SALB and verified through
  in-country processes. These boundaries are restricted to non-commercial use.

Use the `release_type` argument to request a specific release type, for example,
`gb_get_adm1("Sri Lanka", release_type = "gbHumanitarian")`.

For coverage and boundary metadata by release type, see the **geobounds**
articles.

## Advanced usage

Map the highest available ADM level in **geoBoundaries** by country:

```{r}
#| label: map-coverage
#| fig-cap: "Highest available gbOpen ADM level by country."
library(geobounds)
library(ggplot2)
library(dplyr)

world <- gb_get_world()
max_lvl <- gb_get_max_adm_lvl(release_type = "gbOpen")

world_max <- world |>
  mutate(boundaryISO = shapeGroup) |>
  left_join(max_lvl) |>
  mutate(max_lvl = factor(maxBoundaryType, levels = 0:5))

pal <- c("#0e221b", "#0f4a38", "#0b6e4f", "#719384", "#b9975a", "#936e28")
names(pal) <- levels(world_max$max_lvl)

ggplot(world_max) +
  geom_sf(fill = "#e5e5e5", color = "#e5e5e5") +
  geom_sf(aes(fill = max_lvl), color = "transparent") +
  scale_fill_manual(values = pal, na.translate = FALSE, drop = FALSE) +
  guides(fill = guide_legend(direction = "horizontal", nrow = 1)) +
  coord_sf(expand = TRUE, crs = "+proj=robin") +
  theme_void() +
  theme(
    plot.background = element_rect(fill = "white", color = NA),
    text = element_text(family = "sans", face = "bold"),
    legend.position = "bottom",
    legend.title.position = "top",
    legend.title = element_text(size = rel(0.75), face = "plain"),
    legend.text = element_text(size = rel(1)),
    legend.text.position = "right",
    legend.key.height = unit(1, "line"),
    legend.key.width = unit(1, "line"),
    plot.caption = element_text(
      size = rel(0.7),
      margin = margin(r = 4)
    )
  ) +
  labs(
    fill = "gbOpen: Highest available ADM level",
    caption = "Source: geoBoundaries (CGAZ and gbOpen metadata)"
  )
```

## Documentation and resources

- Visit the **pkgdown** site for full documentation:
  <https://dieghernan.github.io/geobounds/>
- Articles on **geoBoundaries** release types:
  - [gbOpen](https://dieghernan.github.io/geobounds/articles/gbopen.html)
  - [gbHumanitarian](https://dieghernan.github.io/geobounds/articles/gbhumanitarian.html)
  - [gbAuthoritative](https://dieghernan.github.io/geobounds/articles/gbauthoritative.html)
- Explore the **geoBoundaries** homepage: <https://www.geoboundaries.org/>
- Read the original paper describing the **geoBoundaries** dataset
  [@10.1371/journal.pone.0231866].
- Report issues or contribute on
  [**GitHub**](https://github.com/dieghernan/geobounds).

## License

The **geobounds** software is released under the [MIT
license](https://opensource.org/license/mit). This license does not cover
boundaries downloaded through the package or figures derived from those
boundaries.

Each boundary retains the original license reported by **geoBoundaries**. Before
reusing or redistributing boundaries, use `gb_get_metadata()` to check
`boundaryLicense`, `licenseDetail`, `licenseSource`, `boundarySource` and
`boundarySourceURL`. Attribute **geoBoundaries** and the original providers,
include the applicable license and indicate modifications when required.
`gbAuthoritative` contains UN SALB boundaries restricted to non-commercial use.

## Acknowledgments

- Thanks to the **geoBoundaries** team and the [William & Mary
  geoLab](https://sites.google.com/view/wmgeolab/) for creating and maintaining
  the dataset.
- Thanks to the **R** package community and all **geobounds** contributors.
- If you use **geobounds** with **geoBoundaries** boundaries, please cite both.

## Citation

```{r}
#| label: cit
#| echo: false
#| results: asis
print(citation("geobounds")[1], style = "html")
```

A **BibTeX** entry for **LaTeX** users:

```{r}
#| echo: false
#| comment: ''
toBibtex(citation("geobounds")[1])
```

## References