Skip to main content

nodes

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 border

Columns 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 border

distances

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 47

node_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.