Skip to main content

shapes

shapes

Administrative boundaries: the full geometry.

load_nodes() gives you centroids, areas and p-codes, which is what a metapopulation model actually consumes and which fits in the wheel. This module gives you the polygons, for maps, exact spatial joins and raster aggregation. Polygons do not fit in a wheel – a single country at admin 2 runs to tens of MB – so they are downloaded and cached, and they need the optional geospatial stack:

pip install starsim_data[spatial]
import starsim_data as ssd
ssd.list_shape_sources()                              # what's available, and its license
gdf = ssd.download_shapes('kenya', level=1)              # 47 counties, with geometry
gdf = ssd.download_shapes('kenya', level=2, source='gadm')

Three sources, because coverage genuinely varies by country and level:

source coverage levels key license
unocha ~110 countries 0-4 p-code CC BY 3.0 IGO
geoboundaries near-universal 0-5 shapeID CC BY 4.0
gadm universal 0-5 GID_n non-commercial only

source=None tries UNOCHA then geoBoundaries – UNOCHA first because its p-codes are the join key for essentially all subnational health data. GADM is never reached automatically: it is licensed for non-commercial use only, so asking for it has to be a deliberate act. That constraint lives in the source descriptor (ShapeSource.redistributable) rather than in anyone’s memory, and the build scripts refuse to derive bundled data from a source that sets it False.

Two things deliberately not ported from laser-init. Its UNOCHA extractor falls back to a 1-2 GB global geodatabase when a country is missing; a download that size triggered implicitly by a library call is user-hostile, and geoBoundaries covers the same gap for a few MB. And its transformer writes GeoPackages to an output directory as a pipeline step; here download_shapes() just returns the frame, and saving is gdf.to_file(...).

Functions

Name Description
borders The pairs of polygons that share a border.
download_shapes Download administrative boundaries with full geometry from their publisher, and cache them.
list_shape_sources Return the boundary sources as a dataframe: coverage, levels and license.
measure The centroid latitude and longitude, and the area in km², of each polygon.

borders

shapes.borders(gdf, tolerance=TOUCH_TOLERANCE)

The pairs of polygons that share a border.

Parameters

Name Type Description Default
gdf GeoDataFrame polygons in WGS84, e.g. from download_shapes(). required
tolerance float polygons closer than this, in degrees, count as touching (default about 100 m, which absorbs slivers between neighboring polygons). TOUCH_TOLERANCE

Returns

Name Type Description
numpy.ndarray: (n, 2) row positions (i, j) with i < j.

download_shapes

shapes.download_shapes(
    location,
    level=1,
    source=None,
    refresh=False,
    verbose=None,
)

Download administrative boundaries with full geometry from their publisher, and cache them.

Requires the [spatial] extra. For centroids, areas and populations without any geospatial dependency, use load_nodes() instead – it is bundled and instant.

Parameters

Name Type Description Default
location str location name, ISO-2/ISO-3 code, official name or alias. required
level int / str administrative level; 0 is the country, 1 its first-level subdivisions. Accepts 'admin2' / 'ADM2' / 2. 1
source str 'unocha', 'geoboundaries' or 'gadm'. None (default) tries UNOCHA then geoBoundaries. GADM is never tried automatically – it is licensed for non-commercial use only, so it must be asked for by name. None
refresh bool re-download even if the file is already cached. False
verbose bool report progress (default: options.verbose). None

Returns

Name Type Description
geopandas.GeoDataFrame: columns nodeid, location, iso3, level, name,
pcode, dot_name, source, geometry. pcode and dot_name match
load_nodes() for the same source, so the two join directly.

Raises

Type Description
ImportError if the [spatial] extra is not installed.
ValueError if the source or level is not recognized.
KeyError if the location is unknown, or no source has it at this level.

Example

import starsim_data as ssd
gdf = ssd.download_shapes('kenya', level=1)

list_shape_sources

shapes.list_shape_sources()

Return the boundary sources as a dataframe: coverage, levels and license.

Returns

Name Type Description
sciris.dataframe: with columns `[source, max_level, license, redistributable,
universal, note]`.

Example

import starsim_data as ssd
ssd.list_shape_sources() # One row per source; GADM's has redistributable=False

measure

shapes.measure(gdf)

The centroid latitude and longitude, and the area in km², of each polygon.

Parameters

Name Type Description Default
gdf GeoDataFrame polygons in WGS84, e.g. from download_shapes(). required

Returns

Name Type Description
tuple arrays of latitudes, longitudes and areas, one entry per row.