core_lens.base.namespaces.plot#

Visualisation namespace for Results.

Classes#

SubplotOn

Temporal dimensions to split plot data across.

MapWithLegend

Wrapper around lonboard.Map that adds a legend for Jupyter and HTML exports.

PlotNamespace

Visualisation namespace for Result.

Module Contents#

class core_lens.base.namespaces.plot.SubplotOn(*args, **kwds)#

Bases: enum.Enum

Temporal dimensions to split plot data across.

Used to specify how data should be partitioned into subplots or map layers based on temporal columns added during materialisation.

Variables:

  • YEAR – Split data by year.

  • MONTH – Split data by month.

  • SEASON – Split data by meteorological season.

  • SEASON_YEAR – Split data by season and year.

YEAR = 'year'#
MONTH = 'month'#
SEASON = 'season'#
SEASON_YEAR = 'season_year'#
class core_lens.base.namespaces.plot.MapWithLegend(map_widget: Any, cmap: Any, v_min: float, v_max: float, column_name: str, clamped_min: bool = False, clamped_max: bool = False)#

Wrapper around lonboard.Map that adds a legend for Jupyter and HTML exports.

__getattr__(name: str) → Any#

Get map attribute.

Parameters:

name – The attribute name to look up on the underlying map.

Returns:

The requested attribute from the map widget.

to_html(filename: str | None = None, title: str | None = None) → str | None#

Export the map to a static HTML string or file, injecting the legend.

class core_lens.base.namespaces.plot.PlotNamespace(result: core_lens.base.result.Result)#

Visualisation namespace for Result.

Methods return map or chart objects.

Variables:

result – The parent Result object.

result#
choropleth(column: str, subplot_on: SubplotOn | None = None, v_min: float | None = None, v_max: float | None = None) → MapWithLegend#

Render an interactive choropleth map using Lonboard.

If the Result does not already have geometry, it will be attached automatically via with_geometry().

Parameters:

  • column (str) – The column to use for colour mapping.

  • subplot_on (SubplotOn | None, optional) – Optional temporal dimension to split data across. A SubplotOn enum value. When set, one layer is rendered per unique value of subplot_on in the data.

  • v_min (float | None, optional) – Minimum value for color scale.

  • v_max (float | None, optional) – Maximum value for color scale.

Returns:

A Lonboard Map object.

Return type:

lonboard.Map

Raises:

  • ValueError – If column or subplot_on column not found in data.

  • NotImplementedError – Lonboard does not support native subplot grids; only single-value subplot_on is rendered when specified.

Under the hood:

  • Calls lonboard.Map and lonboard.PolygonLayer to render high-performance WebGL maps.

  • Uses geoarrow.rust.core.from_wkb for zero-copy geometry conversion from Polars WKB.

  • Colormaps are applied via lonboard.colormap.apply_continuous_cmap (using matplotlib colormaps).

timeseries(x: str | None = None, y: str | list[str] | None = None, subplot_on: SubplotOn | str | None = None, top_n: int = 10, aggregate: bool = False) → Any#

Render a timeseries line chart using Bokeh.

Returns a bokeh.models.Tabs widget with two panels: Per Entity (up to top_n entities) and Aggregated Mean. When aggregate=True, only the aggregated panel is returned as a plain bokeh.plotting.figure.

Parameters:

  • x (str | None, optional) – The temporal column to plot on the x-axis.

  • y (str | list[str] | None, optional) – The value column(s) to plot on the y-axis. If None, all numeric columns (except x) are used.

  • subplot_on (SubplotOn | str | None, optional) – Optional temporal dimension to split data across. A SubplotOn enum value or string.

  • top_n (int, optional) – Maximum number of entities rendered in per-entity view.

  • aggregate (bool, optional) – If True, renders only the aggregated mean view.

Returns:

A Bokeh Tabs object (or a single Figure when aggregate=True).

Return type:

Any

Under the hood:

Uses bokeh.plotting.figure to construct interactive line and scatter charts. Data is passed via bokeh.models.ColumnDataSource and split into tabs using bokeh.models.Tabs.

scatter(x: str | None = None, y: str | list[str] | None = None, top_n: int = 10) → Any#

Render a scatter plot using Bokeh.

Parameters:

  • x (str | None, optional) – The column to plot on the x-axis.

  • y (str | list[str] | None, optional) – The column(s) to plot on the y-axis. If None, auto-selects all numeric.

  • top_n (int, optional) – Maximum number of entities to plot.

Returns:

A Bokeh Figure or Tabs object.

Return type:

Any

Under the hood:

Uses bokeh.plotting.figure for the scatter plot rendering, populating data through a ColumnDataSource to enable tooltips and interactive panning.

distribution(x: str | list[str] | None = None, top_n: int = 10) → Any#

Render a distribution (histogram) plot using Bokeh.

Parameters:

  • x (str | list[str] | None, optional) – The column(s) to plot the distribution for. If None, auto-selects all numeric.

  • top_n (int, optional) – Maximum number of entities to include.

Returns:

A Bokeh Figure or Tabs object.

Return type:

Any

Under the hood:

  • Computes histogram bins and counts efficiently using numpy.histogram_bin_edges and numpy.histogram.

  • Renders the resulting distribution using the quad glyph in bokeh.plotting.figure.

correlation(columns: list[str] | None = None, top_n: int = 10) → Any#

Render a correlation heatmap using Bokeh.

Parameters:

  • columns (list[str] | None, optional) – Optional list of columns to correlate. Defaults to all numeric.

  • top_n (int, optional) – Maximum number of entities to include (currently unused).

Returns:

A Bokeh Figure object.

Return type:

Any

Under the hood:

  • Computes the Pearson correlation matrix using pandas’ native corr() method.

  • Renders a heatmap grid using Bokeh’s rect glyph and LinearColorMapper.

heatmap(x: str | None = None, y: str | None = None, value: str | None = None, top_n: int = 10) → Any#

Render a heatmap using Bokeh.

Parameters:

  • x (str | None, optional) – The column for the x-axis.

  • y (str | None, optional) – The column for the y-axis.

  • value (str | None, optional) – The column for the colour values.

  • top_n (int, optional) – Maximum number of entities to include (currently unused).

Returns:

A Bokeh Figure object.

Return type:

Any

Under the hood:

  • Pivots the Polars DataFrame to a 2D matrix.

  • Uses bokeh.plotting.figure with rect glyphs and LinearColorMapper for the color scale.

matrix() → Any#

Render a scatter matrix (pairs plot) using Bokeh.

Returns:

A Bokeh gridplot object.

Return type:

Any

Under the hood:

Iterates through all pairs of numeric columns, creating a grid of individual Bokeh scatter plots and assembling them into a single layout using bokeh.layouts.gridplot.