Downloading Population Data from WorldPop

In this notebook we will use dhis2eo to download population count data from WorldPop for a set of DHIS2 organisation units.

Step-by-Step Workflow¶

Start by importing the libraries that we need:

import dhis2eo
import dhis2eo.org_units
import dhis2eo.data.worldpop

Step 1. Connect to DHIS2¶

The first thing to do is connect to an instance of DHIS2. For our example, we will connect to a local instance of DHIS2 containing the standard Sierra Leone demo database, but you should be able to switch out the instance url and credentials to work directly with your own database.

from dhis2_client import DHIS2Client
from dhis2_client.settings import ClientSettings

# Create DHIS2 client connection
cfg = ClientSettings(
  base_url="http://localhost:8080",
  username="admin",
  password="district"
)
client = DHIS2Client(settings=cfg)

# Verify connection
info = client.get_system_info()
print("Current DHIS2 version:", info["version"])

Current DHIS2 version: 2.42.3

Step 2: Retrieve organisation units¶

Next, we get the organisation units from our DHIS2 instance and load them into a format we can work with:

org_units_geojson = client.get_org_units_geojson(level=2)
org_units = dhis2eo.org_units.from_dhis2_geojson(org_units_geojson)
org_units

Step 3: Download data for multiple years¶

The dhis2eo.data.worldpop module contains a convenience function for downloading yearly historical and projected population data for individual countries from the WorldPop v2 dataset between 2015 and 2030. Downloading population data for a country and range of years can be achieved with a simple yearly loop and the country’s ISO3-code:

country_code = 'SLE'
for year in range(2015, 2025+1):
    print(f'Year: {year}')

    # Download data...
    data = dhis2eo.data.worldpop.get_population_data(year, country_code)

    # do something with the data
    # e.g. save to disk, aggregate, or import to DHIS2
    # ...

Year: 2015
dhis2eo.data.worldpop - INFO - Loading from cache: /tmp/sle_pop_2015_CN_100m_R2025A_v1.tif
Year: 2016
dhis2eo.data.worldpop - INFO - Loading from cache: /tmp/sle_pop_2016_CN_100m_R2025A_v1.tif
Year: 2017
dhis2eo.data.worldpop - INFO - Loading from cache: /tmp/sle_pop_2017_CN_100m_R2025A_v1.tif
Year: 2018
dhis2eo.data.worldpop - INFO - Loading from cache: /tmp/sle_pop_2018_CN_100m_R2025A_v1.tif
Year: 2019
dhis2eo.data.worldpop - INFO - Loading from cache: /tmp/sle_pop_2019_CN_100m_R2025A_v1.tif
Year: 2020
dhis2eo.data.worldpop - INFO - Loading from cache: /tmp/sle_pop_2020_CN_100m_R2025A_v1.tif
Year: 2021
dhis2eo.data.worldpop - INFO - Loading from cache: /tmp/sle_pop_2021_CN_100m_R2025A_v1.tif
Year: 2022
dhis2eo.data.worldpop - INFO - Loading from cache: /tmp/sle_pop_2022_CN_100m_R2025A_v1.tif
Year: 2023
dhis2eo.data.worldpop - INFO - Loading from cache: /tmp/sle_pop_2023_CN_100m_R2025A_v1.tif
Year: 2024
dhis2eo.data.worldpop - INFO - Loading from cache: /tmp/sle_pop_2024_CN_100m_R2025A_v1.tif
Year: 2025
dhis2eo.data.worldpop - INFO - Loading from cache: /tmp/sle_pop_2025_CN_100m_R2025A_v1.tif

To inspect the contents of the downloaded data, let’s view the data of the last element of the loop:

data

We see that this is data for 2025, and contains data variables total_pop (Total population).

Step 4: Process the data¶

The loop in the previous step only downloaded the data, but didn’t actually do anything with it. For guidance on how to further process the downloaded data, see:

Next steps¶

This notebook has showed how to download and potentially process the WorldPop population count data. As these are yearly data that includes future projections, the script likely only needs to be run once.