Visualisations

forecast_evaluation.visualisations.apply_theme(fig, ax)

Apply the shared theme to a Matplotlib figure and axes.

forecast_evaluation.visualisations.create_themed_figure(nrows=1, ncols=1, **kwargs)

Create a matplotlib figure with theme applied from the start.

Parameters:

• nrows (int, default=1) – Number of subplot rows

• ncols (int, default=1) – Number of subplot columns

• **kwargs (dict) – Additional arguments passed to plt.subplots() (e.g., figsize, sharex, sharey)

Returns:

fig, ax – Figure and axes objects with theme applied

Return type:

tuple

forecast_evaluation.visualisations.plot_accuracy(df: DataFrame | TestResult, variable: str, metric: Literal['levels', 'pop', 'yoy'], frequency: Literal['Q', 'M'] = 'Q', statistic: Literal['rmse', 'rmedse', 'mse', 'mean_abs_error'] = 'rmse', convert_to_percentage: bool = False, return_plot: bool = False)

Plot accuracy statistic for all sources by forecast horizon for a specific variable and metric combination.

Creates a line plot showing how the selected accuracy statistic varies across forecast horizons for different forecast sources. The default statistic is RMSE, but other measures like RMEDSE, MSE, or MAE can be selected.

Parameters:

• df (DataFrame or AccuracyResults object) – containing accuracy statistics with columns ‘variable’, ‘source’, ‘metric’, ‘frequency’, ‘forecast_horizon’, ‘rmse’, ‘rmedse’, ‘mse’, ‘mean_abs_error’, ‘n_observations’, ‘start_date’, ‘end_date’.

• variable (str) – Variable to analyse (e.g., ‘gdpkp’, ‘cpisa’, ‘unemp’).

• metric (str) – Metric to analyse (‘levels’, ‘pop’, or ‘yoy’).

• frequency (str) – Data frequency (‘Q’ for quarterly or ‘M’ for monthly).

• statistic (str) – Accuracy statistic to plot (‘rmse’, ‘rmedse’, ‘mse’, or ‘mean_abs_error’).

• convert_to_percentage (bool) – If True, multiplies values on the y-axis by 100.

• return_plot (bool) – If True, returns (fig, ax) tuple instead of displaying the plot.

Returns:

If return_plot is True, returns the figure and axes objects. Otherwise, displays the plot and returns None.

Return type:

tuple of (matplotlib.figure.Figure, matplotlib.axes.Axes) or None

forecast_evaluation.visualisations.plot_average_revision_by_period(data, source, variable, metric, frequency, return_plot: bool = False)

Plot the average revision grouped by forecast_horizon.

Creates a line plot showing how the average size of forecast revisions varies by forecast horizon (periods until final revision).

Parameters:

• data (ForecastData) – ForecastData object containing forecasts data.

• source (str) – Forecast source identifier (e.g., ‘mpr’).

• variable (str) – Variable to analyse (e.g., ‘gdpkp’, ‘cpisa’).

• metric (str) – Metric to analyse (‘levels’, ‘pop’, or ‘yoy’).

• frequency (str) – Data frequency (‘Q’ for quarterly or ‘M’ for monthly).

• return_plot (bool, default False) – If True, returns (fig, ax) tuple instead of displaying the plot.

Returns:

If return_plot is True, returns the figure and axes objects. Otherwise, displays the plot and returns None.

Return type:

tuple of (matplotlib.figure.Figure, matplotlib.axes.Axes) or None

forecast_evaluation.visualisations.plot_bias_by_horizon(df: DataFrame | TestResult, variable: str, source: str, metric: Literal['levels', 'pop', 'yoy'], frequency: Literal['Q', 'M'], convert_to_percentage: bool = False, return_plot: bool = False)

Plot average forecast errors by forecast horizon, averaged over all forecast vintages.

Parameters:

• df (pd.DataFrame or TestResult) – Bias summary dataset generated with bias_analysis() or a BiasResults object.

• variable (str) – The variable to analyse (e.g., ‘gdpkp’, ‘cpisa’, ‘unemp’)

• source (str) – The source of the forecasts (e.g., ‘compass conditional’, ‘mpr’)

• metric (str) – The metric to analyse (e.g., ‘yoy’, ‘pop’, ‘levels’)

• frequency (str) – The frequency to analyse (e.g., ‘Q’, ‘M’)

• convert_to_percentage (bool, default=False) – If True, multiplies values on the y-axis by 100

• return_plot (bool, default=False) – If True, returns the matplotlib figure and axis objects

Returns:

If return_plot is True, returns (fig, ax). Otherwise, returns None.

Return type:

tuple or None

forecast_evaluation.visualisations.plot_blanchard_leigh_ratios(results: DataFrame | TestResult, return_plot: bool = False)

Plot Blanchard-Leigh efficiency test ratios across horizons with confidence intervals.

Parameters:

• results (DataFrame or BlanchardLeighResults) – DataFrame or BlanchardLeighResults object containing Blanchard-Leigh test results for multiple horizons. Expected columns include ‘horizon’, ‘outcome_variable’, ‘instrument_variable’, ‘ratio’, ‘ratio_se’, ‘ratio_ci_lower’, ‘ratio_ci_upper’, ‘alpha’.

• return_plot (bool, default False) – If True, returns (fig, ax) tuple instead of displaying the plot.

Returns:

If return_plot is True, returns the figure and axes objects. Otherwise, displays the plot and returns None.

Return type:

tuple of (matplotlib.figure.Figure, matplotlib.axes.Axes) or None

forecast_evaluation.visualisations.plot_compare_to_benchmark(df: DataFrame, variable: str, metric: Literal['levels', 'pop', 'yoy'], frequency: Literal['Q', 'M'], benchmark_model: str, statistic: Literal['rmse', 'rmedse', 'mean_abs_error'] = 'rmse', return_plot: bool = False)

Plot the ratio of each model’s accuracy statistic to a benchmark model’s statistic by forecast horizon.

Parameters:

• df (DataFrame) – containing accuracy statistics with columns ‘variable’, ‘source’, ‘metric’, ‘frequency’, ‘forecast_horizon’, ‘rmse’, ‘rmedse’, ‘mean_abs_error’, ‘n_observations’, ‘start_date’, ‘end_date’.

• variable (str) – Variable to analyse (e.g., ‘gdpkp’, ‘cpisa’, ‘unemp’).

• metric (str) – Metric to analyse (e.g., ‘yoy’, ‘levels’).

• frequency (str) – Data frequency (‘Q’ for quarterly or ‘M’ for monthly).

• benchmark_model (str) – The forecast source to use as the benchmark for comparison (e.g., ‘mpr’).

• statistic (str) – The accuracy statistic to compare (‘rmse’, ‘rmedse’, or ‘mean_abs_error’).

• return_plot (bool) – If True, returns (fig, ax) tuple instead of displaying the plot.

Returns:

If return_plot is True, returns the figure and axes objects. Otherwise, displays the plot and returns None.

Return type:

tuple of (matplotlib.figure.Figure, matplotlib.axes.Axes) or None

forecast_evaluation.visualisations.plot_errors_across_time(data: ForecastData, variable: str, metric: Literal['levels', 'pop', 'yoy'], error: Literal['raw', 'absolute', 'squared'] = 'raw', horizons: int | list[int] = None, sources: str | list[str] = None, frequency: Literal['Q', 'M'] = None, k: int = 12, ma_window: int = 1, show_mean: bool = True, convert_to_percentage: bool = False, return_plot: bool = False, custom_labels: dict = None, existing_plot: tuple = None)

Plot average forecast errors by forecast horizon, averaged over all forecast vintages.

Parameters:

• data (ForecastData) – ForecastData object containing forecast and outturn data.

• variable (str) – The variable to analyse (e.g., ‘gdpkp’, ‘cpisa’, ‘unemp’)

• metric (str) – The metric to analyse (e.g., ‘yoy’, ‘pop’, ‘levels’)

• error (str, default='raw') – The type of error to plot. Options are ‘raw’, ‘absolute’, or ‘squared’.

• horizons (int or list[int], default=None) – The forecast horizon(s) to analyse. If None, the minimum horizon in the data is used. If a list is provided, creates faceted subplots by horizon.

• sources (str or list[str], default=None) – The source(s) of the forecasts (e.g., ‘compass conditional’, ‘mpr’). If None, all sources in the data are used.

• frequency (str, default=None) – The frequency to analyse (e.g., ‘Q’, ‘M’). If None the most prevalent frequency in the data is used.

• k (int, default=12) – Number of revisions used to define the outturns.

• ma_window (int, default=1) – Size of moving average window to smooth the errors. By default, no smoothing is applied (ma_window=1).

• show_mean (bool, default=True) – If True, displays horizontal dashed lines showing the mean error for each source.

• convert_to_percentage (bool, default=False) – If True, multiplies values on the y-axis by 100

• return_plot (bool, default=False) – If True, returns the matplotlib figure and axis objects

• custom_labels (dict, default=None) – A dictionary mapping source names to custom labels for the legend.

• existing_plot (tuple, default=None) – A tuple (fig, axes) from a previous call to this function. If provided, new data is added to these axes.

Returns:

If return_plot is True, returns (fig, ax). Otherwise, returns None.

Return type:

tuple or None

forecast_evaluation.visualisations.plot_forecast_error_density(data: ForecastData, variable: str, horizon: int, metric: Literal['levels', 'pop', 'yoy'], frequency: Literal['Q', 'M'], source: str, k: int = 12, highlight_dates: str | list[str] | None = None, highlight_vintages: str | list[str] | None = None, return_plot: bool = False)

Plot density of forecast errors for a specific variable/source/vintage combination

Parameters:

• data (ForecastData) – ForecastData object containing forecast error data

• variable (str) – The variable to analyze (e.g., ‘gdpkp’)

• horizon (int) – The forecast horizon to analyze

• metric (str) – The metric to analyze (e.g., ‘yoy’, ‘pop’, ‘levels’)

• frequency (str) – The frequency to analyze (e.g., ‘Q’, ‘M’)

• source (str) – The source of the forecasts (e.g., ‘compass’)

• k (int) – The k to analyze (e.g., 12)

• highlight_dates (str or list of str, optional) – Date(s) to highlight (format: ‘YYYY-MM-DD’). If None, highlights last observation.

• highlight_vintages (str or list of str, optional) – Vintage date(s) to highlight (format: ‘YYYY-MM-DD’). Takes precedence over highlight_dates.

• return_plot (bool, default=False) – If True, returns the matplotlib figure and axis objects

Returns:

If return_plot is True, returns (fig, ax). Otherwise, returns None.

Return type:

tuple or None

forecast_evaluation.visualisations.plot_forecast_errors(data: ForecastData, variable: str, metric: Literal['levels', 'pop', 'yoy'], frequency: Literal['Q', 'M'], source: str, vintage_date_forecast: str, k: int = 12, convert_to_percentage: bool = False, return_plot: bool = False)

Plot average forecast errors for a specific variable/source/vintage combination

Parameters:

• data (ForecastData) – ForecastData object containing forecast accuracy data

• variable (str) – The variable to analyse (e.g., ‘gdpkp’)

• metric (str) – The metric to analyse (e.g., ‘yoy’, ‘pop’, ‘levels’)

• frequency (str) – The frequency to analyse (e.g., ‘Q’, ‘M’)

• source (str) – The source of the forecasts (e.g., ‘compass’)

• vintage_date_forecast (str) – The vintage_date of the forecasts (e.g., ‘2022-03-31’)

• k (int) – The k to analyse (e.g., 12)

• convert_to_percentage (bool, default=False) – If True, multiplies values on the y-axis by 100

• return_plot (bool, default=False) – If True, returns the matplotlib figure and axis objects

Returns:

If return_plot is True, returns (fig, ax). Otherwise, returns None.

Return type:

tuple or None

forecast_evaluation.visualisations.plot_forecast_errors_by_horizon(data: ForecastData, variable: str, source: str | list[str], metric: Literal['levels', 'pop', 'yoy'], frequency: Literal['Q', 'M'], k: int = 12, convert_to_percentage: bool = False, return_plot: bool = False)

Plot average forecast errors by forecast horizon, averaged over all forecast vintages.

Parameters:

• data (ForecastData) – ForecastData object containing forecast accuracy data

• variable (str) – The variable to analyze (e.g., ‘gdpkp’, ‘cpisa’, ‘unemp’)

• source (str or list of str) – The source(s) of the forecasts (e.g., ‘compass conditional’, or [‘compass conditional’, ‘mpr’]). When a list is provided, each source is plotted as a separate line on the same axes.

• metric (str) – The metric to analyze (e.g., ‘yoy’, ‘pop’, ‘levels’)

• frequency (str) – The frequency to analyze (e.g., ‘Q’, ‘M’)

• k (int) – The k to analyze (e.g., 12)

• convert_to_percentage (bool, default=False) – If True, multiplies values on the y-axis by 100

• return_plot (bool, default=False) – If True, returns the matplotlib figure and axis objects

Returns:

If return_plot is True, returns (fig, ax). Otherwise, returns None.

Return type:

tuple or None

forecast_evaluation.visualisations.plot_hedgehog(data: ForecastData, variable: str, forecast_source: str, metric: Literal['levels', 'pop', 'yoy'], frequency: Literal['Q', 'M'] = 'Q', k: int = 12, date_start: str | date | None = None, convert_to_percentage: bool = False, return_plot: bool = False) → None

Generate a hedgehog plot comparing forecasts with outturns.

A hedgehog plot displays multiple forecast vintages as light blue lines overlaid with the outturn values as a darker line with markers. This visualization helps assess forecast accuracy over time.

Parameters:

• data (ForecastData) – ForecastData object containing forecast and outturn data.

• variable (str) – Name of the variable to plot (e.g., ‘cpisa’, ‘gdpkp’).

• forecast_source (str) – Source of the forecasts.

• metric ({"levels", "pop", "yoy"}) – Type of transformation to apply to the data.

• frequency ({"Q", "M"}, default "Q") – Frequency of the data, either quarterly or monthly.

• k (int, default 12) – Number of revisions used to define the outturns.

• date_start (str, date, or None, default None) – Optional start date to filter the data. If None, no filtering is applied.

• convert_to_percentage (bool, default False) – If True, multiplies values on the y-axis by 100.

• return_plot (bool, default False) – If True, returns the matplotlib figure and axis objects.

Returns:

fig, ax – If return_plot is True, returns a tuple (fig, ax) of the matplotlib figure and axis objects. Otherwise, returns None.

Return type:

tuple or None

forecast_evaluation.visualisations.plot_outturn_revisions(data: ForecastData, variable: str, metric: Literal['levels', 'pop', 'yoy'], frequency: Literal['Q', 'M'], k: int | list[int] = 12, fill_k: bool = False, ma_window: int = 1, start_date: date | str = None, end_date: date | str = None, convert_to_percentage: bool = False, return_plot: bool = False)

Create outturn revisions plot.

Parameters:

• data (ForecastData) – ForecastData object containing forecast and outturn data.

• variable (str) – The variable to analyse (e.g., ‘gdpkp’, ‘cpisa’, ‘unemp’)

• metric (str) – The metric to analyse (e.g., ‘yoy’, ‘pop’, ‘levels’)

• frequency (str) – The frequency to analyse (e.g., ‘Q’, ‘M’)

• k (int or list of int, default=12) – Number of revisions used to define the outturns. Can be a single integer or a list of integers to compare multiple revision horizons on the same plot.

• fill_k (bool, default=False) – If True, uses only the latest vintage for each date when calculating revisions.

• ma_window (int, default=1) – Size of moving average window to smooth the revisions. By default, no smoothing is applied.

• start_date (date or str, default=None) – The start date for the plot. If None, uses the earliest date in the data.

• end_date (date or str, default=None) – The end date for the plot. If None, uses the latest date in the data.

• convert_to_percentage (bool, default=False) – If True, multiplies values on the y-axis by 100

• return_plot (bool, default=False) – If True, returns the matplotlib figure and axis objects

Returns:

If return_plot is True, returns (fig, ax). Otherwise, returns None.

Return type:

tuple or None

forecast_evaluation.visualisations.plot_outturns(data: ForecastData, variable: str, metric: Literal['levels', 'pop', 'yoy'], frequency: Literal['Q', 'M'], k: int | list[int] = 12, fill_k: bool = True, start_date: date | str = None, end_date: date | str = None, convert_to_percentage: bool = False, return_plot: bool = False)

Create outturns plot.

Parameters:

• data (ForecastData) – ForecastData object containing forecast and outturn data.

• variable (str) – The variable to analyse (e.g., ‘gdpkp’, ‘cpisa’, ‘unemp’)

• metric (str) – The metric to analyse (e.g., ‘yoy’, ‘pop’, ‘levels’)

• frequency (str) – The frequency to analyse (e.g., ‘Q’, ‘M’)

• start_date (date or str, default=None) – The start date for the plot. If None, uses the earliest date in the data.

• end_date (date or str, default=None) – The end date for the plot. If None, uses the latest date in the data.

• convert_to_percentage (bool, default=False) – If True, multiplies values on the y-axis by 100

• return_plot (bool, default=False) – If True, returns the matplotlib figure and axis objects

Returns:

If return_plot is True, returns (fig, ax). Otherwise, returns None.

Return type:

tuple or None

forecast_evaluation.visualisations.plot_rolling_bias(df: DataFrame, horizons: Sequence[int], variable: str = None, source: str = None, convert_to_percentage: bool = False, return_plot: bool = False)

Plot bias estimates with confidence intervals across window_end dates, faceted by forecast_horizon.

If the data contains fluctuation rejection columns (reject_05, reject_10), the bias estimates are marked with coloured dots indicating significance levels.

Parameters:

• df (pd.DataFrame) – Rolling bias summary dataset generated with rolling_analysis() with the analysis func bias_analysis.

• horizons (Sequence[int]) – List of forecast horizons to plot.

• variable (str, optional) – Variable to filter by. If None, uses the first variable found in the data.

• source (str, optional) – Source to filter by. If None, uses the first source found in the data.

• convert_to_percentage (bool, default False) – If True, multiplies bias estimates and confidence intervals by 100.

• return_plot (bool, default False) – If True, returns (fig, ax) tuple instead of displaying the plot.

Returns:

If return_plot is True, returns the figure and axes objects. Otherwise, displays the plot and returns None.

Return type:

tuple of (matplotlib.figure.Figure, matplotlib.axes.Axes) or None

forecast_evaluation.visualisations.plot_rolling_relative_accuracy(df: DataFrame, variable: str, horizons: list[int], return_plot: bool = False)

Plot RMSE ratio relative to benchmark across rolling windows, with significance levels indicated by dot colors.

Parameters:

• df (pd.DataFrame) – DataFrame with columns: variable, source, forecast_horizon, rmse_ratio, p_value, window_start, window_end

• variable (str) – Variable to plot (used for title)

• horizons (list[int]) – List of forecast horizons to include in the plot

• return_plot (bool) – If True, returns (fig, axes) instead of displaying

Returns:

(fig, axes) if return_plot=True, else None

Return type:

tuple or None

forecast_evaluation.visualisations.plot_strong_efficiency(results: DataFrame | TestResult, return_plot: bool = False)

Plot strong efficiency test coefficients across forecast horizons with confidence intervals.

This function creates a visualization of the strong efficiency test results, showing how the OLS coefficient (from regressing forecast errors on instrument variables) varies across different forecast horizons. The plot includes confidence intervals and a reference line at zero to assess statistical significance.

Parameters:

• results (DataFrame or StrongEfficiencyResults object containing strong efficiency test) – results for multiple horizons. Expected columns include ‘horizon’, ‘outcome_variable’, ‘instrument_variable’, ‘ols_coefficient’, ‘ols_se’, ‘coeff_ci_lower’, ‘coeff_ci_upper’, ‘n_observations’, ‘alpha’.

• return_plot (If True, returns (fig, ax) tuple instead of displaying the plot.)

Returns:

• tuple of (matplotlib.figure.Figure, matplotlib.axes.Axes) or None (If return_plot is True,)

• returns the figure and axes objects. Otherwise, displays the plot and returns None.

forecast_evaluation.visualisations.plot_vintage(data: ForecastData, variable: str, vintage_date: str | Timestamp, forecast_source: list[str] = None, outturn_start_date: str | Timestamp = None, frequency: Literal['Q', 'M'] = 'Q', metric: Literal['levels', 'pop', 'yoy'] = 'levels', k: int = 12, convert_to_percentage: bool = False, return_plot: bool = False) → None

Generate a plot comparing forecasts from different sources for a specific vintage.

Parameters:

• data (ForecastData) – ForecastData object containing forecast and outturn data.

• variable (str) – Name of the variable to plot.

• forecast_source (list of str) – List of forecast sources to include in the plot.

• vintage_date (str or pd.Timestamp) – The vintage date to plot, either as string or pandas Timestamp.

• outturn_start_date (str or pd.Timestamp, optional) – Start date for outturn data to display (inclusive). If None, all available outturns are used.

• frequency ({"Q", "M"}, default "Q") – Frequency of the data, either quarterly or monthly.

• metric ({"levels", "pop", "yoy"}, default "levels") – Type of transformation to apply to the data.

• convert_to_percentage (bool, default False) – If True, multiplies values on the y-axis by 100.

• return_plot (bool, default False) – If True, returns the matplotlib figure and axis objects.

Returns:

fig, ax – If return_plot is True, returns a tuple (fig, ax) of the matplotlib figure and axis objects. Otherwise, returns None.

Return type:

tuple or None