# rasters

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

Gridded population, and how to turn it into node populations.

This is the step that turns a boundary file into a metapopulation. [load_nodes()](../api/nodes.md#starsim_data.nodes.load_nodes) gives you where each administrative unit is and how big it is; what it cannot give you, without a download, is how many people live in each one below the national level. That number comes from summing a 1 km gridded population raster inside each unit's polygon:

``` python
import starsim_data as ssd
nodes = ssd.download_nodes('kenya', level=1)   # the node table, with population filled in
ssd.distances('kenya', level=1)                #  ... and the distances between them
```

Which is everything a gravity model needs: `P_i`, `P_j` and `D_ij`.

Requires the `[spatial]` extra (`pip install starsim_data[spatial]`), because reading polygons and clipping rasters needs `geopandas` and `rastertoolkit`. Rasters are cached like every other download; WorldPop's server is slow, so the first call for a country takes a while and later ones do not.

A caution worth carrying: WorldPop's *constrained* estimates are modeled, not counted, and they will not equal the UN WPP national total for the same year - for Kenya 2020 they come out about 1% low. If a model needs the national total to match WPP exactly, rescale: `nodes.population *= wpp_total / nodes.population.sum()`.

## Functions

| Name | Description |
|----|----|
| [aggregate_raster](#starsim_data.rasters.aggregate_raster) | Sum a raster inside each polygon: zonal statistics, keyed by an attribute. |
| [download_nodes](#starsim_data.rasters.download_nodes) | The node table with `population` filled in, from WorldPop, at any level and year. |
| [download_raster](#starsim_data.rasters.download_raster) | Download a WorldPop 1 km gridded-population raster for a country, and cache it. |
| [rescale_to_national](#starsim_data.rasters.rescale_to_national) | Scale node populations so they sum to this package's national WPP total. |

### aggregate_raster

``` python
rasters.aggregate_raster(raster, shapes, by='pcode', nearest=None)
```

Sum a raster inside each polygon: zonal statistics, keyed by an attribute.

#### Parameters

| Name | Type | Description | Default |
|----|----|----|----|
| raster | str / Path | a GeoTIFF, e.g. from [download_raster()](../api/rasters.md#starsim_data.rasters.download_raster). | *required* |
| shapes | GeoDataFrame | polygons, e.g. from [download_shapes()](../api/shapes.md#starsim_data.shapes.download_shapes). | *required* |
| by | str | the column of [shapes](../api/shapes.md#starsim_data.shapes) to key the result on. | `'pcode'` |
| nearest | float | if given, also count a cell whose center is in no polygon but within this distance (in degrees) of one, for the nearest: boundaries are simplified at the coast, so otherwise a coastal city or a small island loses its people. | `None` |

#### Returns

| Name | Type | Description                      |
|------|------|----------------------------------|
| dict |      | `{key: total}` for each polygon. |

#### Raises

| Type | Description |
|----|----|
| ImportError | if the `[spatial]` extra is not installed. |
| ValueError | if `by` is not a column of [shapes](../api/shapes.md#starsim_data.shapes). |

#### Example

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

### download_nodes

``` python
rasters.download_nodes(
    location,
    level=1,
    year=None,
    source=None,
    refresh=False,
    verbose=None,
)
```

The node table with `population` filled in, from WorldPop, at any level and year.

[load_nodes()](../api/nodes.md#starsim_data.nodes.load_nodes) is instant and offline, with populations for 2020 at levels 0 and 1. This downloads the boundaries and the population raster for a country, sums the raster inside each unit, and returns the same table with the numbers filled in.

At a bundled level, the boundaries are downloaded from whichever source the bundled node table used for this country, so the p-codes line up and the join is exact rather than by name. At a finer level (2 and up), the table is built from the boundaries themselves, as the bundled one is, and which units share a border is worked out too and kept in `.attrs['borders']`, for `adjacency(nodes=...)`.

#### Parameters

| Name | Type | Description | Default |
|----|----|----|----|
| location | str | location name, ISO-2/ISO-3 code, official name or alias. | *required* |
| level | int / str | administrative level (default 1). | `1` |
| year | int | population year (default: the node table's, so level 0 and level 1 are for the same year). | `None` |
| source | str | override the boundary source; see [list_shape_sources()](../api/shapes.md#starsim_data.shapes.list_shape_sources). Leaving this alone is usually right - see above. | `None` |
| refresh | bool | re-download even if the files are already cached. | `False` |
| verbose | bool | report progress (default: `options.verbose`). | `None` |

#### Returns

| Name | Type | Description |
|----|----|----|
|  |  | sciris.dataframe: the node table for this location and level, with `population` |
|  |  | filled and `population_source` / `population_year` recorded in |
|  |  | `.attrs['provenance']`. |

#### Raises

| Type | Description |
|----|----|
| ImportError | if the `[spatial]` extra is not installed. |
| KeyError | if the location, its boundaries, or its raster cannot be found. |

#### Example

``` python
import starsim_data as ssd
nodes = ssd.download_nodes('kenya', level=1)
```

### download_raster

``` python
rasters.download_raster(location, year=None, refresh=False, verbose=None)
```

Download a WorldPop 1 km gridded-population raster for a country, and cache it.

#### Parameters

| Name | Type | Description | Default |
|----|----|----|----|
| location | str | location name, ISO-2/ISO-3 code, official name or alias. | *required* |
| year | int | the year to download (2000-2030). Defaults to the year the bundled node table uses for national population, so the two are comparable. | `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                       |
|------|------|-----------------------------------|
|      |      | pathlib.Path: the cached GeoTIFF. |

#### Raises

| Type       | Description                                          |
|------------|------------------------------------------------------|
| ValueError | if the year is outside WorldPop's range.             |
| KeyError   | if WorldPop has no raster for this country and year. |

#### Example

``` python
import starsim_data as ssd
ssd.download_raster('kenya', year=2020)
```

### rescale_to_national

``` python
rasters.rescale_to_national(nodes, location=None, year=None)
```

Scale node populations so they sum to this package's national WPP total.

WorldPop and UN WPP disagree by a percent or two, and which one is "right" depends on the question. This makes the choice explicit rather than leaving two national totals silently in play.

#### Parameters

| Name | Type | Description | Default |
|----|----|----|----|
| nodes | [dataframe](../api/settings.md#starsim_data.settings.dataframe) | a node table with `population` filled, from [download_nodes()](../api/rasters.md#starsim_data.rasters.download_nodes). | *required* |
| location | str | the location; taken from the table if not given. | `None` |
| year | int | the WPP year to match; taken from the table's provenance if not given. | `None` |

#### Returns

| Name | Type | Description                                          |
|------|------|------------------------------------------------------|
|      |      | sciris.dataframe: a copy with `population` rescaled. |

#### Example

``` python
import starsim_data as ssd
nodes = ssd.rescale_to_national(ssd.download_nodes('kenya'))
```
