---
title: "Working with tidycensuskr"
output: rmarkdown::html_vignette
date: "`r format(Sys.Date(), '%B %d, %Y')`"
vignette: >
  %\VignetteIndexEntry{Working with tidycensuskr} 
  %\VignetteEngine{knitr::rmarkdown}
  %\usepackage[utf8]{inputenc}
---

```{r, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>",
  warning = FALSE,
  message = FALSE,
  out.width = "100%"
)

library(ggplot2)
library(sf)
library(dplyr)
library(tidyr)
```



## Getting Started with tidycensuskr

The `tidycensuskr` package provides easy access to South Korean census and socioeconomic statistics, along with corresponding geospatial boundary data. With this package, R users can query and visualize population, housing, economy, tax, and mortality data linked to administrative districts.

Load the package:
```{r, include = TRUE}
library(tidycensuskr)

```

tidycensuskr will work at its full potential with the companion data package `tidycensuskr.sf`, which contains the district boundaries of South Korea. The package can be installed from R-universe:
```r
install.packages("tidycensuskr.sf", repos = "https://sigmafelix.r-universe.dev")
```

After installing the companion package, three RDS files for 2010, 2015, and 2020 will be accessible through the function `system.file()`. For example, the RDS file path of the 2010 district boundaries can be loaded as follows:

```r
fs10 <- system.file("extdata", "adm2_sf_2010.rds", package = "tidycensuskr.sf")
adm2_sf_2010 <- readRDS(fs10)
```




## 1. Understanding Korean Geographic Hierarchies

South Korean census data is organized by three levels of administrative divisions:

- **_Si-Do_**: The highest level of administrative division.
  - Metropolitan cities are treated as provinces.
  - Jeju-do, Gangwon-do, and Jeollabuk-do have special self-governing status under Korean law.
- **_Si-Gun-Gu_**: The second level, which includes cities and counties.
  - **_Si_**: Cities (urban administrative units)
  - **_Gun_**: Counties (rural areas, typically <50,000 population)
  - **_Gu_**: Districts (urban subdivisions of metropolitan cities or large cities).
    - _Gu_ under metropolitan cities are autonomous districts
    - _Gu_ under 11 large cities, as of 2025 (i.e., Suwon-si, Seongnam-si, Anyang-si, Goyang-si, Ansan-si, Yongin-si, Cheongju-si, Cheonan-si, Pohang-si, Changwon-si, Jeonju-si), are administraitve districts 
- **_Eup-Myeon-Dong_**: The third level, which includes town and districts. (_planned for future releases_)
  - **_Eup_**: Towns (urban, >20,000 population, within a county)
  - **_Myeon_**: Townships (rural, <20,000 population, within a county)
  - **_Dong_**: Neighborhoods (smallest units within cities and districts)

### Comparison of Administrative Divisions  

The table below provides a rough comparison of administrative divisions across South Korea, the United States, the European Union, and the United Kingdom (England). While the correspondence is not exact, it can be helpful to understand the approximate levels when working with census or regional data.  

| South Korea       | US                                         | EU (NUTS[^1]) | UK (England)                     |
|-------------------|-------------------------------------------|---------------|----------------------------------|
| **Si/Do**         | State                                     | NUTS1         | Regions / Combined Authorities   |
| **Si/Gun/Gu**     | County                                    | NUTS2         | County                           |
| **Eup/Myeon/Dong**| Townships / Towns / Census County Division | NUTS3         | Districts / Wards / Boroughs     |

[^1]: NUTS: *Nomenclature of Territorial Units for Statistics*, a geocode standard for referencing the subdivisions of countries for statistical purposes.  


![]("man/figures/korea_map.png")


Because administrative boundaries and coding systems can vary across years and data sources, `tidycensuskr` standardizes administrative codes to allow consistent integration of statistics. 
Currently, for 2020 data there are 250 _Si-Gun-Gu_ and 17 _Si-Do_. The package is provided with a built-in dataset of 2020 _Si-Gun-Gu_ boundaries, which can be loaded using the function `data()`.

```{r, include = TRUE}
data(adm2_sf_2020)
print(length(unique(adm2_sf_2020$adm2_code)))

```


## 2. Available census data
The package provides census and survey data through:  
  - The function `anycensus()` for querying subsets  
  - The built-in dataset `censuskor` in long format  


### Data types
<div style="font-size:80%;">
| type | class1 | class2 | unit | description | available |
|------|--------|--------|------|-------------|-----------|
| population | all households | total | persons | Total population count | 2010, 2015, 2020 |
| population | all households | male | persons | Male population count | 2010, 2015, 2020 |
| population | all households | female | persons | Female population count | 2010, 2015, 2020 |
| tax | income | general | million KRW | General income tax revenue | 2020 |
| tax | income | labor | million KRW | Labor income tax revenue | 2020 |
| mortality | All causes | total | per 100k population | Total mortality rate from all causes | 2020 |
| mortality | All causes | male | per 100k population | Male mortality rate from all causes | 2020 |
| mortality | All causes | female | per 100k population | Female mortality rate from all causes | 2020 |
| economy | company | total | count | Total number of companies | 2010, 2015, 2020 |
| housing | housing types | total | count | Total number of housing units | 2010, 2015, 2020 |
| housing | housing types | detached housing | count | Number of detached/single-family houses | 2010, 2015, 2020 |
| housing | housing types | apartment | count | Number of apartment units | 2010, 2015, 2020 |
| housing | housing types | row house | count | Number of row house units | 2010, 2015, 2020 |
| housing | housing types | multiplex | count | Number of multiplex housing units | 2010, 2015, 2020 |
| housing | housing types | non-residential | count | Number of non-residential buildings used for housing | 2010, 2015, 2020 |
| medicine | doctors | anesthesiology and pain medicine | persons | Number of anesthesiologists | 2010, 2015, 2020 |
| medicine | doctors | clinical laboratory medicine | persons | Number of clinical laboratory physicians | 2010, 2015, 2020 |
| medicine | doctors | dermatology | persons | Number of dermatologists | 2010, 2015, 2020 |
| medicine | doctors | emergency medicine | persons | Number of emergency medicine physicians | 2010, 2015, 2020 |
| medicine | doctors | family medicine | persons | Number of family medicine physicians | 2010, 2015, 2020 |
| medicine | doctors | internal medicine | persons | Number of internal medicine physicians | 2010, 2015, 2020 |
| medicine | doctors | neurology | persons | Number of neurologists | 2010, 2015, 2020 |
| medicine | doctors | neurosurgery | persons | Number of neurosurgeons | 2010, 2015, 2020 |
| medicine | doctors | nuclear medicine | persons | Number of nuclear medicine physicians | 2010, 2015, 2020 |
| medicine | doctors | obstetrics and gynecology | persons | Number of OB/GYN physicians | 2010, 2015, 2020 |
| medicine | doctors | occupational and environmental medicine | persons | Number of occupational/environmental medicine physicians | 2010, 2015, 2020 |
| medicine | doctors | ophthalmology | persons | Number of ophthalmologists | 2010, 2015, 2020 |
| medicine | doctors | orthopedics | persons | Number of orthopedic surgeons | 2010, 2015, 2020 |
| medicine | doctors | otorhinolaryngology | persons | Number of ENT specialists | 2010, 2015, 2020 |
| medicine | doctors | pathology | persons | Number of pathologists | 2010, 2015, 2020 |
| medicine | doctors | pediatrics | persons | Number of pediatricians | 2010, 2015, 2020 |
| medicine | doctors | plastic surgery | persons | Number of plastic surgeons | 2010, 2015, 2020 |
| medicine | doctors | preventive medicine | persons | Number of preventive medicine physicians | 2010, 2015, 2020 |
| medicine | doctors | psychiatry | persons | Number of psychiatrists | 2010, 2015, 2020 |
| medicine | doctors | radiation oncology | persons | Number of radiation oncologists | 2010, 2015, 2020 |
| medicine | doctors | radiology | persons | Number of radiologists | 2010, 2015, 2020 |
| medicine | doctors | rehabilitation medicine | persons | Number of rehabilitation medicine physicians | 2010, 2015, 2020 |
| medicine | doctors | surgery | persons | Number of general surgeons | 2010, 2015, 2020 |
| medicine | doctors | thoracic and cardiovascular surgery | persons | Number of thoracic/cardiovascular surgeons | 2010, 2015, 2020 |
| medicine | doctors | total | persons | Total number of doctors across all specialties | 2010, 2015, 2020 |
| medicine | doctors | tuberculosis | persons | Number of tuberculosis specialists | 2010, 2015, 2020 |
| medicine | doctors | urology | persons | Number of urologists | 2010, 2015, 2020 |
| migration | marital | female | count | Number of female marriage migrants | 2010, 2015, 2020 |
| migration | marital | male | count | Number of male marriage migrants | 2010, 2015, 2020 |
| migration | marital | total | count | Total number of marriage migrants | 2010, 2015, 2020 |
| environment | organic_matter | discharge | kg_day | Daily organic matter discharge | 2010, 2015, 2020 |
| environment | wastewater | generation | m3_day | Daily wastewater generation volume | 2010, 2015, 2020 |
| environment | wastewater | discharge | m3_day | Daily wastewater discharge volume | 2010, 2015, 2020 |
| environment | organic_matter | generation | kg_day | Daily organic matter generation | 2010, 2015, 2020 |
| population | fertility | total | births | Total number of births | 2010, 2015, 2020 |
| population | fertility | 15-19 | births per 1000 | Age-specific fertility rate for ages 15-19 | 2010, 2015, 2020 |
| population | fertility | 20-24 | births per 1000 | Age-specific fertility rate for ages 20-24 | 2010, 2015, 2020 |
| population | fertility | 25-29 | births per 1000 | Age-specific fertility rate for ages 25-29 | 2010, 2015, 2020 |
| population | fertility | 30-34 | births per 1000 | Age-specific fertility rate for ages 30-34 | 2010, 2015, 2020 |
| population | fertility | 35-39 | births per 1000 | Age-specific fertility rate for ages 35-39 | 2010, 2015, 2020 |
| population | fertility | 40-44 | births per 1000 | Age-specific fertility rate for ages 40-44 | 2010, 2015, 2020 |
| population | fertility | 45-49 | births per 1000 | Age-specific fertility rate for ages 45-49 | 2010, 2015, 2020 |
| economy | grdp | gross regional domestic product at market prices | million KRW | Total GRDP at market prices | 2010, 2015, 2020 |
| economy | grdp | net taxes on products | million KRW | Net taxes on products component of GRDP | 2010, 2015, 2020 |
| economy | grdp | total value added at basic prices | million KRW | Total value added at basic prices | 2010, 2015, 2020 |
| economy | grdp | agriculture, forestry and fishing | million KRW | GRDP from agriculture, forestry, and fishing sector | 2010, 2015, 2020 |
| economy | grdp | mining and quarrying | million KRW | GRDP from mining and quarrying sector | 2010, 2015, 2020 |
| economy | grdp | manufacturing | million KRW | GRDP from manufacturing sector | 2010, 2015, 2020 |
| economy | grdp | electricity, gas, steam and air conditioning supply; water supply and waste management | million KRW | GRDP from utilities and waste management sector | 2010, 2015, 2020 |
| economy | grdp | construction | million KRW | GRDP from construction sector | 2010, 2015, 2020 |
| economy | grdp | wholesale and retail trade | million KRW | GRDP from wholesale and retail trade sector | 2010, 2015, 2020 |
| economy | grdp | transportation and storage | million KRW | GRDP from transportation and storage sector | 2010, 2015, 2020 |
| economy | grdp | accommodation and food service activities | million KRW | GRDP from accommodation and food services sector | 2010, 2015, 2020 |
| economy | grdp | information and communication | million KRW | GRDP from information and communication sector | 2010, 2015, 2020 |
| economy | grdp | financial and insurance activities | million KRW | GRDP from financial and insurance sector | 2010, 2015, 2020 |
| economy | grdp | real estate activities; rental and leasing activities | million KRW | GRDP from real estate and rental sector | 2010, 2015, 2020 |
| economy | grdp | professional, scientific and technical activities; business support facilities | million KRW | GRDP from professional/technical services sector | 2010, 2015, 2020 |
| economy | grdp | public administration and defence; compulsory social security | million KRW | GRDP from public administration sector | 2010, 2015, 2020 |
| economy | grdp | education | million KRW | GRDP from education sector | 2010, 2015, 2020 |
| economy | grdp | human health and social work activities | million KRW | GRDP from health and social work sector | 2010, 2015, 2020 |
| economy | grdp | arts, sports and recreation; membership organizations and personal services | million KRW | GRDP from arts, recreation, and personal services sector | 2010, 2015, 2020 |
| social security | basic living security | female | persons | Female recipients of basic living security benefits | 2010, 2015, 2020 |
| social security | basic living security | male | persons | Male recipients of basic living security benefits | 2010, 2015, 2020 |
| social security | basic pension | male | persons | Male recipients of basic pension | 2015, 2020 |
| social security | basic pension | female | persons | Female recipients of basic pension | 2015, 2020 |
| welfare | facilities | residential facility | count | Number of residential welfare facilities | 2015, 2020 |
| welfare | facilities | service facility | count | Number of service-oriented welfare facilities | 2015, 2020 |
| welfare | facilities | other facility | count | Number of other welfare facilities | 2015, 2020 |
| welfare | registered physically mentally challenged | female_0-19 | persons | Registered disabled females aged 0-19 | 2015, 2020 |
| welfare | registered physically mentally challenged | female_20-39 | persons | Registered disabled females aged 20-39 | 2015, 2020 |
| welfare | registered physically mentally challenged | female_40-64 | persons | Registered disabled females aged 40-64 | 2015, 2020 |
| welfare | registered physically mentally challenged | female_65-79 | persons | Registered disabled females aged 65-79 | 2015, 2020 |
| welfare | registered physically mentally challenged | female_80+ | persons | Registered disabled females aged 80 and above | 2015, 2020 |
| welfare | registered physically mentally challenged | male_0-19 | persons | Registered disabled males aged 0-19 | 2015, 2020 |
| welfare | registered physically mentally challenged | male_20-39 | persons | Registered disabled males aged 20-39 | 2015, 2020 |
| welfare | registered physically mentally challenged | male_40-64 | persons | Registered disabled males aged 40-64 | 2015, 2020 |
| welfare | registered physically mentally challenged | male_65-79 | persons | Registered disabled males aged 65-79 | 2015, 2020 |
| welfare | registered physically mentally challenged | male_80+ | persons | Registered disabled males aged 80 and above | 2015, 2020 |
| welfare | registered physically mentally challenged | total_0-19 | persons | Total registered disabled persons aged 0-19 | 2015 |
| welfare | registered physically mentally challenged | total_20-39 | persons | Total registered disabled persons aged 20-39 | 2015 |
| welfare | registered physically mentally challenged | total_40-64 | persons | Total registered disabled persons aged 40-64 | 2015 |
| welfare | registered physically mentally challenged | total_65-79 | persons | Total registered disabled persons aged 65-79 | 2015 |
| welfare | registered physically mentally challenged | total_80+ | persons | Total registered disabled persons aged 80 and above | 2015 |
| welfare | registered physically mentally challenged severity | less severely impaired_0-19 | persons | Less severely impaired persons aged 0-19 | 2020 |
| welfare | registered physically mentally challenged severity | less severely impaired_20-39 | persons | Less severely impaired persons aged 20-39 | 2020 |
| welfare | registered physically mentally challenged severity | less severely impaired_40-64 | persons | Less severely impaired persons aged 40-64 | 2020 |
| welfare | registered physically mentally challenged severity | less severely impaired_65-79 | persons | Less severely impaired persons aged 65-79 | 2020 |
| welfare | registered physically mentally challenged severity | less severely impaired_80+ | persons | Less severely impaired persons aged 80 and above | 2020 |
| welfare | registered physically mentally challenged severity | severely impaired_0-19 | persons | Severely impaired persons aged 0-19 | 2020 |
| welfare | registered physically mentally challenged severity | severely impaired_20-39 | persons | Severely impaired persons aged 20-39 | 2020 |
| welfare | registered physically mentally challenged severity | severely impaired_40-64 | persons | Severely impaired persons aged 40-64 | 2020 |
| welfare | registered physically mentally challenged severity | severely impaired_65-79 | persons | Severely impaired persons aged 65-79 | 2020 |
| welfare | registered physically mentally challenged severity | severely impaired_80+ | persons | Severely impaired persons aged 80 and above | 2020 |
| housing | vacant housing | fraction | percent | Percentage of vacant housing units | 2015, 2020 |
| housing | vacant housing | number of vacant housing | count | Total number of vacant housing units | 2015, 2020 |
| housing | vacant housing | total number of housing | count | Total number of housing units (occupied and vacant) | 2015, 2020 |
| landuse | greenspace | number of greenspace | count | Number of greenspaces | 2010, 2015, 2020 |
| landuse | greenspace | area of greenspace | square meters | Total area of greenspaces | 2010, 2015, 2020 |
| landuse | parks | number of parks | count | Number of parks | 2010, 2015, 2020 |
| landuse | parks | area of parks | square meters | Total area of parks | 2010, 2015, 2020 |
| landuse | road | length of roads | meters | Total length of roads | 2010, 2015, 2020 |
| landuse | road | area of roads | square meters | Total area of roads | 2010, 2015, 2020 |
</div>


* As of version 0.3.0, `tidycensuskr` comes with ADM3 level variables for types `population`, `mortality`, `housing`, and `economy` in 2020 census.

* The data is provided under the Korea Open Government License (KOGL) Type 1 (Attribution) (Note: in Korean). Each raw data table is available for download from the Public Data Portal and Korea Statistical Information System (KOSIS) with no cost. KOGL Type 1 is similar to the Creative Commons Attribution 4.0 International License (CC BY 4.0), which allows for free use, distribution, and adaptation of the data as long as proper attribution is given.

![](inst/extdata/kogl_type1.jpg){style="fig-align: center; width: 200px;"}


### Query data using `anycensus()`

The function `anycensus()` returns a tidy tibble with columns such as:

- `year`: year of the dataset
- `adm1`, `adm1_code`: _Si-Do_ (province) level administrative unit name and its corresponding code 
- `adm2`, `adm2_code`: _Si-Gun-Gu_ (district) level administrative unit name and its corresponding code 
- `adm3`, `adm3_code`: _Eup-Myeon-Dong_ (neighborhood) level administrative unit name and its corresponding code

Columns containing the values are added as a wide form. The column `adm2_code` or `adm3_code` links census data directly to boundary files retrieved with `load_districts()`, depending on the spatial level of data collection.

```{r, include = TRUE}
df_2020 <- anycensus(year = 2020,
                     type = "mortality",
                     level = "adm2")
head(df_2020)

```
The function can also aggregate values to higher administrative units. By specifying `level = "adm1"` and providing an aggregation function, we obtain province-level (`adm1`) results that summarize across all districts.

```{r, include = TRUE}
df_2020_sido <- anycensus(year = 2020,
                          type = "mortality",
                          level = "adm1",
                          aggregator = mean,
                          na.rm = TRUE)
head(df_2020_sido)

```

For rate variables, weighted aggregation is also available. The example below computes a population-weighted mortality rate using the total population column from a separate `type = "population"` query.

```{r, include = TRUE}
df_2020_sido_weighted <- anycensus(year = 2020,
                                   codes = "Seoul",
                                   type = "mortality",
                                   level = "adm1",
                                   aggregator = stats::weighted.mean,
                                   weight_type = "population",
                                   weight_column = "all households_total_prs",
                                   na.rm = TRUE)
head(df_2020_sido_weighted)

```

For provinces that contain both autonomous/basic local government codes and
non-autonomous `Gu` codes, use `adm2_type = "atn"` to clean to the
autonomous/basic local government level. In weighted aggregation, rate rows for
those autonomous units are recalculated from the non-autonomous component
districts using the supplied weights. This can be returned at `level = "adm2"`
or further aggregated to `level = "adm1"`.

```{r, include = TRUE}
df_2020_adm2_weighted_atn <- anycensus(year = 2020,
                                       codes = "Gyeonggi-do",
                                       type = "mortality",
                                       level = "adm2",
                                       adm2_type = "atn",
                                       aggregator = stats::weighted.mean,
                                       weight_type = "population",
                                       weight_column = "all households_total_prs",
                                       na.rm = TRUE)
head(df_2020_adm2_weighted_atn)

```

```{r, include = TRUE}
df_2020_sido_weighted_atn <- anycensus(year = 2020,
                                       codes = "Gyeonggi-do",
                                       type = "mortality",
                                       level = "adm1",
                                       adm2_type = "atn",
                                       aggregator = stats::weighted.mean,
                                       weight_type = "population",
                                       weight_column = "all households_total_prs",
                                       na.rm = TRUE)
head(df_2020_sido_weighted_atn)

```

For ADM3 level data, use `level = "adm3"` and provide the corresponding `adm3_code` to retrieve neighborhood-level data.

```{r, include = TRUE}
df_2020_adm3 <- anycensus(year = 2020,
                          codes = "Seoul",
                          type = "mortality",
                          level = "adm3")
head(df_2020_adm3)
```



### Built-in dataset `censuskor`

You can access the whole dataset directly using the function `data(censuskor)` which returns the built-in dataset in a long form. 

- `year`: year of the dataset
- `adm1`, `adm1_code`: Si-Do (province) level administrative unit name and its corresponding code  
- `adm2`, `adm2_code`: Si-Gun-Gu (district) level administrative unit name and its corresponding code
- `adm3`, `adm3_code`: Eup-Myeon-Dong (neighborhood) level administrative unit name and its corresponding code
- `type`: Types of census or survey
- `class1`, `class2`: Classification variables providing further breakdowns
- `unit`: Measurement unit for the value
- `value`: The observed census value for the given combination of year, region, and category  

```{r, include = TRUE}
data(censuskor)
head(censuskor)

```

### Quick Visualization

Since `anycensus()` returns tidy data, visualization with `ggplot2` is straightforward.

```{r, include = TRUE, fig.width=7, fig.height=4}
ggplot(df_2020, aes(x = `all causes_male_p1p`, y = `all causes_female_p1p`)) +
  geom_point() +
  labs(
    x = "Male mortality (per 100,000 population)",
    y = "Female mortality (per 100,000 population)",
    title = "Male vs. Female Age-standardized Mortality Rates in South Korea (2020)"
  ) +
  theme_minimal(base_size = 10)
```
