# plotting

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

Validation plots.

These exist to catch the errors that are invisible in a table and obvious in a picture: the wrong country, the wrong units, a mortality curve that does not bend the way a mortality curve bends. Plotting the data before it goes into a simulation is the cheapest check there is.

``` python
import starsim_data as ssd
ssd.plot('kenya')                            # a 4-panel summary: pyramid, rates, mx, matrix
ssd.plot('kenya', which='population')        # just the age pyramid
ssd.plot('kenya', which='nodes', level=1)    # where the admin units are (centroids)
ssd.choropleth('kenya', level=1)             # ... and filled polygons, with [spatial]
```

One plotter per layout, looked up in `PLOTTERS`; a new layout can add itself by assigning into that dict, in the same spirit as `ssd.registry.LAYOUTS`. `matplotlib` arrives with sciris (which imports `pyplot` itself) and is a direct Starsim dependency, so this costs nothing at import time and needs no optional extra.

## Functions

| Name | Description |
|----|----|
| [choropleth](#starsim_data.plotting.choropleth) | Draw a filled map of an administrative value - the geometry version of `plot(which='nodes')`. |
| [plot](#starsim_data.plotting.plot) | Plot data for a location, as a quick check before it goes into a model. |

### choropleth

``` python
plotting.choropleth(
    location,
    level=1,
    value='population',
    shapes=None,
    ax=None,
    cmap='viridis',
    fig_kw=None,
    **kwargs,
)
```

Draw a filled map of an administrative value - the geometry version of `plot(which='nodes')`.

Requires the `[spatial]` extra, because it needs real polygons. If you only want to see roughly where the units are, `plot(location, which='nodes')` does that with the bundled centroids and no extra dependencies.

#### Parameters

| Name | Type | Description | Default |
|----|----|----|----|
| location | str | location name, ISO-2/ISO-3 code, official name or alias. | *required* |
| level | int / str | administrative level to draw (default 1). | `1` |
| value | str | the column to color by. `'population'` (default) downloads it from WorldPop; any other name must already be a column of [shapes](../api/shapes.md#starsim_data.shapes). | `'population'` |
| shapes | GeoDataFrame | draw these instead of downloading, e.g. a frame you have already merged your own values onto. | `None` |
| ax | matplotlib.axes.Axes | draw into this axes rather than making a figure. | `None` |
| cmap | str | the colormap. | `'viridis'` |
| fig_kw | dict | passed to `plt.subplots` when creating a figure. | `None` |
| \*\*kwargs |  | passed to `GeoDataFrame.plot`, e.g. `scheme=`, `vmin=`, `vmax=`. |  |

#### Returns

| Name | Type | Description                                |
|------|------|--------------------------------------------|
|      |      | matplotlib.axes.Axes: the axes drawn into. |

#### Raises

| Type        | Description                                |
|-------------|--------------------------------------------|
| ImportError | if the `[spatial]` extra is not installed. |
| ValueError  | if `value` is not available.               |

#### Example

``` python
import starsim_data as ssd
ax = ssd.choropleth('kenya', level=1)
```

### plot

``` python
plotting.plot(location, which=None, year=None, level=1, fig_kw=None)
```

Plot data for a location, as a quick check before it goes into a model.

#### Parameters

| Name | Type | Description | Default |
|----|----|----|----|
| location | str | location name, ISO-2/ISO-3 code, official name or alias. | *required* |
| which | str / list | dataset(s) to plot. None (default) draws a summary figure - age pyramid, crude birth rate, mortality curve and contact matrix - skipping any the location lacks. | `None` |
| year | int | the year to show for the single-year panels (age pyramid, mortality curve). Defaults to the most recent year that is not a projection. | `None` |
| level | int / str | the administrative level, for `which='nodes'` only. | `1` |
| fig_kw | dict | passed to `plt.subplots`, e.g. `dict(figsize=(12, 8))`. | `None` |

#### Returns

| Name | Type | Description |
|----|----|----|
|  |  | matplotlib.figure.Figure: the figure, so it can be saved or further adjusted. |

#### Example

``` python
import starsim_data as ssd
fig = ssd.plot('kenya')
fig = ssd.plot('kenya', which='population')
```
