Visualization#

Twiga ships a unified plotting toolkit built on Lets-Plot, a Kotlin/Python port of ggplot2. All public functions are available via a flat import:

from twiga.core.plot import (
    plot_forecast,
    plot_forecast_intervals,
    plot_quantile_fan,
    twiga_theme,
)

Every function returns a Lets-Plot ggplot object that can be displayed inline in Jupyter notebooks, saved to a file, or composed with + like standard ggplot layers.

Theme#

A consistent visual identity across all plots. Apply twiga_theme() to any ggplot object or pass it once to a function via the theme parameter.

twiga.core.plot.theme.twiga_theme(show_x_axis=True, font_size=10, line_width=0.8, x_axis_angle=0, legend_pos='top', grid=False)#

Official Twiga Forecast theme for Lets-Plot visualizations.

Produces clean, publication-quality figures aligned with the Twiga brand: left-aligned title, optional subtle horizontal grid, no vertical grid, and a professional Inter/Segoe-UI font stack.

Parameters:

show_x_axis (bool) – Whether to render x-axis labels, ticks, and title.
font_size (int) – Base font size in points (axis labels, legend text).
line_width (float) – Base stroke width for axis lines and ticks.
x_axis_angle (int) – Rotation angle for x-axis tick labels.
legend_pos (Literal['top', 'bottom', 'left', 'right', 'none']) – Legend anchor - “top”, “bottom”, “left”, “right”, or “none”.
grid (bool) – If True, draw subtle horizontal reference lines.

Return type:

Returns:

A Lets-Plot theme object ready to be added to any ggplot.

Examples

>>> from twiga.core.plot import twiga_theme, TWIGA_PALETTE
>>> p = ggplot(df, aes("x", "y")) + geom_line() + twiga_theme()

twiga.core.plot.theme.TWIGA_PALETTE = ['#00BFA5', '#0072B2', '#D55E00', '#E69F00', '#7035B7', '#57B8E0', '#CC79A7', '#56595E', '#009E73', '#8AABB4']#

Built-in mutable sequence.

If no argument is given, the constructor creates a new empty list. The argument must be an iterable if specified.

Time Series & Forecast Plots#

Core functions for visualising point forecasts, prediction intervals and quantile fans against observed data.

twiga.core.plot.timeseries.plot_forecast(data, *, date_col=None, actual_col='Actual', forecast_col='forecast', lower_col=None, upper_col=None, model_name=None, title=None, subtitle=None, x_label='Time step', y_label='Value', n_samples=None, caption='Twiga Forecast', show_x_axis=True, font_size=10, line_width=0.8, x_axis_angle=0, legend_pos='top', grid=False, fig_size=(820, 300), ribbon_fill='#00BFA5', ribbon_alpha=0.2, actual_line_size=0.75, actual_alpha=0.65, forecast_line_size=0.75, forecast_alpha=0.95)#

Visualize forecast vs actual values with an optional prediction interval.

Produces a clean two-layer plot: a light grey actual line underneath a bold Twiga-teal forecast line, with an optional translucent ribbon for confidence / prediction intervals.

Parameters:

data (DataFrame) – DataFrame containing the columns specified by actual_col, forecast_col, and optionally date_col, lower_col, upper_col.
date_col (str | None) – Column name for the x-axis (dates or ordered labels). If None or not found, an integer sample index is used.
actual_col (str) – Column containing observed (true) values.
forecast_col (str) – Column containing model predictions.
lower_col (str | None) – Column for the lower bound of the prediction interval.
upper_col (str | None) – Column for the upper bound of the prediction interval.
model_name (str | None) – Model identifier shown in the auto-generated title.
title (str | None) – Override the auto-generated title.
subtitle (str | None) – Optional subtitle shown below the title.
x_label (str) – X-axis label.
y_label (str) – Y-axis label.
n_samples (int | None) – If given, only the first n_samples rows are plotted.
caption (str) – Plot caption (attribution / tool credit).
show_x_axis (bool) – Whether to render x-axis labels, ticks, and title.
font_size (int) – Base font size in points.
line_width (float) – Stroke width for axis lines and ticks.
x_axis_angle (int) – Rotation angle for x-axis tick labels.
legend_pos (Literal['top', 'bottom', 'left', 'right', 'none']) – Legend anchor - “top”, “bottom”, “left”, “right”, or “none”.
grid (bool) – If True, draw subtle horizontal reference lines.
fig_size (tuple[int, int]) – Figure size as (width_px, height_px).
ribbon_fill (str) – Fill colour for the prediction interval ribbon.
ribbon_alpha (float) – Transparency of the ribbon (0 = invisible, 1 = opaque).
actual_line_size (float) – Stroke width of the actual (observed) line.
actual_alpha (float) – Transparency of the actual line.
forecast_line_size (float) – Stroke width of the forecast line.
forecast_alpha (float) – Transparency of the forecast line.

Return type:

Returns:

A Lets-Plot ggplot object.

Examples

>>> from twiga.core.plot import plot_forecast
>>> p = plot_forecast(results, date_col="ds", actual_col="y", forecast_col="yhat")
>>> p

twiga.core.plot.timeseries.plot_timeseries(data, y_cols, *, date_col=None, band_col=None, band_labels=None, title='Time Series', subtitle=None, x_label='Time', y_label='Value', n_samples=None, caption='Twiga Forecast', grid=False, font_size=10, show_x_axis=True, line_width=0.8, x_axis_angle=0, legend_pos='top', fig_size=(820, 280), series_line_size=0.75, series_alpha=0.95, band_alpha=0.25, band_colors=None)#

Plot one or multiple time series from a DataFrame.

Data is melted to long format internally; each series receives a distinct colour from the Twiga palette.

Parameters:

data (DataFrame) – Source DataFrame.
y_cols (list[str] | str) – One or more column names to plot on the y-axis.
date_col (str | None) – Column for the x-axis. Falls back to an integer index.
band_col (str | None) – Optional binary/categorical column used to shade the background (e.g. "day_night"). Each unique value gets a distinct semi-transparent ribbon.
band_labels (dict[int, str] | None) – Mapping from band_col value to display label, e.g. {0: "Night", 1: "Day"}.
title (str) – Plot title.
subtitle (str | None) – Optional subtitle.
x_label (str) – X-axis label.
y_label (str) – Y-axis label.
n_samples (int | None) – Limit to the first N rows.
caption (str) – Plot caption.
grid (bool) – If True, draw subtle horizontal reference lines.
font_size (int) – Base font size in points.
show_x_axis (bool) – Whether to render x-axis labels, ticks, and title.
line_width (float) – Stroke width for axis lines and ticks.
x_axis_angle (int) – Rotation angle for x-axis tick labels.
legend_pos (Literal['top', 'bottom', 'left', 'right', 'none']) – Legend anchor - “top”, “bottom”, “left”, “right”, or “none”.
fig_size (tuple[int, int]) – Figure size (width_px, height_px).
series_line_size (float) – Stroke width of the time series lines.
series_alpha (float) – Transparency of the time series lines.
band_alpha (float) – Transparency of the background shading bands.
band_colors (dict[int, str] | None) – Mapping from band value to fill colour. Defaults to {0: "#d4e8f7", 1: "#fff9e6"} for night/day.

Return type:

Returns:

A Lets-Plot ggplot object.

Examples

>>> from twiga.core.plot import plot_timeseries
>>> p = plot_timeseries(
...     df, ["NetLoad(kW)"], date_col="timestamp", band_col="day_night", band_labels={0: "Night", 1: "Day"}
... )
>>> p

twiga.core.plot.timeseries.plot_forecast_grid(data, *, date_col=None, actual_col='Actual', forecast_col='forecast', model_col='Model', n_samples_per_model=None, title='Forecast vs Actual', x_label='Sample', y_label='Value', caption='Twiga Forecast', ncol=1, panel_height=240, fig_width=860, show_x_axis=True, font_size=10, line_width=0.8, x_axis_angle=0, legend_pos='top', grid=False, actual_line_size=0.75, actual_alpha=0.65, forecast_line_size=0.75, forecast_alpha=0.95)#

Faceted forecast grid - one panel per model.

Equivalent to the classic multi-subplot matplotlib view but rendered as a single Lets-Plot ggplot with facet_wrap.

Parameters:

data (DataFrame) – DataFrame with columns for actuals, forecasts, and model names.
date_col (str | None) – Column for x-axis. Falls back to integer index.
actual_col (str) – Observed values column.
forecast_col (str) – Predicted values column.
model_col (str) – Column that identifies each model (used for faceting).
n_samples_per_model (int | None) – Rows shown per model panel (default: all rows).
title (str) – Overall plot title.
x_label (str) – X-axis label.
y_label (str) – Y-axis label.
caption (str) – Plot caption.
ncol (int) – Number of facet columns.
panel_height (int) – Height in pixels of each individual panel row.
fig_width (int) – Total figure width in pixels.
show_x_axis (bool) – Whether to render x-axis labels, ticks, and title.
font_size (int) – Base font size in points.
line_width (float) – Stroke width for axis lines and ticks.
x_axis_angle (int) – Rotation angle for x-axis tick labels.
legend_pos (Literal['top', 'bottom', 'left', 'right', 'none']) – Legend anchor - “top”, “bottom”, “left”, “right”, or “none”.
grid (bool) – If True, draw subtle horizontal reference lines.
actual_line_size (float) – Stroke width of the actual (observed) lines.
actual_alpha (float) – Transparency of the actual lines.
forecast_line_size (float) – Stroke width of the forecast lines.
forecast_alpha (float) – Transparency of the forecast lines.

Return type:

Returns:

A Lets-Plot ggplot object.

twiga.core.plot.timeseries.dual_line_plot(df, target_col, *, exog_col=None, date_col='timestamp', target_unit=None, exog_unit=None, colors=None, dataset_name=None, n_samples=None, caption='Twiga Forecast', show_x_axis=True, font_size=10, line_width=0.8, x_axis_angle=0, grid=False, fig_size=(820, 280), line_size=0.75, series_alpha=0.95)#

Plot target time series with an optional exogenous series in a stacked panel.

When exog_col is provided, the two series are shown in separate stacked panels with independent y-axes (scales="free_y"), avoiding the misleading dual-axis scaling of traditional approaches. Without exog_col a single line is drawn.

Parameters:

df (DataFrame) – Source DataFrame.
target_col (str) – Column name for the primary series.
exog_col (str | None) – Optional column name for a second series plotted below.
date_col (str | None) – Column to use as the x-axis. Defaults to "timestamp". Falls back to an integer index if not found.
target_unit (str | None) – Physical unit for the target label, e.g. "kW".
exog_unit (str | None) – Physical unit for the exogenous label, e.g. "W/m²".
colors (list[str] | None) – Two hex colours for target and exog. Defaults to the first two Twiga palette colours (color-blind safe Blue / Vermilion).
dataset_name (str | None) – Plot title. Defaults to "Dataset".
n_samples (int | None) – Limit to the first N rows before plotting.
caption (str) – Plot caption.
show_x_axis (bool) – Whether to render x-axis labels, ticks, and title.
font_size (int) – Base font size in points.
line_width (float) – Stroke width for axis lines and ticks.
x_axis_angle (int) – Rotation angle for x-axis tick labels.
grid (bool) – If True, draw subtle horizontal reference lines.
fig_size (tuple[int, int]) – (width_px, height_px) of a single panel. Total height doubles automatically when exog_col is present.
line_size (float) – Stroke width for the series lines.
series_alpha (float) – Transparency of the series lines.

Return type:

Returns:

A Lets-Plot ggplot object.

Examples

>>> from twiga.core.plot import dual_line_plot
>>> p = dual_line_plot(
...     df, "NetLoad(kW)", exog_col="Ghi", target_unit="kW", exog_unit="W/m²", dataset_name="MLVS-PT"
... )
>>> p

twiga.core.plot.timeseries.plot_quantile_fan(data, *, date_col=None, actual_col='Actual', median_col='q50', quantile_pairs=None, title='Probabilistic Forecast - Fan Chart', subtitle=None, x_label='Time step', y_label='Value', n_samples=None, caption='Twiga Forecast', show_x_axis=True, font_size=10, line_width=0.8, x_axis_angle=0, legend_pos='top', grid=False, fig_size=(820, 380), ribbon_fill='#00BFA5', min_ribbon_alpha=0.12, max_ribbon_alpha=0.32, actual_line_size=0.75, actual_alpha=0.25, median_line_size=0.75, median_alpha=0.95)#

Fan chart for multi-quantile probabilistic forecasts.

Renders graduated ribbon bands from widest (lightest) to narrowest (most opaque), with the median line on top and actual observations in light grey underneath. Widely used in meteorological and energy forecasting literature to communicate forecast uncertainty.

Parameters:

data (DataFrame) – DataFrame with quantile and actual columns.
date_col (str | None) – Column for the x-axis. Falls back to integer index.
actual_col (str) – Column of observed values.
median_col (str) – Column of median (q50) forecasts.
quantile_pairs (list[tuple[str, str]] | None) – List of (lower_col, upper_col) column pairs, ordered from widest to narrowest interval. Auto-detected from qXX columns if None.
title (str) – Plot title.
subtitle (str | None) – Optional subtitle (auto-generated if None).
x_label (str) – X-axis label.
y_label (str) – Y-axis label.
n_samples (int | None) – Limit to the first N rows.
caption (str) – Plot caption.
show_x_axis (bool) – Whether to render x-axis labels, ticks, and title.
font_size (int) – Base font size in points.
line_width (float) – Stroke width for axis lines and ticks.
x_axis_angle (int) – Rotation angle for x-axis tick labels.
legend_pos (Literal['top', 'bottom', 'left', 'right', 'none']) – Legend anchor - “top”, “bottom”, “left”, “right”, or “none”.
grid (bool) – If True, draw subtle horizontal reference lines.
fig_size (tuple[int, int]) – Figure size (width_px, height_px).
ribbon_fill (str) – Fill colour for the quantile ribbons. Defaults to TWIGA_PALETTE[3] (emerald).
min_ribbon_alpha (float) – Transparency of the widest (outermost) ribbon.
max_ribbon_alpha (float) – Transparency of the narrowest (innermost) ribbon.
actual_line_size (float) – Stroke width of the actual (observed) line.
actual_alpha (float) – Transparency of the actual line.
median_line_size (float) – Stroke width of the median forecast line.
median_alpha (float) – Transparency of the median line.

Return type:

Returns:

A Lets-Plot ggplot object.

Examples

>>> from twiga.core.plot import plot_quantile_fan
>>> p = plot_quantile_fan(
...     results,
...     median_col="q50",
...     quantile_pairs=[("q10", "q90"), ("q25", "q75")],
... )
>>> p

twiga.core.plot.timeseries.plot_forecast_intervals(data, interval_specs, *, date_col=None, actual_col='Actual', title='Forecast Interval Comparison', subtitle=None, x_label='Time step', y_label='Value', n_samples=None, caption='Twiga Forecast', show_x_axis=True, font_size=10, line_width=0.8, x_axis_angle=0, legend_pos='top', grid=False, fig_size=(820, 380), min_ribbon_alpha=0.15, max_ribbon_alpha=0.26, actual_line_size=0.75, actual_alpha=0.85, center_line_size=0.75, center_alpha=0.95)#

Overlay multiple models’ prediction intervals for direct comparison.

Renders each model as a semi-transparent ribbon + centre line, making sharpness and coverage differences across methods immediately visible (e.g. CQR vs CRC vs parametric Normal).

Parameters:

data (DataFrame) – DataFrame with actual values and all interval columns.
interval_specs (list[dict[str, str]]) – List of dicts, one per method. Each dict must have: - "model" - display name - "lower" - lower bound column name - "upper" - upper bound column name - "center" - centre / median column (optional)
date_col (str | None) – Column for the x-axis. If None, integer steps are used.
actual_col (str) – Column of observed values.
title (str) – Plot title.
subtitle (str | None) – Optional subtitle (auto-generated from model names if None).
x_label (str) – X-axis label.
y_label (str) – Y-axis label.
n_samples (int | None) – Limit to the first N rows.
caption (str) – Plot caption.
show_x_axis (bool) – Whether to render x-axis labels, ticks, and title.
font_size (int) – Base font size in points.
line_width (float) – Stroke width for axis lines and ticks.
x_axis_angle (int) – Rotation angle for x-axis tick labels.
legend_pos (Literal['top', 'bottom', 'left', 'right', 'none']) – Legend anchor - “top”, “bottom”, “left”, “right”, or “none”.
grid (bool) – If True, draw subtle horizontal reference lines.
fig_size (tuple[int, int]) – Figure size (width_px, height_px).
min_ribbon_alpha (float) – Transparency of the first method’s ribbon.
max_ribbon_alpha (float) – Transparency of the last method’s ribbon.
actual_line_size (float) – Stroke width of the actual (observed) line.
actual_alpha (float) – Transparency of the actual line.
center_line_size (float) – Stroke width of the centre/median lines.
center_alpha (float) – Transparency of the centre lines.

Return type:

Returns:

A Lets-Plot ggplot object.

Examples

>>> specs = [
...     {"model": "CQR", "lower": "lo_c", "upper": "hi_c", "center": "q50_c"},
...     {"model": "Norm", "lower": "lo_n", "upper": "hi_n", "center": "mu_n"},
... ]
>>> p = plot_forecast_intervals(df, specs, date_col="ds")

Residual Diagnostics#

Functions for visually diagnosing forecast residuals — checking normality, heteroscedasticity and leverage.

twiga.core.plot.residuals.residual_plot(data, x_col='fitted', y_col='residuals', color_col='split', title='Tukey-Anscombe Plot', subtitle='Residuals vs Fitted - check linearity & homoscedasticity', x_label='Fitted', y_label='Residuals', caption='Twiga Forecast', font_size=10, show_x_axis=True, line_width=0.8, x_axis_angle=0, legend_pos='top', grid=False, fig_size=(500, 300), point_size=1.8, point_alpha=0.65, zero_line_color='#D55E00', zero_line_type='dashed', zero_line_size=0.75, smooth_method='loess', smooth_line_size=0.75, smooth_color='#00BFA5', smooth_se=False)#

Tukey-Anscombe plot: residuals vs fitted values.

Scatter of residuals against fitted values overlaid with a LOESS smooth and a horizontal zero line. Use this plot to detect non-linearity and heteroscedasticity.

Parameters:

data (DataFrame) – DataFrame with columns for fitted values and residuals.
x_col (str) – Column of fitted values (x-axis).
y_col (str) – Column of residual values (y-axis).
color_col (str) – Column used to colour points by cross-validation split.
title (str) – Plot title.
subtitle (str) – Plot subtitle.
x_label (str) – X-axis label.
y_label (str) – Y-axis label.
caption (str) – Plot caption.
font_size (int) – Base font size.
show_x_axis (bool) – Whether to render x-axis labels, ticks, and title.
line_width (float) – Stroke width for axis lines and ticks.
x_axis_angle (int) – Rotation angle for x-axis tick labels.
legend_pos (Literal['top', 'bottom', 'left', 'right', 'none']) – Legend anchor.
grid (bool) – If True, draw subtle horizontal reference lines.
fig_size (tuple[int, int]) – Figure size (width_px, height_px).
point_size (float) – Size of scatter points.
point_alpha (float) – Transparency of points.
zero_line_color (str) – Colour of the horizontal zero line.
zero_line_type (str) – Linetype of the zero line.
zero_line_size (float) – Stroke width of the zero line.
smooth_method (Literal['lm', 'loess']) – Smoothing method (“lm” or “loess”).
smooth_line_size (float) – Stroke width of the smooth line.
smooth_color (str) – Colour of the smooth line.
smooth_se (bool) – Whether to show confidence band around smooth.

Return type:

Returns:

A Lets-Plot ggplot object.

twiga.core.plot.residuals.normal_q_qplot(data, sample_col='residual', color_col='split', title='Normal Q-Q Plot', subtitle='Standardised residuals vs theoretical normal quantiles', x_label='Theoretical Quantiles', y_label='Standardised Residuals', caption='Twiga Forecast', font_size=10, show_x_axis=True, line_width=0.8, x_axis_angle=0, legend_pos='top', grid=False, fig_size=(500, 300), point_size=1.8, point_alpha=0.65, qq_line_color='#D55E00', qq_line_type='dashed', qq_line_size=0.75)#

Normal Q-Q plot for standardised residuals.

Points should fall on the red reference line if residuals are normally distributed. Systematic departures indicate heavy tails or skewness.

Parameters:

data (DataFrame) – DataFrame with a column of standardised residuals.
sample_col (str) – Column of sample values to check against the normal.
color_col (str) – Column used to colour points by split.
title (str) – Plot title.
subtitle (str) – Plot subtitle.
x_label (str) – X-axis label.
y_label (str) – Y-axis label.
caption (str) – Plot caption.
font_size (int) – Base font size.
show_x_axis (bool) – Whether to render x-axis labels, ticks, and title.
line_width (float) – Stroke width for axis lines and ticks.
x_axis_angle (int) – Rotation angle for x-axis tick labels.
legend_pos (Literal['top', 'bottom', 'left', 'right', 'none']) – Legend anchor.
grid (bool) – If True, draw subtle horizontal reference lines.
fig_size (tuple[int, int]) – Figure size (width_px, height_px).
point_size (float) – Size of Q-Q points.
point_alpha (float) – Transparency of points.
qq_line_color (str) – Colour of the reference diagonal line.
qq_line_type (str) – Linetype of the reference line.
qq_line_size (float) – Stroke width of the reference line.

Return type:

Returns:

A Lets-Plot ggplot object.

twiga.core.plot.residuals.squared_residual_plot(data, x_col='fitted', y_col='sqrt_abs_std_res', color_col='split', title='Scale-Location Plot', subtitle='Check for homoscedasticity - expect a flat LOESS band', x_label='Fitted', y_label='√|Std. Residuals|', caption='Twiga Forecast', font_size=10, show_x_axis=True, line_width=0.8, x_axis_angle=0, legend_pos='top', grid=False, fig_size=(500, 300), point_size=1.8, point_alpha=0.65, smooth_method='loess', smooth_line_size=0.75, smooth_color='#00BFA5', smooth_se=False)#

Scale-Location plot: √|standardised residuals| vs fitted.

A roughly horizontal LOESS band indicates constant variance (homoscedasticity). A rising or falling band suggests heteroscedasticity.

Parameters:

data (DataFrame) – DataFrame with fitted values and pre-computed √|std. residuals|.
x_col (str) – Column of fitted values.
y_col (str) – Column of √|standardised residuals|.
color_col (str) – Column used to colour points by split.
title (str) – Plot title.
subtitle (str) – Plot subtitle.
x_label (str) – X-axis label.
y_label (str) – Y-axis label.
caption (str) – Plot caption.
font_size (int) – Base font size.
show_x_axis (bool) – Whether to render x-axis labels, ticks, and title.
line_width (float) – Stroke width for axis lines and ticks.
x_axis_angle (int) – Rotation angle for x-axis tick labels.
legend_pos (Literal['top', 'bottom', 'left', 'right', 'none']) – Legend anchor.
grid (bool) – If True, draw subtle horizontal reference lines.
fig_size (tuple[int, int]) – Figure size (width_px, height_px).
point_size (float) – Size of scatter points.
point_alpha (float) – Transparency of points.
smooth_method (Literal['lm', 'loess']) – Smoothing method (“lm” or “loess”).
smooth_line_size (float) – Stroke width of the smooth line.
smooth_color (str) – Colour of the smooth line.
smooth_se (bool) – Whether to show confidence band.

Return type:

Returns:

A Lets-Plot ggplot object.

twiga.core.plot.residuals.residual_leverage_plot(data, x_col='leverage', y_col='std_res', color_col='split', featuresize=None, title='Residuals vs Leverage', subtitle="Dashed lines: Cook's distance 0.5 (amber) and 1.0 (vermilion)", x_label='Leverage', y_label='Std. Residuals', caption='Twiga Forecast', font_size=10, show_x_axis=True, line_width=0.8, x_axis_angle=0, legend_pos='top', grid=False, fig_size=(500, 300), point_size=1.8, point_alpha=0.65, smooth_method='loess', smooth_line_size=0.75, smooth_color='#00BFA5', smooth_se=False, cook_05_color='#0072B2', cook_05_linetype='dashed', cook_05_line_size=0.75, cook_10_color='#D55E00', cook_10_linetype='dashed', cook_10_line_size=0.75)#

Residuals vs leverage plot with Cook’s distance contours.

Points outside the dashed Cook’s distance contours (0.5 and 1.0) are potentially influential observations worth investigating.

Parameters:

data (DataFrame) – DataFrame with leverage and standardised residuals columns.
x_col (str) – Column of leverage values.
y_col (str) – Column of standardised residuals.
color_col (str) – Column used to colour points by split.
featuresize (int | None) – Number of predictors p in the model (defaults to 1).
title (str) – Plot title.
subtitle (str) – Plot subtitle.
x_label (str) – X-axis label.
y_label (str) – Y-axis label.
caption (str) – Plot caption.
font_size (int) – Base font size.
show_x_axis (bool) – Whether to render x-axis labels, ticks, and title.
line_width (float) – Stroke width for axis lines and ticks.
x_axis_angle (int) – Rotation angle for x-axis tick labels.
legend_pos (Literal['top', 'bottom', 'left', 'right', 'none']) – Legend anchor.
grid (bool) – If True, draw subtle horizontal reference lines.
fig_size (tuple[int, int]) – Figure size (width_px, height_px).
point_size (float) – Size of scatter points.
point_alpha (float) – Transparency of points.
smooth_method (Literal['lm', 'loess']) – Smoothing method for the LOESS trend.
smooth_line_size (float) – Stroke width of the smooth line.
smooth_color (str) – Colour of the smooth line.
smooth_se (bool) – Whether to show confidence band.
cook_05_color (str) – Colour of the Cook’s distance = 0.5 contour.
cook_05_linetype (str) – Linetype of the 0.5 contour.
cook_05_line_size (float) – Stroke width of the 0.5 contour.
cook_10_color (str) – Colour of the Cook’s distance = 1.0 contour.
cook_10_linetype (str) – Linetype of the 1.0 contour.
cook_10_line_size (float) – Stroke width of the 1.0 contour.

Return type:

Returns:

A Lets-Plot ggplot object.

Distribution Plots#

Functions for visualising predicted or empirical distributions — density, KDE, CDF and combined distribution panels.

twiga.core.plot.distribution.plot_density(df, *, title='Density Plot', subtitle=None, n_samples=None, x_col='value', color_col='distribution', x_label='Value', y_label='Density', alpha=0.25, line_size=0.75, adjust=1.0, font_size=10, caption='Twiga Forecast', flavor='light', show_x_axis=True, line_width=0.8, x_axis_angle=0, legend_pos='top', grid=False, fig_size=(500, 300))#

Overlaid kernel density plot for multiple distributions.

Parameters:

df (DataFrame) – Long-format DataFrame with at least x_col and color_col.
title (str) – Plot title.
subtitle (str | None) – Optional subtitle.
n_samples (int | None) – Limit rows to N samples.
x_col (str) – Numeric column for the x-axis.
color_col (str) – Categorical column that defines each distribution group.
x_label (str) – X-axis label.
y_label (str) – Y-axis label.
alpha (float) – Fill transparency (0–1).
line_size (float) – Density outline stroke width.
adjust (float) – KDE bandwidth multiplier (>1 = smoother).
font_size (int) – Base font size.
caption (str) – Plot caption.
flavor (Optional[Literal['dark', 'light']]) – "dark" for high-contrast dark, "light" for solarised light, None for plain Twiga theme.
show_x_axis (bool) – Whether to render x-axis labels, ticks, and title.
line_width (float) – Stroke width for axis lines and ticks.
x_axis_angle (int) – Rotation angle for x-axis tick labels.
legend_pos (Literal['top', 'bottom', 'left', 'right', 'none']) – Legend anchor - “top”, “bottom”, “left”, “right”, or “none”.
grid (bool) – If True, draw subtle horizontal reference lines.
fig_size (tuple[int, int]) – Figure size (width_px, height_px).

Return type:

Returns:

A Lets-Plot ggplot object.

twiga.core.plot.distribution.plot_kde(df, x_col, color_col=None, *, title='Density', x_label=None, alpha=0.85, line_size=0.75, caption='Twiga Forecast', show_x_axis=True, font_size=10, line_width=0.8, x_axis_angle=0, legend_pos='top', grid=False, fig_size=(500, 300))#

Kernel density estimate with optional per-group colour encoding.

Thin wrapper around plot_density() using the plot_kde name.

Parameters:

df (DataFrame) – Source DataFrame.
x_col (str) – Numeric column to estimate density for.
color_col (str | None) – Optional categorical column for per-group density curves.
title (str) – Plot title.
x_label (str | None) – X-axis label (defaults to x_col).
alpha (float) – Fill transparency.
line_size (float) – Density outline stroke width.
caption (str) – Plot caption.
show_x_axis (bool) – Whether to render x-axis labels, ticks, and title.
font_size (int) – Base font size in points.
line_width (float) – Stroke width for axis lines and ticks.
x_axis_angle (int) – Rotation angle for x-axis tick labels.
legend_pos (Literal['top', 'bottom', 'left', 'right', 'none']) – Legend anchor - “top”, “bottom”, “left”, “right”, or “none”.
grid (bool) – If True, draw subtle horizontal reference lines.
fig_size (tuple[int, int]) – Figure size (width_px, height_px).

Return type:

Returns:

A Lets-Plot ggplot object.

twiga.core.plot.distribution.plot_cdf(df, x_col, color_col=None, *, title='Cumulative Distribution', x_label=None, caption='Twiga Forecast', show_x_axis=True, font_size=10, line_width=0.8, x_axis_angle=0, legend_pos='top', grid=False, fig_size=(500, 300), step_line_size=0.75, step_alpha=0.95)#

Empirical cumulative distribution function (ECDF).

Computes the ECDF per group and renders step lines with Twiga-palette colours.

Parameters:

df (DataFrame) – Source DataFrame.
x_col (str) – Numeric column for the x-axis.
color_col (str | None) – Optional categorical grouping column.
title (str) – Plot title.
x_label (str | None) – X-axis label (defaults to x_col).
caption (str) – Plot caption.
show_x_axis (bool) – Whether to render x-axis labels, ticks, and title.
font_size (int) – Base font size in points.
line_width (float) – Stroke width for axis lines and ticks.
x_axis_angle (int) – Rotation angle for x-axis tick labels.
legend_pos (Literal['top', 'bottom', 'left', 'right', 'none']) – Legend anchor - “top”, “bottom”, “left”, “right”, or “none”.
grid (bool) – If True, draw subtle horizontal reference lines.
fig_size (tuple[int, int]) – Figure size (width_px, height_px).
step_line_size (float) – Stroke width of the step lines.
step_alpha (float) – Transparency of the step lines.

Return type:

Returns:

A Lets-Plot ggplot object.

twiga.core.plot.distribution.plot_distribution(df, x_col, y_col, color_col=None, *, title=None, x_label=None, y_label=None, alpha=0.2, caption='Twiga Forecast', show_x_axis=True, font_size=10, line_width=0.8, x_axis_angle=0, legend_pos='top', grid=False, fig_size=(560, 320), ribbon_alpha=0.2, line_size=0.75)#

Mean ± standard-deviation band grouped by x_col.

Groups by x_col (and optionally color_col), computes per-group mean and std for y_col, then renders the mean as a line with a translucent ±1σ ribbon.

Parameters:

df (DataFrame) – Source DataFrame.
x_col (str) – Grouping / x-axis column (e.g. "hour").
y_col (str) – Numeric column whose distribution to visualise.
color_col (str | None) – Optional secondary grouping column.
title (str | None) – Plot title.
x_label (str | None) – X-axis label.
y_label (str | None) – Y-axis label.
alpha (float) – Ribbon transparency (deprecated, use ribbon_alpha).
caption (str) – Plot caption.
show_x_axis (bool) – Whether to render x-axis labels, ticks, and title.
font_size (int) – Base font size in points.
line_width (float) – Stroke width for axis lines and ticks.
x_axis_angle (int) – Rotation angle for x-axis tick labels.
legend_pos (Literal['top', 'bottom', 'left', 'right', 'none']) – Legend anchor - “top”, “bottom”, “left”, “right”, or “none”.
grid (bool) – If True, draw subtle horizontal reference lines.
fig_size (tuple[int, int]) – Figure size (width_px, height_px).
ribbon_alpha (float) – Transparency of the ±1σ ribbon.
line_size (float) – Stroke width of the mean line.

Return type:

Returns:

A Lets-Plot ggplot object.

Data Exploration#

Functions for exploratory data analysis — line charts, scatter plots, correlation heatmaps.

twiga.core.plot.exploration.line_plot(y, x, *, title='Charge Curve', y_label='Voltage (V)', x_label=None, show_x_axis=True, font_size=10, line_width=0.8, x_axis_angle=0, legend_pos='top', grid=False, fig_size=(500, 300), caption='Twiga Forecast', line_color='#00BFA5', line_size=0.75, line_alpha=1.0)#

Plot a clean line curve (e.g. charge/discharge profile).

Parameters:

y (Sequence[float]) – Y-values.
x (Sequence[float] | None) – Optional X-values. If None, a normalised [0, 1] range is used.
title (str) – Plot title.
y_label (str) – Y-axis label.
x_label (str | None) – X-axis label.
show_x_axis (bool) – Whether to render x-axis labels, ticks, and title.
font_size (int) – Base font size in points.
line_width (float) – Stroke width for axis lines and ticks.
x_axis_angle (int) – Rotation angle for x-axis tick labels.
legend_pos (Literal['top', 'bottom', 'left', 'right', 'none']) – Legend anchor - “top”, “bottom”, “left”, “right”, or “none”.
grid (bool) – If True, draw subtle horizontal reference lines.
fig_size (tuple[int, int]) – Figure size (width_px, height_px).
caption (str) – Plot caption.
line_color (str) – Colour of the line. Defaults to TWIGA_PALETTE[0] (deep blue).
line_size (float) – Stroke width of the line.
line_alpha (float) – Transparency of the line.

Return type:

Returns:

A Lets-Plot ggplot object.

twiga.core.plot.exploration.scatter_plot(data, x_col='cycle', y_col='value', color_col='group', facet=True, title=None, caption='Twiga Forecast', show_x_axis=True, font_size=10, line_width=0.8, x_axis_angle=0, legend_pos='top', grid=False, point_size=3.5, point_alpha=0.65, smooth_method='loess', smooth_line_size=0.75, smooth_color='#0072B2')#

Create a faceted scatter plot with a LOESS trend line per group.

Parameters:

data (DataFrame) – Input DataFrame.
x_col (str) – Column for the x-axis.
y_col (str) – Column for the y-axis.
color_col (str) – Column used for colour encoding.
facet (bool) – If True, wrap the plot into multiple panels based on color_col.
title (str | None) – Optional plot title.
caption (str) – Plot caption.
show_x_axis (bool) – Whether to render x-axis labels, ticks, and title.
font_size (int) – Base font size in points.
line_width (float) – Stroke width for axis lines and ticks.
x_axis_angle (int) – Rotation angle for x-axis tick labels.
legend_pos (Literal['top', 'bottom', 'left', 'right', 'none']) – Legend anchor - “top”, “bottom”, “left”, “right”, or “none”.
grid (bool) – If True, draw subtle horizontal reference lines.
point_size (float) – Size of the scatter points.
point_alpha (float) – Transparency of the scatter points.
smooth_method (Literal['lm', 'loess']) – Smoothing method for the trend line (“lm” or “loess”).
smooth_line_size (float) – Stroke width of the trend line.
smooth_color (str) – Colour of the trend line. Defaults to TWIGA_PALETTE[1] (amber).

Return type:

Returns:

A Lets-Plot ggplot object.

twiga.core.plot.exploration.scatter_matrix(data, variables, targets, hue_col=None, n_sample=1000, random_state=111, title=None, caption='Twiga Forecast', show_x_axis=True, font_size=10, line_width=0.8, x_axis_angle=0, legend_pos='top', grid=False, fig_size=(700, 700), sort_by_variance=False, diag='density', point_size=1.8, point_alpha=0.65, density_alpha=0.1)#

Create a scatter-plot matrix (pair plot) using Lets-Plot.

Parameters:

data (DataFrame) – Input DataFrame.
variables (list[str]) – Column names for the x-axes.
targets (list[str]) – Column names for the y-axes.
hue_col (str | None) – Optional colour-encoding column.
n_sample (int | None) – Rows to sample. None uses all rows.
random_state (int) – Random seed for sampling.
title (str | None) – Optional title.
caption (str) – Plot caption.
show_x_axis (bool) – Whether to render x-axis labels, ticks, and title.
font_size (int) – Base font size in points.
line_width (float) – Stroke width for axis lines and ticks.
x_axis_angle (int) – Rotation angle for x-axis tick labels.
legend_pos (Literal['top', 'bottom', 'left', 'right', 'none']) – Legend anchor - “top”, “bottom”, “left”, “right”, or “none”.
grid (bool) – If True, draw subtle horizontal reference lines.
fig_size (tuple[int, int]) – Figure size (width_px, height_px).
sort_by_variance (bool) – Sort axes by descending variance.
diag (Literal['scatter', 'density', 'none']) – Diagonal cell treatment - "density", "scatter", or "none".
point_size (float) – Size of the scatter points in off-diagonal cells.
point_alpha (float) – Transparency of the scatter points.
density_alpha (float) – Transparency of the density fill on the diagonal.

Return type:

Returns:

A Lets-Plot ggplot object with a faceted scatter matrix.

twiga.core.plot.exploration.correlation_heatmap(corr_df, title=None, caption='Twiga Forecast', show_x_axis=True, font_size=10, line_width=0.8, x_axis_angle=0, legend_pos='top', grid=False, fig_size=(500, 500), cmap_low='#E69F00', cmap_mid='#f7f7f7', cmap_high='#D55E00')#

Create a correlation heatmap from a long-form correlation DataFrame.

The input must contain columns col1, col2, and correlation, matching the output of twiga.core.stats.corr.CorrelationAnalyzer.

Parameters:

corr_df (DataFrame) – Long-form correlation data.
title (str | None) – Plot title.
caption (str) – Plot caption.
show_x_axis (bool) – Whether to render x-axis labels, ticks, and title.
font_size (int) – Base font size in points.
line_width (float) – Stroke width for axis lines and ticks.
x_axis_angle (int) – Rotation angle for x-axis tick labels.
legend_pos (Literal['top', 'bottom', 'left', 'right', 'none']) – Legend anchor - “top”, “bottom”, “left”, “right”, or “none”.
grid (bool) – If True, draw subtle horizontal reference lines.
fig_size (tuple[int, int]) – Figure size (width_px, height_px).
cmap_low (str) – Hex colour for the negative extreme.
cmap_mid (str) – Hex colour for zero.
cmap_high (str) – Hex colour for the positive extreme.

Return type:

Returns:

A Lets-Plot ggplot object.

Statistical & Evaluation Plots#

Functions for evaluating forecast quality — ACF, metric bar charts, reliability diagrams and PIT histograms.

twiga.core.plot.stats.plot_acf(series, *, max_lag=40, partial=False, alpha=0.05, title=None, x_label='Lag', caption='Twiga Forecast', show_x_axis=True, font_size=10, line_width=0.8, x_axis_angle=0, legend_pos='top', grid=False, fig_size=(640, 300), bar_width=1.0, point_size=2.5, ci_line_type='dashed', ci_line_color='#D55E00', ci_line_size=0.75, zero_line_color='#444444', zero_line_size=0.6)#

Autocorrelation (ACF) or partial autocorrelation (PACF) bar chart.

Computes the ACF/PACF via statsmodels and renders vertical bars with a 95 % confidence band (±1.96 / √n, dashed lines).

Parameters:

series (Series | ndarray) – 1-D time series (array or pandas Series).
max_lag (int) – Maximum lag to display.
partial (bool) – If True, compute PACF instead of ACF.
alpha (float) – Significance level for the confidence interval. Default 0.05 gives ±1.96 / √n bands.
title (str | None) – Plot title. Auto-generated from partial if None.
x_label (str) – X-axis label.
caption (str) – Plot caption.
show_x_axis (bool) – Whether to render x-axis labels, ticks, and title.
font_size (int) – Base font size in points.
line_width (float) – Stroke width for axis lines and ticks.
x_axis_angle (int) – Rotation angle for x-axis tick labels.
legend_pos (Literal['top', 'bottom', 'left', 'right', 'none']) – Legend anchor - “top”, “bottom”, “left”, “right”, or “none”.
grid (bool) – If True, draw subtle horizontal reference lines.
fig_size (tuple[int, int]) – Figure size (width_px, height_px).
bar_width (float) – Width of the vertical bars (passed as size to geom_segment).
point_size (float) – Size of the points drawn at the top of each bar.
ci_line_type (str) – Linetype for the confidence interval bands (e.g. “dashed”, “solid”).
ci_line_color (str) – Colour of the CI lines. Defaults to TWIGA_PALETTE[2] (vermilion).
ci_line_size (float) – Stroke width of the CI lines.
zero_line_color (str) – Colour of the horizontal line at zero.
zero_line_size (float) – Stroke width of the zero line.

Return type:

Returns:

A Lets-Plot ggplot object.

Examples

>>> from twiga.core.plot import plot_acf
>>> p = plot_acf(df["load"], max_lag=48, title="Load ACF")
>>> p

twiga.core.plot.stats.plot_metrics_bar(data, metric_col, *, model_col='Model', lower_is_better=True, title=None, x_label=None, caption='Twiga Forecast', horizontal=True, show_x_axis=True, font_size=10, line_width=0.8, x_axis_angle=0, legend_pos='top', grid=False, fig_size=(520, 340), bar_width=0.6, best_bar_color='#00BFA5', other_bar_color='#cfd8dc')#

Bar chart comparing a single metric across models.

The best model (lowest or highest value depending on lower_is_better) is highlighted in Twiga deep teal; all others use a muted grey.

Parameters:

data (DataFrame) – DataFrame with a model-name column and a numeric metric column.
metric_col (str) – Column of numeric metric values to plot.
model_col (str) – Column identifying each model.
lower_is_better (bool) – If True the minimum bar is highlighted in teal.
title (str | None) – Plot title.
x_label (str | None) – Axis label for the metric axis.
caption (str) – Plot caption.
horizontal (bool) – If True (default) renders a horizontal bar chart (models on y, metric on x).
show_x_axis (bool) – Whether to render x-axis labels, ticks, and title.
font_size (int) – Base font size in points.
line_width (float) – Stroke width for axis lines and ticks.
x_axis_angle (int) – Rotation angle for x-axis tick labels.
legend_pos (Literal['top', 'bottom', 'left', 'right', 'none']) – Legend anchor - “top”, “bottom”, “left”, “right”, or “none”.
grid (bool) – If True, draw subtle horizontal reference lines.
fig_size (tuple[int, int]) – Figure size (width_px, height_px).
bar_width (float) – Width of the bars (0–1, where 1 fills the whole bin).
best_bar_color (str) – Colour for the best model bar. Defaults to deep blue.
other_bar_color (str) – Colour for the non‑best bars.

Return type:

Returns:

A Lets-Plot ggplot object.

Examples

>>> from twiga.core.plot import plot_metrics_bar
>>> p = plot_metrics_bar(results, metric_col="MAE", title="MAE by Model", lower_is_better=True)
>>> p

twiga.core.plot.stats.plot_reliability_diagram(nominal, empirical, *, group_col=None, groups=None, title='Reliability Diagram', subtitle='Empirical vs nominal coverage - perfect calibration on the diagonal', caption='Twiga Forecast', show_x_axis=True, font_size=10, line_width=0.8, x_axis_angle=0, legend_pos='top', grid=False, fig_size=(440, 400), line_size=0.75, line_alpha=0.95, point_size=3.0, point_alpha=0.85, diagonal_line_color='#cccccc', diagonal_line_type='dashed', diagonal_line_size=0.75)#

Coverage reliability diagram for probabilistic forecasts.

Plots empirical coverage against nominal coverage levels. Points lying on the diagonal indicate perfect calibration; points above indicate conservative intervals (over-coverage); points below indicate anti-conservative intervals (under-coverage).

Parameters:

nominal (ndarray | list[float]) – Nominal coverage levels (x-axis), e.g. [0.5, 0.6, ..., 0.95].
empirical (ndarray | list[float]) – Empirical (observed) coverage at each level (y-axis). For multiple methods, pass a 2-D array of shape (n_levels, n_methods) and provide groups.
group_col (str | None) – Name to use for the group/method column when building the long-form DataFrame.
groups (list[str] | None) – Method names when empirical is 2-D.
title (str) – Plot title.
subtitle (str) – Plot subtitle.
caption (str) – Plot caption.
show_x_axis (bool) – Whether to render x-axis labels, ticks, and title.
font_size (int) – Base font size in points.
line_width (float) – Stroke width for axis lines and ticks.
x_axis_angle (int) – Rotation angle for x-axis tick labels.
legend_pos (Literal['top', 'bottom', 'left', 'right', 'none']) – Legend anchor - “top”, “bottom”, “left”, “right”, or “none”.
grid (bool) – If True, draw subtle horizontal reference lines.
fig_size (tuple[int, int]) – Figure size (width_px, height_px).
line_size (float) – Stroke width of the main lines (empirical coverage).
line_alpha (float) – Transparency of the main lines.
point_size (float) – Size of the markers at each coverage level.
point_alpha (float) – Transparency of the markers.
diagonal_line_color (str) – Colour of the perfect‑calibration diagonal.
diagonal_line_type (str) – Linetype of the diagonal (e.g. “dashed”, “solid”).
diagonal_line_size (float) – Stroke width of the diagonal.

Return type:

Returns:

A Lets-Plot ggplot object.

Examples

>>> from twiga.core.plot import plot_reliability_diagram
>>> p = plot_reliability_diagram(
...     nominal=np.linspace(0.1, 0.95, 18),
...     empirical=np.array([[cqr_cov], [crc_cov]]).T,
...     groups=["CQR", "CRC"],
... )
>>> p

twiga.core.plot.stats.plot_pit_histogram(pit_values, *, n_bins=20, title='PIT Histogram', subtitle='Uniform distribution indicates a well-calibrated forecast', caption='Twiga Forecast', show_x_axis=True, font_size=10, line_width=0.8, x_axis_angle=0, legend_pos='top', grid=False, fig_size=(500, 300), bar_fill_color='#00BFA5', bar_alpha=0.65, bar_width_factor=0.92, reference_line_color='#D55E00', reference_line_type='dashed', reference_line_size=0.75)#

Probability Integral Transform (PIT) histogram.

A diagnostic tool for probabilistic forecast calibration (Gneiting et al., 2007). PIT values that are U[0, 1] indicate a perfectly calibrated forecast.

Shape interpretation:

Flat → well-calibrated
U-shape → over-dispersed (intervals too wide)
Hump → under-dispersed (intervals too narrow / overconfident)
Skewed → systematic bias in the predicted distribution

Parameters:

pit_values (ndarray | Series) – 1-D array of PIT values in [0, 1].
n_bins (int) – Number of histogram bins.
title (str) – Plot title.
subtitle (str) – Plot subtitle.
caption (str) – Plot caption.
show_x_axis (bool) – Whether to render x-axis labels, ticks, and title.
font_size (int) – Base font size in points.
line_width (float) – Stroke width for axis lines and ticks.
x_axis_angle (int) – Rotation angle for x-axis tick labels.
legend_pos (Literal['top', 'bottom', 'left', 'right', 'none']) – Legend anchor - “top”, “bottom”, “left”, “right”, or “none”.
grid (bool) – If True, draw subtle horizontal reference lines.
fig_size (tuple[int, int]) – Figure size (width_px, height_px).
bar_fill_color (str) – Colour for the histogram bars. Defaults to deep blue.
bar_alpha (float) – Transparency of the bars.
bar_width_factor (float) – Fraction of the bin width to use for bar width (0–1).
reference_line_color (str) – Colour of the uniform reference line. Defaults to vermilion.
reference_line_type (str) – Linetype of the reference line.
reference_line_size (float) – Stroke width of the reference line.

Return type:

Returns:

A Lets-Plot ggplot object.

Examples

>>> from twiga.core.plot import plot_pit_histogram
>>> pit = compute_pit(y_true, predictive_cdf)
>>> p = plot_pit_histogram(pit, title="Normal Model - PIT")
>>> p