Module futureexpert.plot

Contains all the functionality to plot the checked in time series and the forecast and backtesting results.

Functions

def create_multiple_yaxis(count_y_axis: int) ‑> dict[str, typing.Any]

Expand source code

def create_multiple_yaxis(count_y_axis: int) -> dict[str, Any]:
    """Create multiple yaxis for interactive plots.

    Parameters
    ----------
    count_y_axis: builtins.int
        Number of how many yaxis are needed.
    return: builtins.dict[builtins.str, typing.Any]

    """
    return {
        f"yaxis{'' if ax == 0 else ax+1}": {
            "showticklabels": False,
            "overlaying": None if ax == 0 else "y",
        }
        for ax in range(count_y_axis)
    }

Create multiple yaxis for interactive plots.

Parameters

count_y_axis : builtins.int

Number of how many yaxis are needed.

return : builtins.dict[builtins.str, typing.Any]

 

def filter_models(models: list[Model],
ranks: list[int] | None = [1],
model_names: list[str] | None = None) ‑> list[Model]

Expand source code

def filter_models(models: list[Model],
                  ranks: Optional[list[int]] = [1],
                  model_names: Optional[list[str]] = None,) -> list[Model]:
    """Filter models based on the given criteria.

    Parameters
    ----------
    models: builtins.list[futureexpert.forecast.Model]
        List of models.
    model_names: typing.Optional[builtins.list[builtins.str]]
        Names of the models to filtered by.
    ranks: typing.Optional[builtins.list[builtins.int]]
        Ranks of the models to filtered by.
    return: builtins.list[futureexpert.forecast.Model]

    """
    if model_names:
        models = [mo for mo in models if mo.model_name in model_names]
    if ranks:
        models = [mo for mo in models if mo.model_selection.ranking and mo.model_selection.ranking.rank_position in ranks]

    return models

Filter models based on the given criteria.

Parameters

models : builtins.list[Model]

List of models.

model_names : typing.Optional[builtins.list[builtins.str]]

Names of the models to filtered by.

ranks : typing.Optional[builtins.list[builtins.int]]

Ranks of the models to filtered by.

return : builtins.list[Model]

 

def plot_backtesting(result: ForecastResult,
iteration: int = 1,
plot_last_x_data_points_only: int | None = None,
model_names: list[str] | None = None,
ranks: list[int] | None = [1],
plot_prediction_intervals: bool = True,
plot_outliers: bool = False,
plot_change_points: bool = False,
plot_replaced_missings: bool = False,
plot_covariates: bool = False,
as_interactive: bool = False) ‑> None

Expand source code

def plot_backtesting(result: ForecastResult,
                     iteration: int = 1,
                     plot_last_x_data_points_only: Optional[int] = None,
                     model_names: Optional[list[str]] = None,
                     ranks: Optional[list[int]] = [1],
                     plot_prediction_intervals: bool = True,
                     plot_outliers: bool = False,
                     plot_change_points: bool = False,
                     plot_replaced_missings: bool = False,
                     plot_covariates: bool = False,
                     as_interactive: bool = False) -> None:
    """Plots actuals and backtesting results from a single time series.

    Parameters
    ----------
    result: futureexpert.forecast.ForecastResult
        Forecasting and backtesting results of a single time series and model.
    iteration: builtins.int
        Iteration of the backtesting forecast.
    plot_last_x_data_points_only: typing.Optional[builtins.int]
        Number of data points of the actuals that should be shown in the plot.
    model_names: typing.Optional[builtins.list[builtins.str]]
        Names of the models to plot.
    ranks: typing.Optional[builtins.list[builtins.int]]
        Ranks of the models to plot.
    plot_prediction_intervals: builtins.bool
        Shows prediction intervals.
    plot_outliers: builtins.bool
        Shows outlieres and replacement values.
    plot_change_points: builtins.bool
        Shows change point like level shifts and few observations.
    plot_replaced_missings: builtins.bool
        Shows replaced missing values.
    plot_covariates: builtins.bool
        Shows the covariates that where used in the model.
    as_interactive: builtins.bool
        Plots the data in an interactive plot or as static image.
    return: builtins.NoneType

    """
    plot_models = filter_models(result.models, ranks, model_names)
    df_ac = _prepare_actuals(result.input.actuals, plot_last_x_data_points_only)

    plot_few_observations = []
    if plot_change_points:

        change_points = result.ts_characteristics.change_points or []
        few_observations = [copy.deepcopy(x) for x in change_points if x.change_point_type.startswith('FEW_OBS')]

        plot_few_observations = _calculate_few_observation_borders(df_ac.date.tolist(), few_observations)

        level_shifts = [x for x in change_points if x.change_point_type == 'LEVEL_SHIFT']
        df_ac = _add_level_shifts(df_ac, level_shifts)

    if plot_outliers:
        outliers = result.ts_characteristics.outliers or []
        df_ac = _add_outliers(df_ac, outliers, result.changed_values)

    df_ac = _add_changed_start_date(df_ac, result.changed_start_date)

    missing_borders = []
    if plot_replaced_missings:
        df_ac = _add_replaced_missings(df_ac, result.changed_values)
        if 'replaced_missing' in df_ac.columns:
            missing_borders = _calculate_replaced_missing_borders(df_ac)

    for model in plot_models:

        assert model.model_selection.backtesting, \
            'Cannot create backtesting plot, at least one model has no backtesting results available.'
        assert model.model_selection.ranking, 'No ranking, plotting not possible.'
        df_bt = _prepare_backtesting(model, iteration)

        title = f'Backtesting of {result.input.actuals.name} - Iteration: {iteration}'
        subtitle = f'using {model.model_name} (Rank {model.model_selection.ranking.rank_position})'

        if plot_covariates and len(model.covariates) > 0:
            df_concat = _add_covariates(df_ac, model.covariates, result.input.covariates,
                                        _calculate_max_covariate_date(result.input.actuals.granularity, df_ac.date.max()))
        else:
            df_concat = df_ac

        if as_interactive:
            _create_interactive_backtesting_plot(title=title,
                                                 subtitle=subtitle,
                                                 df_concat=df_concat, df_bt=df_bt,
                                                 missing_borders=missing_borders,
                                                 plot_prediction_intervals=plot_prediction_intervals,
                                                 plot_few_observations=plot_few_observations)
        else:
            _create_static_backtesting_plot(title=title,
                                            subtitle=subtitle,
                                            df_concat=df_concat,
                                            df_bt=df_bt,
                                            plot_prediction_intervals=plot_prediction_intervals,
                                            plot_few_observations=plot_few_observations)

Plots actuals and backtesting results from a single time series.

Parameters

result : ForecastResult

Forecasting and backtesting results of a single time series and model.

iteration : builtins.int

Iteration of the backtesting forecast.

plot_last_x_data_points_only : typing.Optional[builtins.int]

Number of data points of the actuals that should be shown in the plot.

model_names : typing.Optional[builtins.list[builtins.str]]

Names of the models to plot.

ranks : typing.Optional[builtins.list[builtins.int]]

Ranks of the models to plot.

plot_prediction_intervals : builtins.bool

Shows prediction intervals.

plot_outliers : builtins.bool

Shows outlieres and replacement values.

plot_change_points : builtins.bool

Shows change point like level shifts and few observations.

plot_replaced_missings : builtins.bool

Shows replaced missing values.

plot_covariates : builtins.bool

Shows the covariates that where used in the model.

as_interactive : builtins.bool

Plots the data in an interactive plot or as static image.

return : builtins.NoneType

 

def plot_forecast(result: ForecastResult,
plot_last_x_data_points_only: int | None = None,
model_names: list[str] | None = None,
ranks: list[int] | None = [1],
plot_prediction_intervals: bool = True,
plot_outliers: bool = False,
plot_change_points: bool = False,
plot_replaced_missings: bool = False,
plot_covariates: bool = False,
as_interactive: bool = False) ‑> None

Expand source code

def plot_forecast(result: ForecastResult,
                  plot_last_x_data_points_only: Optional[int] = None,
                  model_names: Optional[list[str]] = None,
                  ranks: Optional[list[int]] = [1],
                  plot_prediction_intervals: bool = True,
                  plot_outliers: bool = False,
                  plot_change_points: bool = False,
                  plot_replaced_missings: bool = False,
                  plot_covariates: bool = False,
                  as_interactive: bool = False) -> None:
    """Plots actuals and forecast from a single time series.

    Parameters
    ----------
    forecasts
        Forecasting results of a single time series and model.
    plot_last_x_data_points_only: typing.Optional[builtins.int]
        Number of data points of the actuals that should be shown in the plot.
    model_names: typing.Optional[builtins.list[builtins.str]]
        Names of the models to plot.
    ranks: typing.Optional[builtins.list[builtins.int]]
        Ranks of the models to plot.
    plot_prediction_intervals: builtins.bool
        Shows prediction intervals.
    plot_outliers: builtins.bool
        Shows outlieres and replacement values.
    plot_change_points: builtins.bool
        Shows change point like level shifts and few observations.
    plot_replaced_missings: builtins.bool
        Shows replaced missing values.
    plot_covariates: builtins.bool
        Shows the covariates that where used in the model.
    as_interactive: builtins.bool
        Plots the data in an interactive plot or as static image.
    result: futureexpert.forecast.ForecastResult

    return: builtins.NoneType

    """

    df_ac = _prepare_actuals(actuals=result.input.actuals,
                             plot_last_x_data_points_only=plot_last_x_data_points_only)
    name = result.input.actuals.name
    plot_models = filter_models(result.models, ranks, model_names)

    plot_few_observations = []
    if plot_change_points:
        change_points = result.ts_characteristics.change_points or []
        few_observations = [copy.deepcopy(x) for x in change_points if x.change_point_type.startswith('FEW_OBS')]

        plot_few_observations = _calculate_few_observation_borders(df_ac.date.tolist(), few_observations)

        level_shifts = [x for x in change_points if x.change_point_type == 'LEVEL_SHIFT']
        df_ac = _add_level_shifts(df_ac, level_shifts)

    if plot_outliers:
        outliers = result.ts_characteristics.outliers or []
        df_ac = _add_outliers(df_ac, outliers, result.changed_values)

    df_ac = _add_changed_start_date(df_ac, result.changed_start_date)

    missing_borders = []
    if plot_replaced_missings:
        df_ac = _add_replaced_missings(df_ac, result.changed_values)
        if 'replaced_missing' in df_ac.columns:
            missing_borders = _calculate_replaced_missing_borders(df_ac)

    for model in plot_models:
        assert model.model_selection.ranking, 'No ranking, plotting not possible.'
        df_concat = _add_forecast(df_ac, model)
        title = f'Forecast for {name}'
        subtitle = f'using {model.model_name} (Rank {model.model_selection.ranking.rank_position})'

        if plot_covariates and len(model.covariates) > 0:
            df_concat = _add_covariates(df_concat, model.covariates, result.input.covariates, df_concat.date.max())

        if as_interactive:
            _create_interactive_forecast_plot(title=title,
                                              subtitle=subtitle,
                                              df_concat=df_concat,
                                              missing_borders=missing_borders,
                                              plot_prediction_intervals=plot_prediction_intervals,
                                              plot_few_observations=plot_few_observations)
        else:
            _create_static_forecast_plot(title=title,
                                         subtitle=subtitle,
                                         df_concat=df_concat,
                                         plot_prediction_intervals=plot_prediction_intervals,
                                         plot_few_observations=plot_few_observations)

Plots actuals and forecast from a single time series.

Parameters

forecasts

Forecasting results of a single time series and model.

plot_last_x_data_points_only : typing.Optional[builtins.int]

Number of data points of the actuals that should be shown in the plot.

model_names : typing.Optional[builtins.list[builtins.str]]

Names of the models to plot.

ranks : typing.Optional[builtins.list[builtins.int]]

Ranks of the models to plot.

plot_prediction_intervals : builtins.bool

Shows prediction intervals.

plot_outliers : builtins.bool

Shows outlieres and replacement values.

plot_change_points : builtins.bool

Shows change point like level shifts and few observations.

plot_replaced_missings : builtins.bool

Shows replaced missing values.

plot_covariates : builtins.bool

Shows the covariates that where used in the model.

as_interactive : builtins.bool

Plots the data in an interactive plot or as static image.

result : ForecastResult

 

return : builtins.NoneType

 

def plot_time_series(ts: TimeSeries,
covariate: list[Covariate] | None = None,
plot_last_x_data_points_only: int | None = None,
as_interactive: bool = False) ‑> None

Expand source code

def plot_time_series(ts: TimeSeries,
                     covariate: Optional[list[Covariate]] = None,
                     plot_last_x_data_points_only: Optional[int] = None,
                     as_interactive: bool = False) -> None:
    """Plots actuals from a single time series. Optional a Covariate can be plotted next to it.

    Parameters
    ----------
    ts: futureexpert.shared_models.TimeSeries
        time series data
    covariate: typing.Optional[builtins.list[futureexpert.shared_models.Covariate]]
        covariate data
    plot_last_x_data_points_only: typing.Optional[builtins.int]
        Number of data points of the actuals that should be shown in the plot.
    as_interactive: builtins.bool
        Plots the data as an interactive plot or as static image.
    return: builtins.NoneType

    """
    df_ac = _prepare_actuals(actuals=ts, plot_last_x_data_points_only=plot_last_x_data_points_only)
    name = ts.name

    if covariate:
        df_ac = _add_covariates(df_ac, covariate, covariate,
                                _calculate_max_covariate_date(ts.granularity, df_ac.date.max()))

    if as_interactive:
        _create_interactive_time_series_plot(df_ac, name)
    else:
        _create_static_time_series_plot(df_ac, name)

Plots actuals from a single time series. Optional a Covariate can be plotted next to it.

Parameters

ts : TimeSeries

time series data

covariate : typing.Optional[builtins.list[Covariate]]

covariate data

plot_last_x_data_points_only : typing.Optional[builtins.int]

Number of data points of the actuals that should be shown in the plot.

as_interactive : builtins.bool

Plots the data as an interactive plot or as static image.

return : builtins.NoneType