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.
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 | Draw a filled map of an administrative value – the geometry version of plot(which='nodes'). |
| plot | Plot data for a location, as a quick check before it goes into a model. |
choropleth
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. |
'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
import starsim_data as ssd
ax = ssd.choropleth('kenya', level=1)plot
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
import starsim_data as ssd
fig = ssd.plot('kenya')
fig = ssd.plot('kenya', which='population')