# downloading

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

Download data from the organizations that publish it.

[load()](../api/loaders.md#starsim_data.loaders.load) is instant, offline and frozen: decadal snapshots of the Medium variant, which is what almost every model needs, and the default contact matrices (`prem2021`). [fetch()](../api/fetching.md#starsim_data.fetching.fetch) adds the stores this package publishes with its releases. [download()](../api/downloading.md#starsim_data.downloading.download) covers what neither of those has, straight from the UN:

- **annual** resolution rather than every tenth year,
- **complete life tables** (`qx`, `lx`, `ex`, …) rather than just `mx`,
- **other projection variants** (High, Low, Constant fertility, …) rather than Medium.

Unlike the bundled and fetched data, this depends on a server this package does not control, which may be slow, change its files or be unavailable; the name says so at the call site. ([download_shapes()](../api/shapes.md#starsim_data.shapes.download_shapes), [download_raster()](../api/rasters.md#starsim_data.rasters.download_raster) and [download_nodes()](../api/rasters.md#starsim_data.rasters.download_nodes) are the same for the spatial sources.)

It works by downloading the UN's bulk CSVs - the same files `laser-init` uses - into the local cache and filtering them per call. No API token is needed (the WPP Data Portal API requires one; these files do not). The downloads are large, from 17 MB for the indicator file to 145 MB per half of the abridged life table, so they are cached and reused; see [cache_info()](../api/cache.md#starsim_data.cache.cache_info) and [clear_cache()](../api/cache.md#starsim_data.cache.clear_cache).

For the five series that are also bundled, [download](../api/downloading.md#starsim_data.downloading.download) returns exactly the schema [load](../api/loaders.md#starsim_data.loaders.load) returns, so the two are interchangeable apart from resolution. `life_table` and `indicators` have no bundled counterpart and return the upstream shape.

``` python
import starsim_data as ssd
ssd.download('kenya', which='deaths', years=(2000, 2025))     # annual mx, not decadal
ssd.download('kenya', which='life_table', years=2020)         # qx, lx, ex, ...
ssd.download('kenya', which='births', variant='High')         # a different projection
ssd.download('kenya', which='indicators', years=(2020, 2030)) # CDR, TFR, LEx, IMR, ...
```

## Functions

| Name | Description |
|----|----|
| [download](#starsim_data.downloading.download) | Download UN WPP data that is not packaged, caching it for next time. |
| [list_downloadable](#starsim_data.downloading.list_downloadable) | Return the datasets [download()](../api/downloading.md#starsim_data.downloading.download) can retrieve. |

### download

``` python
downloading.download(
    location,
    which='deaths',
    years=None,
    variant=DEFAULT_VARIANT,
    revision=None,
    refresh=False,
    verbose=None,
)
```

Download UN WPP data that is not packaged, caching it for next time.

Unlike [load()](../api/loaders.md#starsim_data.loaders.load) and [fetch()](../api/fetching.md#starsim_data.fetching.fetch), this reaches the UN's own server on a cache miss, which this package does not control: it may be slow, or revise its files. The name says so at the call site; see [provenance()](../api/loaders.md#starsim_data.loaders.provenance) for pinning what was used.

#### Parameters

| Name | Type | Description | Default |
|----|----|----|----|
| location | str | location name, ISO-2/ISO-3 code, official name or alias, exactly as for [load()](../api/loaders.md#starsim_data.loaders.load). WPP is national, so not a subnational unit. | *required* |
| which | str | `'births'`, `'deaths'`, `'migration'`, `'population'`, `'fertility'` (the bundled series, at annual resolution), `'life_table'` (the complete abridged life table), or `'indicators'` (every WPP indicator). See [list_downloadable()](../api/downloading.md#starsim_data.downloading.list_downloadable). | `'deaths'` |
| years | int / tuple / list | a single year; a 2-tuple `(start, end)`, treated as an inclusive range; or an explicit list of years. None means all of 1950-2100, which for life tables means downloading both halves (~290 MB). | `None` |
| variant | str | the projection variant, e.g. `'Medium'` (default), `'High'`, `'Low'`, `'Constant fertility'`. Life tables are Medium-only upstream. | `DEFAULT_VARIANT` |
| revision | str / int | the WPP release to download, e.g. `2024`. Defaults to the newest revision bundled with this package. | `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 |
|----|----|----|
|  |  | sciris.dataframe: for the five bundled series, exactly the schema [load()](../api/loaders.md#starsim_data.loaders.load) |
|  |  | returns. For `life_table`, \`\[Time, Sex, AgeGrpStart, mx, qx, px, lx, dx, Lx, Sx, |
|  |  | Tx, ex, ax\]`with a glossary in`.attrs\['columns'\]`. For`indicators`,`Time\` |
|  |  | plus every indicator column. Provenance is in `.attrs['provenance']`. |

#### Raises

| Type | Description |
|----|----|
| ValueError | if `which`, `years`, `variant` or `revision` cannot be satisfied. |
| KeyError | if the location is unknown. |

#### Example

``` python
import starsim_data as ssd
d = ssd.download('kenya', which='deaths', years=(2020, 2024))
lt = ssd.download('KEN', which='life_table', years=2020)
```

### list_downloadable

``` python
downloading.list_downloadable()
```

Return the datasets [download()](../api/downloading.md#starsim_data.downloading.download) can retrieve.

#### Example

``` python
import starsim_data as ssd
'life_table' in ssd.list_downloadable() # Returns True
```
