<!--
  %\VignetteEngine{knitr}
%\VignetteIndexEntry{i) Creating Administrative Level 1 Maps}
 \usepackage[utf8]{inputenc}
-->

Creating Administrative Level 1 Maps
===

"Administrative Level 1" is the generic term for the largest subnational administrative unit of a country. This unit has different names depending on the country. For example, in the USA Admin 1 units are called "states", but in Japan they are called "prefectures". choroplethr ships with an Admin 1 map of all countries of the world, and supports creating choropleths of these maps. To learn more about the map type the following:

```{r}
library(choroplethrAdmin1)
?admin1.map
```

This vignette walks thru an example of using choroplethr to create an Admin 1 choropleth of Japan. The data we will use is 2010 population estimates from the Japanese Census Bureau:

```{r}
library(choroplethr)
?df_japan_census
data(df_japan_census)
head(df_japan_census)
```

# Step 1: Verify that names match

In order to create a choropleth of our data we first need to understand how names are treated both in the map and in our data. If the names are not the same in both places we will need to make adjustments. (For example if the map says "Tōkyō" but our data says "Tokyo" the map will not render correctly).

First let's see how the map spells the country:

```{r}
head(get_admin1_countries())
```

The map lists the country as "japan" (all lowercase).  Now let's see how the map names the prefectures of Japan:

```{r}
head(get_admin1_regions("japan"))
```

They appear in all lower-case without a trailing "-ken". Note that this is exactly the same convention used in our data. So the names match and we can proceed to the next step.

Note that if you would like to create an Admin 1 map of Japan then type this:

```{r}
admin1_map("japan")
```

# Step 2: Prepare our data

choroplethr requires our data to be in a specific format: a data.frame that contains one column named "region" and one column named "value". `df_japan_census` has a `region` column and several columns of data. But none of them are called `value`. For the purposes of this example, let's copy the `pop_2010` column to the `value` column.

```{r}
df_japan_census$value = df_japan_census$pop_2010
```

# Step 3: Explore our data

Now that our data is prepared for choroplethr, we can view the data with the function `admin1_choropleth`:

```{r}
library(choroplethr)
?admin1_choropleth
admin1_choropleth(country.name = "japan", 
                  df           = df_japan_census, 
                  title        = "2010 Japan Population Estimates", 
                  legend       = "Population", 
                  num_colors   = 1)
```

As with all choropleth functions, you can also zoom in to specific regions and change the scale.  Here is an example of zooming in on the Kansai region of Japan with a continuous scale:

```{r}
kansai = c("mie", "nara", "wakayama", "kyoto", "osaka", "hyogo", "shiga")
admin1_choropleth(country.name = "japan", 
                  df           = df_japan_census, 
                  title        = "2010 Japan Population Estimates - Kansai Region", 
                  legend       = "Population", 
                  num_colors   = 1, 
                  zoom         = kansai)
```