pycensuskr

A Python package for Korean district-level census and geographic data.

Installation

PyPI

pip install pycensuskr

From source

git clone https://github.com/sigmafelix/pycensuskr.git
cd pycensuskr
pip install -e .

# python setup.py install

For development

git clone https://github.com/sigmafelix/pycensuskr.git
cd pycensuskr
pip install -e ".[dev]"

Usage

from pycensuskr import CensusKR
from matplotlib import pyplot as plt
import geopandas as gpd

# Create a CensusData instance
census = CensusKR()

# load specific year data
data_2020 = census.load_data(year = 2020)
print(data_2020)

# load district boundaries for a specific year
districts_2020 = census.load_districts(year = 2020)
districts_2020["adm2_re"] = districts_2020["adm2_code"].astype(str).str.slice(0,4)
# aggregate geometries by adm2_re
districts_2020 = districts_2020.dissolve(by="adm2_re", as_index=False)
districts_2020["adm2_code"] = districts_2020["adm2_re"] + "0"
districts_2020["adm2_code"] = districts_2020["adm2_code"].astype(int)

# cleaned data with variable types
df_tax_2020 = census.anycensus(year = 2020, type = "tax", aggregator = "sum")

districts_tax_2020 = districts_2020.merge(df_tax_2020, on="adm2_code")
print(districts_tax_2020)

districts_tax_2020.plot("income_labor_mil")
plt.show()

Filter non-/autonomous district codes

from pycensuskr import CensusKR

# Create a CensusData instance
census = CensusKR()

# load population data
pop20 = census.anycensus(year=2020, type="population")
pop20_nonauto = census.detect_adm2_type(df=pop20, mode="non")

Load 2020 adm3-level data

• From version 0.3.0, users can load adm3 (Eup/Myeon/Dong) level data and boundaries. To note, adm3 level data is currently available for population, housing, mortality, and economy types in 2020.

from pycensuskr import CensusKR

# Create a CensusData instance
census = CensusKR()

# load population data
pop20_adm3 = census.anycensus(year = 2020, type = "population", level = "adm3")

# load housing data
housing20_adm3 = census.anycensus(year = 2020, type = "housing", level = "adm3")

Notes on data updates

Our data cleaning and processing pipeline is based on the original R package tidycensuskr. We periodically synchronize the bundled datasets used in this package with those in R tidycensuskr and tidycensuskr.sf to ensure accuracy and relevance. Please refer to the tidycensuskr webpage for details on the latest data updates and changes.

Data license disclaimer

• The data is provided under the Korea Open Government License Type 1 (Attribution) (Note: in Korean). Each raw data table is available for download from the Public Data Portal and KOSIS with no cost.

{style="fig-align: center; width: 200px;"}

Development

Running tests

pytest

License

This project is licensed under the MIT License - see the LICENSE file for details.