Skip to main content

plotting

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')