# nodes

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

``` python
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](../api/registry.md#starsim_data.registry.Dataset.level), `name`, `pcode`, `dot_name`, `parent`, `lat`, `lon`, `area_km2`, `population` and [source](../api/registry.md#starsim_data.registry.Dataset.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()](../api/loaders.md#starsim_data.loaders.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()](../api/rasters.md#starsim_data.rasters.download_nodes) in [starsim_data.rasters](../api/rasters.md#starsim_data.rasters).

Full geometry - actual polygons, for maps and exact spatial operations - is [starsim_data.shapes](../api/shapes.md#starsim_data.shapes), and needs the `[spatial]` extra.

## Functions

| Name | Description |
|----|----|
| [adjacency](#starsim_data.nodes.adjacency) | Which administrative units share a border: a square boolean matrix. |
| [distances](#starsim_data.nodes.distances) | Great-circle distances between node centroids - the input a gravity model needs. |
| [load_nodes](#starsim_data.nodes.load_nodes) | Load the node table for a location: centroids, areas, p-codes and hierarchy. |
| [node_name](#starsim_data.nodes.node_name) | Render an administrative unit's name in this package's canonical style. |

### adjacency

``` python
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](../api/settings.md#starsim_data.settings.dataframe) | label the rows and columns from this node table instead of loading one, e.g. one from [download_nodes()](../api/rasters.md#starsim_data.rasters.download_nodes) with population filled in; it must be the units of `location` at [level](../api/registry.md#starsim_data.registry.Dataset.level), in `nodeid` order or a subset. A table from [download_nodes()](../api/rasters.md#starsim_data.rasters.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

``` python
import starsim_data as ssd
a = ssd.adjacency('kenya', level=1)
a.loc['Kenya:Nairobi', 'Kenya:Kiambu'] # Returns True: they share a border
```

### distances

``` python
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()](../api/nodes.md#starsim_data.nodes.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](../api/settings.md#starsim_data.settings.dataframe) | use this node table instead of loading one, e.g. one from [download_nodes()](../api/rasters.md#starsim_data.rasters.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

``` python
import starsim_data as ssd
d = ssd.distances('kenya', level=1)
d.loc['Kenya:Nairobi', 'Kenya:Mombasa'] # Returns 433.1 (km)
```

### load_nodes

``` python
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()](../api/locations.md#starsim_data.locations.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](../api/registry.md#starsim_data.registry.Dataset.level), `name`, `pcode`, `dot_name`, `parent`, `lat`, `lon`, |
|  |  | `area_km2`, `population` and [source](../api/registry.md#starsim_data.registry.Dataset.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

``` python
import starsim_data as ssd
ssd.load_nodes('kenya', level=1).shape[0] # Returns 47
```

### node_name

``` python
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()](../api/shapes.md#starsim_data.shapes.download_shapes), so that a shape's `dot_name` is always the same string as its node's.
