epymorph.tools.out_map

Tools for rendering geographic maps from epymorph simulation output data.

NodeLabelRenderer

NodeLabelRenderer(color: str = 'white')

Customizes rendering of text labels on choropleth maps.

The default implementation is very simple, but you may override this class to customize. Default implementations of coords, labels, colors, and additional_kwargs are given so you can override only the aspects you are interested in customizing.

Parameters:

color (str, default: 'white' ) –

The default color of the labels. Accepts color formats supported by matplotlib.

coords

coords(data_gdf: DataFrame) -> GeoSeries

Determine where to draw the labels.

Parameters:

data_gdf (DataFrame) –

The geography/data being rendered.

Returns:

GeoSeries –

The series of centroids for each row in the data. Data must be shapely.Point instances.

labels

labels(data_gdf: DataFrame) -> Iterable[str | None]

Determine the text of each label.

Parameters:

data_gdf (DataFrame) –

The geography/data being rendered.

Returns:

Iterable[str | None] –

The series of labels for each row in the data. Values can be None to skip labeling a row.

colors

colors(
    data_gdf: DataFrame, color_scale: ScalarMappable
) -> Iterable[str]

Determine the color of each label.

Parameters:

data_gdf (DataFrame) –

The geography/data being rendered.
color_scale (ScalarMappable) –

A color scale to use.

Returns:

Iterable[str] –

The series of colors for each row in the data. Values can be any color format supported by matplotlib.

additional_kwargs

additional_kwargs(data_gdf: DataFrame) -> Iterable[dict]

Determine extra keyword arguments to pass to the method drawing labels; supports any argument used by matplotlib.axes.Axes.annotate.

Parameters:

data_gdf (DataFrame) –

The geography/data being rendered.

Returns:

Iterable[dict] –

The series of dicts containing additional kwargs options for each row in the data.

render

render(
    ax: Axes,
    data_gdf: DataFrame,
    color_scale: ScalarMappable,
) -> None

Render labels onto the given matplotlib axes.

Parameters:

ax (Axes) –

The axes on which to render.
data_gdf (DataFrame) –

The geography/data being rendered.
color_scale (ScalarMappable) –

The color scale to use.

MapRenderer

MapRenderer(output: Output)

Provides methods for rendering an output in choropleth map form.

Most commonly, you will use MapRenderer starting from a simulation output object that supports it:

out = BasicSimulation(rume).run()
out.map.choropleth(...)

Parameters:

output (Output) –

The output the renderer will use.

output `instance-attribute`

output: Output = output

The output the renderer will use.

geography_data

geography_data(
    geo: GeoSelection | GeoAggregation,
    time: TimeSelection | TimeAggregation,
    quantity: QuantitySelection | QuantityAggregation,
    *,
    proj: CRS | str | None = None,
    transform: Callable[[DataFrame], DataFrame]
    | None = None,
) -> GeoDataFrame

Calculate the geo dataframe used for drawing maps merged with the output data from the given axis strategies.

This is an advanced method that allows you to leverage the data-handling logic of MapRenderer without necessarily drawing a map.

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.
proj (CRS | str | None, default: 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)
transform (Callable[[DataFrame], DataFrame] | None, default: 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

Returns:

GeoDataFrame –

The geo dataframe as a result of applying the axis strategies to the data.

Raises:

GeographyError –

If we cannot fetch geography for the type of scope used.

geography

geography(
    geo: GeoSelection | GeoGroup | GeoAggregation,
    *,
    proj: CRS | str | None = None,
) -> GeoDataFrame

Calculate the geo dataframe by applying the given geo axis strategy, but without merging any simulation data.

This is an advanced method that allows you to leverage the geo-handling logic of MapRenderer without necessarily drawing a map.

Parameters:

geo (GeoSelection | GeoGroup | GeoAggregation) –

The geographic selection to make on the source geography.
proj (CRS | str | None, default: 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)

Returns:

GeoDataFrame –

The geo dataframe as a result of applying the geo axis strategies to the source geography.

Raises:

GeographyError –

If we cannot fetch geography for the type of scope used.

choropleth

choropleth(
    geo: GeoSelection | GeoAggregation,
    time: TimeSelection | TimeAggregation,
    quantity: QuantitySelection | QuantityAggregation,
    *,
    borders: GeoSelection | GeoGroup | None = None,
    cmap: Any | None = None,
    proj: CRS | str | None = None,
    text_label: bool | str | NodeLabelRenderer = False,
    title: str | None = None,
    transform: Callable[[DataFrame], DataFrame]
    | None = None,
    vmax: float | None = None,
    vmin: float | None = None,
) -> 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, default: 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, default: 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, default: 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, default: 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, default: None ) –

A title to draw on the plot.
transform (Callable[[DataFrame], DataFrame] | None, default: 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, default: None ) –

The max value for the color map, by default the max value of the data.
vmin (float | None, default: None ) –

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

Raises:

GeographyError –

If we cannot fetch geography for the type of scope used.

choropleth_plt

choropleth_plt(
    ax: Axes,
    geo: GeoSelection | GeoAggregation,
    time: TimeSelection | TimeAggregation,
    quantity: QuantitySelection | QuantityAggregation,
    *,
    borders: GeoSelection | GeoGroup | None = None,
    cmap: Any | None = None,
    proj: CRS | str | None = None,
    transform: Callable[[DataFrame], DataFrame]
    | None = None,
    vmax: float | None = None,
    vmin: float | None = None,
) -> tuple[GeoDataFrame, ScalarMappable]

Draws a choropleth map onto the given matplotlib axes showing the given selections. This is a variant of the method choropleth() that gives you more control over the rendering of a plot by letting you do most of the work with matplotlib's API. See that method for conditions that must be met to use this method effectively.

Parameters:

ax (Axes) –

The plot axes on which to draw the map.
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, default: 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, default: 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, default: 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)
transform (Callable[[DataFrame], DataFrame] | None, default: 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, default: None ) –

The max value for the color map, by default the max value of the data.
vmin (float | None, default: None ) –

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

Returns:

tuple[GeoDataFrame, ScalarMappable] –

a tuple with 1. the geo dataframe containing the data used to render the map and 2. the map's color scale.

Raises:

GeographyError –

If we cannot fetch geography for the type of scope used.

MapRendererMixin

Bases: Output

Mixin class that adds a convenient method for rendering choropleth maps from an output.

map `property`

map: MapRenderer

Render a choropleth map from this output.

epymorph.tools.out_map

NodeLabelRenderer

coords

labels

colors

additional_kwargs

render

MapRenderer

output instance-attribute

geography_data

geography

choropleth

choropleth_plt

MapRendererMixin

map property

output `instance-attribute`

map `property`