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=Falsemeasure
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. |