nodes
The node table: metapopulation geography without the geometry.
A spatial model mostly needs to know, for each administrative unit, where it is, how big it is and how many people live there – not the exact shape of its border. Reduced to that, the whole world at admin 0 and 1 is a few hundred KB, needs no geospatial libraries to read, and ships inside the wheel like everything else in tier 0.
import starsim_data as ssd
ssd.load_nodes('kenya') # one row: the country
ssd.load_nodes('kenya', level=1) # 47 counties: centroids, areas, p-codes
ssd.distances('kenya', level=1) # the 47x47 great-circle distance matrix, in km
ssd.adjacency('kenya', level=1) # which of the 47 counties share a borderColumns are nodeid, location, iso3, level, name, pcode, dot_name, parent, lat, lon, area_km2, population and source.
Two of those deserve a note. pcode is the join key: for UNOCHA-sourced rows it is the humanitarian p-code that essentially all subnational health data is keyed on, and it is what joins a node back to its full geometry. dot_name is the readable hierarchical path (Kenya:Baringo), in this package’s canonical spelling, so that dot_name.split(':')[0] is always a location load() accepts.
population is UN WPP at level 0, and WorldPop (1 km, UN-adjusted, 2020) summed within each unit at level 1, worked out when the table is built. Other years, and finer levels, need the raster aggregation at the time of use, which is a download rather than a lookup, so they live behind download_nodes() in starsim_data.rasters.
Full geometry – actual polygons, for maps and exact spatial operations – is starsim_data.shapes, and needs the [spatial] extra.
Functions
| Name | Description |
|---|---|
| adjacency | Which administrative units share a border: a square boolean matrix. |
| distances | Great-circle distances between node centroids – the input a gravity model needs. |
| load_nodes | Load the node table for a location: centroids, areas, p-codes and hierarchy. |
| node_name | Render an administrative unit’s name in this package’s canonical style. |
adjacency
nodes.adjacency(location=None, level=1, nodes=None, index='dot_name')Which administrative units share a border: a square boolean matrix.
Worked out from the polygons when the node table is built (units within about 100 m of each other count as touching, which absorbs slivers between neighboring polygons), so it needs no geospatial libraries and no download.
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| location | str | location name, ISO-2/ISO-3 code, official name or alias. | None |
| level | int / str | administrative level (default 1; level 1 is the finest bundled). | 1 |
| nodes | dataframe | label the rows and columns from this node table instead of loading one, e.g. one from download_nodes() with population filled in; it must be the units of location at level, in nodeid order or a subset. A table from download_nodes() at a level that is not bundled carries its own borders, so any level works that way. |
None |
| index | str | which column labels the rows and columns – 'dot_name' (default), 'pcode', 'name' or 'nodeid'. |
'dot_name' |
Returns
| Name | Type | Description |
|---|---|---|
| sciris.dataframe: a square, symmetric boolean matrix with a false diagonal. |
Raises
| Type | Description |
|---|---|
| ValueError | if the level has no bundled borders, or index is not recognized. |
Example
import starsim_data as ssd
a = ssd.adjacency('kenya', level=1)
a.loc['Kenya:Nairobi', 'Kenya:Kiambu'] # Returns True: they share a borderdistances
nodes.distances(
location=None,
level=1,
nodes=None,
units='km',
index='dot_name',
)Great-circle distances between node centroids – the input a gravity model needs.
The gravity formulation itself (c_ij = k * P_i^a * P_j^b / D_ij^c) belongs in the model, not in a data package: this provides D_ij, and load_nodes() provides P_i.
Distances are great-circle (haversine) on a spherical Earth, which is within about 0.5% of the geodesic distance – far inside the uncertainty of treating an administrative unit as a point in the first place.
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| location | str | location name, ISO-2/ISO-3 code, official name or alias. | None |
| level | int / str | administrative level to use (default 1, the subdivisions). | 1 |
| nodes | dataframe | use this node table instead of loading one, e.g. one from download_nodes() with population filled in, or a subset. | None |
| units | str | 'km' (default), 'm', or 'mi'. |
'km' |
| index | str | which column labels the rows and columns – 'dot_name' (default), 'pcode', 'name' or 'nodeid'. |
'dot_name' |
Returns
| Name | Type | Description |
|---|---|---|
| sciris.dataframe: a square, symmetric matrix with a zero diagonal. |
Raises
| Type | Description |
|---|---|
| ValueError | if units or index is not recognized, or there are no nodes. |
Example
import starsim_data as ssd
d = ssd.distances('kenya', level=1)
d.loc['Kenya:Nairobi', 'Kenya:Mombasa'] # Returns 433.1 (km)load_nodes
nodes.load_nodes(location, level=0)Load the node table for a location: centroids, areas, p-codes and hierarchy.
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 for the country itself, 1 for its first-level subdivisions. Accepts 'admin1' / 'ADM1' / 1; see parse_level(). None returns every level at once. |
0 |
Returns
| Name | Type | Description |
|---|---|---|
sciris.dataframe: one row per administrative unit, with columns nodeid, |
||
location, iso3, level, name, pcode, dot_name, parent, lat, lon, |
||
area_km2, population and source. Provenance is in .attrs['provenance']. |
Raises
| Type | Description |
|---|---|
| KeyError | if the location is unknown, or has no boundaries in the node table. |
| ValueError | if the level is not available. |
Example
import starsim_data as ssd
ssd.load_nodes('kenya', level=1).shape[0] # Returns 47node_name
nodes.node_name(name)Render an administrative unit’s name in this package’s canonical style.
New York -> New_York, Ile-de-France -> Ile_de_France. The same accent- and punctuation-folding as locations.normalize, but case is preserved: a dot_name is read by people as well as matched by machines.
Shared by the node-table build and by download_shapes(), so that a shape’s dot_name is always the same string as its node’s.