Core Functions

Core Functions#

forecast_evaluation.core.add_ar_p_forecasts(data: ForecastData, variable: str | Iterable[str] | None = None, metric: Literal['levels', 'diff', 'pop', 'yoy'] = 'levels', frequency: Literal['Q', 'M'] | Iterable[Literal['Q', 'M']] | None = None, forecast_periods: int = 13, *, estimation_start_date: Timestamp = Timestamp('1997-07-01 00:00:00'), show_progress: bool = False)[source]#

Wrapper function to build AR(p) model and add forecasts to ForecastData.

Parameters:

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

  • variable (str | Iterable[str] | None) – Variable name (e.g., ‘gdpkp’) or multiple variable names. If None, builds forecasts for all variable x frequency combinations present in the outturns.

  • metric (str, optional) – The metric to build the model for. Default is ‘levels’.

  • frequency (Literal["Q", "M"] | Iterable[Literal["Q", "M"]] | None, optional) – Frequency (or multiple frequencies) to build forecasts for. If None, frequencies are inferred from the outturns’ frequency column for the requested variable(s).

  • forecast_periods (int, optional) – Number of periods to forecast ahead. Default is 13.

  • estimation_start_date (pd.Timestamp, optional) – The date from which to start including data for model estimation. Default is ‘1997-07-01’. Set to None to include all data.

  • show_progress (bool, optional) – Whether to show progress bars. Default is False.

Returns:

The function modifies the ForecastData object in place by adding AR(p) forecasts.

Return type:

None

forecast_evaluation.core.add_random_walk_forecasts(data: ForecastData, variable: str | Iterable[str] | None = None, metric: Literal['levels', 'pop', 'yoy'] = 'levels', frequency: Literal['Q', 'M'] | Iterable[Literal['Q', 'M']] | None = None, forecast_periods: int = 13, show_progress: bool = False) → None[source]#

Add random walk forecasts to the ForecastData object.

Parameters:

  • data (ForecastData) – ForecastData object to which random walk forecasts will be added.

  • variable (str | Iterable[str] | None) – Variable name (e.g., ‘gdpkp’) or multiple variable names. If None, builds forecasts for all variable x frequency combinations present in the outturns.

  • metric (str, optional) – The metric to build the model for. Default is ‘levels’.

  • frequency (Literal["Q", "M"] | Iterable[Literal["Q", "M"]] | None, optional) – Frequency (or multiple frequencies) to build forecasts for. If None, frequencies are inferred from the outturns’ frequency column for the requested variable(s).

  • forecast_periods (int, optional) – Number of periods to forecast ahead. Default is 13.

  • show_progress (bool, optional) – Whether to show progress bars. Default is False.

Returns:

The function modifies the ForecastData object in place.

Return type:

None

forecast_evaluation.core.build_main_table(forecasts: DataFrame, outturns: DataFrame, id_columns: list[str], variables: str | list[str] = None, forecast_ids: str | list[str] = None, frequency: Literal['Q', 'M'] = 'Q') → DataFrame[source]#

Calculate the k-diagonal table for forecast evaluation.

Parameters:

  • forecasts (pd.DataFrame) – DataFrame containing forecast data.

  • outturns (pd.DataFrame) – DataFrame containing outturn data.

  • id_columns (list of str) – List of columns that uniquely identify a forecast.

  • variables (str or list of str, optional) – Name of the variable to analyse, or list of variable names.

  • forecast_ids (str or list of str, optional) – Single identifier or list of forecast identifier to include. Can be elements of column ‘source’ or extra_ids columns.

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

Returns:

Table containing forecast evaluation metrics with forecast errors and vintage information.

Return type:

pd.DataFrame

forecast_evaluation.core.create_outturn_revisions(data: ForecastData)[source]#

Create outturn revisions dataframe.

Parameters:

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

Returns:

DataFrame containing outturn revisions.

Return type:

pd.DataFrame

forecast_evaluation.core.create_revision_dataframe(main_df: DataFrame, forecasts: DataFrame, k: int = 12) → DataFrame[source]#

Create a merged DataFrame containing forecast revisions and forecast errors.

This function processes raw forecast data to calculate revisions (changes between consecutive vintage forecasts) and merges them with forecast error data for correlation analysis.

Parameters:

  • main_df (pd.DataFrame) – DataFrame containing forecasts, outturns and forecast errors.

  • forecasts (pd.DataFrame) – DataFrame containing forecast data with vintage information.

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

Returns:

Merged DataFrame with forecast revisions and errors.

Return type:

pd.DataFrame