Bug - `add_edge_population` fails is there are two GHSL tiles overlapping the study area

[juanfonsecaLS1]

Hi @cbueth

When the study area overlaps more than one of the GHSL tiles, the function add_edge_population returns an error.

Here is a reprex for this behaviour

import osmnx as ox
from superblockify.population.approximation import add_edge_population

boundary_lat, boundary_lon = 41.8956456, 12.4655397

graph = ox.graph_from_point(
    (boundary_lat, boundary_lon), 
    dist=500, 
    network_type='drive', 
    simplify=True
)

graph = ox.add_edge_speeds(graph)
graph = ox.add_edge_travel_times(graph)
graph = ox.project_graph(graph)

add_edge_population(graph, overwrite=True)
# 2026-04-01 12:21:54,478 |     INFO | tessellation.py:101 | Calculating edge cells for graph with 165 edges.
# 2026-04-01 12:21:54,609 |     INFO | tessellation.py:155 | Tessellated 132 edge cells in 0:00:00.
# 2026-04-01 12:21:54,672 |     INFO | ghsl.py:129 | Using the GHSL raster tiles for the bounding box (1039130.3128053441, 4999534.908906185, 1040472.7243228266, 5000784.670403941).
# TypeError: invalid path or file: ['/home/juan/create-toy-nets/data/ghsl/GHS_POP_E2025_GLOBE_R2023A_54009_100_V1_0_R4_C20.tif', '/home/juan/create-toy-nets/data/ghsl/GHS_POP_E2025_GLOBE_R2023A_54009_100_V1_0_R5_C20.tif']
# Cell In[56], line 1
# ----> 1 add_edge_population(graph, overwrite=True)

To fix this, we will need to preprocess the tiles beforehand. The changes shouldn't be too long

[cbueth]

Hola @juanfonsecaLS1, thanks for noting this and sharing thereproducable code. I have been able to reproduce the error.
The problem has been noted in the Places on edge tiles subsection in the guide pages. The commented solution there for get_population is looping over the tiles, as you suggest. While I was conscious about this for the notebook and large polygons, specifically for add_edge_population I do not remember it being problematic, but it is only designed to wirk with one tile.
If you look at the full stacktrace, you can see that it comes from get_edge_population (working in the dataset projected crs: Mollweide).

...
    add_edge_population(graph, overwrite=True)
    ~~~~~~~~~~~~~~~~~~~^^^^^^^^^^^^^^^^^^^^^^^
  File "/Users/cbueth/code/superblockify/superblockify/population/approximation.py", line 65, in add_edge_population
    edge_population = get_edge_population(graph, **tess_kwargs)
  File "/Users/cbueth/code/superblockify/superblockify/population/approximation.py", line 188, in get_edge_population
    with rasopen(ghsl_file) as src:
...

The pattern for handling multiple GHSL tiles already exists in our documentation - see:

• Example notebook: examples/06-population-density.ipynb:710
• Documentation: docs/guide/30_population_density.myst:434

The approach there is to iterate over the tile files:

for pop_raster_file in pop_raster_files if isinstance(pop_raster_files, list) else [pop_raster_files]:
    # Load each tile individually

To fix this I'd suggest:

1. In get_edge_population() handle the list case when calling rasopen() and load_ghsl_as_polygons()
2. In load_ghsl_as_polygons()accept either a single path string or a list of paths, and concatenate the results

The GHSL tile loading functions (get_ghsl, download_ghsl, get_ghsl_urls) already correctly return a list when multiple tiles are needed. It's just the consumption code that needs updating.

Would you like to work on this fix? If needed I can give you more hints.

---

I think it is simpler to modify load_ghsl_as_polygon and concatenate them if it is mroe than one, rather than changing the get_edge_population() function.

def load_ghsl_as_polygons(file, window=None):
   # Add this at the start of the function:
    if isinstance(file, list):
        results = []
        for f in file:
            results.append(load_ghsl_as_polygons_single(f, window))
        return pd.concat(results, ignore_index=True)
    # [...]

Make sure to test this properly, possibly with some notebook or the geographical place you need this for. Working with projections and affines can be sensitive.