# shapes

[shapes](../api/shapes.md#starsim_data.shapes)

Administrative boundaries: the full geometry.

[load_nodes()](../api/nodes.md#starsim_data.nodes.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:

``` bash
pip install starsim_data[spatial]
```

``` python
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()](../api/shapes.md#starsim_data.shapes.download_shapes) just returns the frame, and saving is `gdf.to_file(...)`.

## Functions

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

### borders

``` python
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()](../api/shapes.md#starsim_data.shapes.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

``` python
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()](../api/nodes.md#starsim_data.nodes.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](../api/registry.md#starsim_data.registry.Dataset.level), `name`, |
|  |  | `pcode`, `dot_name`, [source](../api/registry.md#starsim_data.registry.Dataset.source), `geometry`. `pcode` and `dot_name` match |
|  |  | [load_nodes()](../api/nodes.md#starsim_data.nodes.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

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

### list_shape_sources

``` python
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

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

### measure

``` python
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()](../api/shapes.md#starsim_data.shapes.download_shapes). | *required* |

#### Returns

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