out_map.MapRenderer.choropleth

tools.out_map.MapRenderer.choropleth(
    geo,
    time,
    quantity,
    *,
    borders=None,
    cmap=None,
    proj=None,
    text_label=False,
    title=None,
    transform=None,
    vmax=None,
    vmin=None,
)

Renders a choropleth map using GeoPandas and matplotlib showing the given selections.

Selections must be made carefully to produce a valid map: the geo selection and grouping will dictate which polygons are shown on the map, the time selection must collapse to a single time-point, and the quantity selection must collapse to a single value per node. Of course there are many ways to trim the output data to that form, but we will check the result of the selections to verify it during rendering, and invalid selections will result in an raised exception.

The plot will be immediately rendered by this function by calling plt.show(). This is intended as a quick plotting method to cover most casual use-cases. If you want more control over how the plot is drawn, see method choropleth_plt().

Parameters

geo: GeoSelection | GeoAggregation

the geographic selection to make on the output data

time: TimeSelection | TimeAggregation

the time selection to make on the output data

quantity: QuantitySelection | QuantityAggregation

the quantity selection to make on the output data

borders: GeoSelection | GeoGroup = None

if given, use this geography to draw dark borders, this could be the same or different geography from geo; if None (default), no borders are drawn

cmap: Any | None = None

the color map to use for the plot; you can pass any value you would normally pass to geopandas.GeoDataFrame.plot()

proj: CRS | str = None

the projection to use for mapping; if None (default) we will map using the default projection for the source geography (for US Census, this is NAD83 https://epsg.org/crs_4269/index.html)

text_label: bool | str | NodeLabelRenderer = False

True to render a text label of the data value for each polygon in white; a string to specify a different color, or a NodeLabelRenderer instance to use that.

title: str = None

a title to draw on the plot

transform: Callable[[pd.DataFrame], pd.DataFrame] = None

allows you to specify an arbitrary transform function on the source dataframe before we plot it, e.g., to rescale the values. The dataframe given as the argument is the result of applying all selections and the projection if specified. You should return a dataframe with the same format, where the data column has been modified for your purposes.

Dataframe columns: - “geo”: the node ID of each polygon - “data”: the data value from the quantity selection

vmax: float = None

the max value for the color map, by default the max value of the data

vmin: float = None

the min value for the color map, by default the min value of the data