viz#

Visualization tools for geospatial data.

Submodules#

Functions#

match_palette(values[, col_name, weights, threshold])

Return the best-matching color palette for a set of category values.

show_building(location, geodatasets[, styles, radius, ...])

Show building in its context with basemap

show_geometry_context(, max_attrs, title, ...)

Plot any geometry type (Point, LineString, Polygon, and their Multi-

show_ingested_geometries(...)

Plot the last ingested layer for visual inspection.

show_random_entity(→ tuple[matplotlib.pyplot.Figure, ...)

Plot a random entity from the last ingested admin unit with its attributes.

plot_tabulation(df, y_cat, x_cat[, v, title, y_max_n, ...])

Stacked horizontal bar chart of v ~ f(y_cat, x_cat).

tabulate(df, y_cat, x_cat[, v, y_max_n, x_max_n, ...])

Cross-tabulate a numeric variable by two categorical columns.

create_street_view_link(address)

Create a Google street view link from a sequence

Package Contents#

openplaces.viz.match_palette(values, col_name=None, weights=None, threshold=0.5)#

Return the best-matching color palette for a set of category values.

Tries matches in order:

  1. Exact column-name key lookup.

  2. Any palette key is a substring of the column name.

  3. Frequency-weighted coverage: fraction of total weight (row count) whose category label has a defined color, using weights if provided, otherwise falling back to unweighted unique-label coverage.

Parameters:

  • values (iterable) – The category labels present in the plot (e.g. widths.columns).

  • col_name (str, optional) – Column name hint; checked first for an exact or substring key match.

  • weights (array-like, optional) – Total weight (e.g. row count) for each value in values, in the same order. When provided, coverage is computed as the fraction of total weight that falls in palette-covered categories, making the match robust to many rare/uncovered categories.

  • threshold (float) – Minimum coverage required for a value-based match.

Returns:

Matching {label: color} palette, or None if no good match.

Return type:

dict or None

openplaces.viz.show_building(location, geodatasets, styles=None, radius=100, size=10, show_basemap=True, show_crosshair=True, show_location=True, return_fig_ax=False, verbose=False)#

Show building in its context with basemap

Parameters:

  • location (tuple or gpd.GeoDataFrame) – A single-row GeoDataFrame

  • geodatasets (dict of GeoDataFrames) – Loaded geodatasets to be plotted alongside location. The 'parcels' key is special: drawn with inner border and attribute text box at top-left. Any other key is treated as a building footprint or point GeoDataFrame — polygons are drawn as boundaries, points as markers, labels from available columns.

  • styles (dict of dict, optional) – Per-dataset style overrides, keyed by geodatasets keys. Supported sub-keys: ‘color’ (str), ‘n_max’ (int, default 4), ‘columns’ (list[str]), ‘marker’ (str, default ‘o’), ‘markersize’ (int, default 10).

  • radius (float) – Radius of plot in EPSG:3857 “meters” (~1.3m in NY)

  • size (float) – Size of plot in inches (both height and width of figsize)

  • show_basemap (bool) – If True, a basemap is added, and colors of parcels are adjusted.

  • show_crosshair (bool) – Display crosshair of the centerpoint

  • show_location (bool) – Display latitude/longitude of location

  • return_fig_ax (bool) – If True, return the plot’s Figure and Axes objects

  • verbose (bool) – If True, prints counts of matched entities per dataset.

openplaces.viz.show_geometry_context(gdf: geopandas.GeoDataFrame, idx: int | str, buffer_factor: float = 3.0, basemap_source: str = 'Esri.WorldImagery', figsize: tuple = (12, 8), max_attrs: int = 20, title: str = None, min_buffer_m: float = 25.0) → tuple[matplotlib.pyplot.Figure, tuple[matplotlib.pyplot.Axes, matplotlib.pyplot.Axes]]#

Plot any geometry type (Point, LineString, Polygon, and their Multi- variants) in geographic context with its attributes.

Parameters:

  • gdf (gpd.GeoDataFrame) – Source geodataframe.

  • idx (int or str) – Integer position or index label of the target feature.

  • buffer_factor (float) – Buffer size as a multiple of the feature’s maximum dimension. For point geometries (zero extent) the buffer is derived from min_buffer_m instead.

  • basemap_source (str) – Contextily basemap provider string.

  • figsize (tuple) – Figure size (width, height).

  • max_attrs (int) – Maximum number of attributes to display in the table.

  • title (str) – Overrides the default title (‘Feature {idx}’).

  • min_buffer_m (float) – Minimum plot half-width in metres, applied when the feature’s projected extent is smaller than this value (most relevant for point geometries). Default is 1 000 m.

Returns:

  • fig (matplotlib.figure.Figure)

  • ax_map, ax_table (matplotlib.axes.Axes)

openplaces.viz.show_ingested_geometries(ingester, admin_recipe_id: str | None = None, fill: bool = True, color: str = 'skyblue', edgecolor: str = 'blue', point_markersize: float = 2, max_plot: int = 250000, basemap_source: str = 'Esri.WorldImagery', figsize: tuple = (10, 10)) → tuple[matplotlib.pyplot.Figure, matplotlib.pyplot.Axes] | None#

Plot the last ingested layer for visual inspection.

Reads entities and admin boundary from the ingester, applies a sample cap for large datasets, and renders a basemap.

Parameters:

  • ingester (openplaces.io.ingester.Ingester) – Completed ingester whose last saved admin unit is shown.

  • admin_recipe_id (str, optional) – Recipe ID for the admin boundary dataset. Auto-detected from the recipe’s admin_id when omitted.

  • fill (bool) – If True (default), fill polygon geometries. If False, draw boundary only.

  • color (str) – Fill color for polygons or face color for points.

  • edgecolor (str) – Edge/boundary color for polygons.

  • point_markersize (float) – Marker size when entities are points.

  • max_plot (int) – Maximum number of polygon features to render; a random sample is taken when exceeded.

  • basemap_source (str) – Contextily basemap provider string (e.g. ‘Esri.WorldImagery’).

  • figsize (tuple) – Figure size (width, height) in inches.

Returns:

fig, ax

Return type:

matplotlib Figure and Axes, or None if nothing to plot.

openplaces.viz.show_random_entity(ingester) → tuple[matplotlib.pyplot.Figure, tuple[matplotlib.pyplot.Axes, matplotlib.pyplot.Axes]]#

Plot a random entity from the last ingested admin unit with its attributes.

Delegates to show_geometry_context().

Parameters:

ingester (openplaces.io.ingester.Ingester) – Completed ingester whose last saved admin unit is sampled.

Returns:

fig, (ax_map, ax_table)

Return type:

matplotlib Figure and Axes pair.

openplaces.viz.plot_tabulation(df, y_cat, x_cat, v='n', title=None, y_max_n=None, x_max_n=None, y_cat_order=None, x_cat_order=None, show_empty_category=True, y_lab_maxlength=30, x_lab_maxlength=30, gap_perc=0.01, cmap='tab20b', alpha=0.8, savefig=None, figsize=(7, 5), legend_kwds=None, colors=None, fontsize=9, titlesize=12)#

Stacked horizontal bar chart of v ~ f(y_cat, x_cat).

Bar heights are proportional to group totals; bar widths show the x_cat breakdown within each y_cat group.

Parameters:

  • df (pd.DataFrame or gpd.GeoDataFrame)

  • y_cat (str) – Column for y-axis groups (one bar per value).

  • x_cat (str) – Column for the stacked dimension (legend entries).

  • v (str) – Numeric column to aggregate; 'n' counts rows.

  • title (str, optional) – Plot title. Defaults to '% of <v> by <y_cat>'.

  • y_max_n (int, optional) – Cap the number of categories shown per axis.

  • x_max_n (int, optional) – Cap the number of categories shown per axis.

  • y_cat_order (list, optional) – Explicit category orderings.

  • x_cat_order (list, optional) – Explicit category orderings.

  • show_empty_category (bool) – Show NaN values as '(N/A)'.

  • y_lab_maxlength (int) – Truncate labels longer than this.

  • x_lab_maxlength (int) – Truncate labels longer than this.

  • gap_perc (float) – Gap between bars as a fraction of total data weight.

  • cmap (str) – Matplotlib colormap name, used when colors is None.

  • alpha (float) – Bar opacity.

  • savefig (str or Path, optional) – Save to this path if provided.

  • figsize (tuple, optional) – Figure size (width, height).

  • legend_kwds (dict, optional) – Keyword arguments passed to ax.legend(). Defaults to {'loc': 'upper right', 'bbox_to_anchor': (0.985, 0.985)}. Any key overrides the default; omitted keys keep their default value.

  • colors (list, optional) – Explicit list of colors, one per x_cat value.

  • fontsize (int) – Font sizes for labels and title.

  • titlesize (int) – Font sizes for labels and title.

Returns:

  • fig (matplotlib.figure.Figure)

  • ax (matplotlib.axes.Axes)

openplaces.viz.tabulate(df, y_cat, x_cat, v='n', y_max_n=None, x_max_n=None, y_cat_order=None, x_cat_order=None, show_empty_category=True)#

Cross-tabulate a numeric variable by two categorical columns.

Parameters:

  • df (pd.DataFrame or gpd.GeoDataFrame)

  • y_cat (str) – Column for y-axis categories.

  • x_cat (str) – Column for x-axis categories (the stacked dimension).

  • v (str) – Numeric column to aggregate; 'n' counts rows.

  • y_max_n (int, optional) – Keep only the top-N y categories by total weight; remainder is collapsed into '(all others)'.

  • x_max_n (int, optional) – Same for x categories.

  • y_cat_order (list, optional) – Explicit ordering for y-axis values.

  • x_cat_order (list, optional) – Explicit ordering for x-axis values (stack order).

  • show_empty_category (bool) – If True, fill NaN labels with '(N/A)' instead of dropping.

Returns:

Normalized crosstab (values sum to 1), shape (y_cats, x_cats).

Return type:

pd.DataFrame

Create a Google street view link from a sequence

Parameters:

address (list | pd.Series) – Address, ideally in the order: street, city, zip, state, country