---
title: "Getting started"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Getting started}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE, comment = "#>", message = FALSE, warning = FALSE,
  fig.width = 7, fig.height = 4, fig.align = "center", dpi = 96
)
library(countryatlas)
library(ggplot2)
library(dplyr)

# The polygon backend needs `maps`, which is only in Suggests, so every chunk
# that attaches or draws polygon geometry is guarded on this. Without it the
# vignette still builds -- it just skips the maps.
has_maps <- requireNamespace("maps", quietly = TRUE)
```

The goal of **countryatlas** is to get country data onto a map with as little
friction as possible, using ISO codes as the universal join key. The happy path
is a single call.

## A map-ready tibble in one call

With a live connection, `world_data(year)` returns everything you need:

```{r eval = FALSE}
data_2020 <- world_data(2020)
```

To keep this vignette offline, we use the bundled snapshot and attach geometry
ourselves:

```{r eval = has_maps}
data_2020 <- attach_geometry(world_snapshot$countries, geometry = "polygon")
```

## Your first choropleth

No `geom_polygon()` boilerplate; `world_map()` does it:

```{r eval = has_maps, fig.alt = "World choropleth of GDP per capita in quantile bins."}
world_map(data_2020, gdp_per_capita, style = "quantile",
          title = "GDP per capita")
```

Income is a factor whose levels are already in income order, so a categorical
fill reads naturally:

```{r eval = has_maps, fig.alt = "World map coloured by World Bank income group."}
world_map(data_2020, income, style = "categorical")
```

## Choosing indicators

You are not limited to GDP. Pass any World Bank indicator code (named, for clean
columns), or browse the bundled catalogue:

```{r}
head(common_indicators)
```

Or search the full World Bank catalogue by name, offline, against `WDI`'s
bundled indicator cache:

```{r}
head(wdi_search("renewable energy"))
```

```{r eval = FALSE}
country_data(2020, c(life_exp = "SP.DYN.LE00.IN", pop = "SP.POP.TOTL"))
```

## Next steps

* *Joining your own data*: get a frame keyed on messy names onto a map.
* *Modern maps with sf & projections*: equal-area, projected maps.
* *Beyond the choropleth*: bubbles, cartograms, tiles, flows and more.