plot

skforecast.plot.plot.set_dark_theme

set_dark_theme(custom_style=None)

Set aspects of the visual theme for all matplotlib plots. This function changes the global defaults for all plots using the matplotlib rcParams system. The theme includes specific colors for figure and axes backgrounds, gridlines, text, labels, and ticks. It also sets the font size and line width.

Parameters:

Name	Type	Description	Default
custom_style	dict	Optional dictionary containing custom styles to be added or override the default dark theme. It is applied after the default theme is set by using the plt.rcParams.update() method.	None

Returns:

Type	Description
None

Source code in skforecast\plot\plot.py

def set_dark_theme(
    custom_style: dict | None = None
) -> None:
    """
    Set aspects of the visual theme for all matplotlib plots.
    This function changes the global defaults for all plots using the matplotlib
    rcParams system. The theme includes specific colors for figure and axes
    backgrounds, gridlines, text, labels, and ticks. It also sets the font size
    and line width.

    Parameters
    ----------
    custom_style : dict, default None
        Optional dictionary containing custom styles to be added or override the
        default dark theme. It is applied after the default theme is set by
        using the `plt.rcParams.update()` method.

    Returns
    -------
    None

    """

    plt.style.use('fivethirtyeight')
    dark_style = {
        'figure.facecolor': '#001633',
        'axes.facecolor': '#001633',
        'savefig.facecolor': '#001633',
        'axes.grid': True,
        'axes.grid.which': 'both',
        'axes.spines.left': False,
        'axes.spines.right': False,
        'axes.spines.top': False,
        'axes.spines.bottom': False,
        'grid.color': '#212946',
        'grid.linewidth': '1',
        'text.color': '0.9',
        'axes.labelcolor': '0.9',
        'xtick.color': '0.9',
        'ytick.color': '0.9',
        'font.size': 10,
        'lines.linewidth': 1.5
    }

    if custom_style is not None:
        dark_style.update(custom_style)

    plt.rcParams.update(dark_style)

skforecast.plot.plot.plot_residuals

plot_residuals(
    residuals=None,
    y_true=None,
    y_pred=None,
    fig=None,
    **fig_kw
)

Parameters:

Name	Type	Description	Default
residuals	pandas Series, numpy ndarray	Values of residuals. If None, residuals are calculated internally using y_true and y_true.	None.
y_true	pandas Series, numpy ndarray	Ground truth (correct) values. Ignored if residuals is not None.	None.
y_pred	pandas Series, numpy ndarray	Values of predictions. Ignored if residuals is not None.	None.
fig	Figure	Pre-existing fig for the plot. Otherwise, call matplotlib.pyplot.figure() internally.	None.
fig_kw	dict	Other keyword arguments are passed to matplotlib.pyplot.figure()	{}

Returns:

Name	Type	Description
fig	Figure	Matplotlib Figure.

Source code in skforecast\plot\plot.py

def plot_residuals(
    residuals: np.ndarray | pd.Series | None = None,
    y_true: np.ndarray | pd.Series | None = None,
    y_pred: np.ndarray | pd.Series | None = None,
    fig: matplotlib.figure.Figure | None = None,
    **fig_kw
) -> matplotlib.figure.Figure:
    """
    Parameters
    ----------
    residuals : pandas Series, numpy ndarray, default None.
        Values of residuals. If `None`, residuals are calculated internally using
        `y_true` and `y_true`.
    y_true : pandas Series, numpy ndarray, default None.
        Ground truth (correct) values. Ignored if residuals is not `None`.
    y_pred : pandas Series, numpy ndarray, default None. 
        Values of predictions. Ignored if residuals is not `None`.
    fig : matplotlib.figure.Figure, default None. 
        Pre-existing fig for the plot. Otherwise, call matplotlib.pyplot.figure()
        internally.
    fig_kw : dict
        Other keyword arguments are passed to matplotlib.pyplot.figure()

    Returns
    -------
    fig: matplotlib.figure.Figure
        Matplotlib Figure.

    """

    if residuals is None and (y_true is None or y_pred is None):
        raise ValueError(
            "If `residuals` argument is None then, `y_true` and `y_pred` must be provided."
        )

    if residuals is None:
        residuals = y_true - y_pred

    if fig is None:
        fig = plt.figure(constrained_layout=True, **fig_kw)

    gs  = matplotlib.gridspec.GridSpec(2, 2, figure=fig)
    ax1 = plt.subplot(gs[0, :])
    ax2 = plt.subplot(gs[1, 0])
    ax3 = plt.subplot(gs[1, 1])

    ax1.plot(residuals)
    sns.histplot(residuals, kde=True, bins=30, ax=ax2)
    plot_acf(residuals, ax=ax3, lags=60)

    ax1.set_title("Residuals")
    ax2.set_title("Distribution")
    ax3.set_title("Autocorrelation")

    return fig

skforecast.plot.plot.calculate_lag_autocorrelation

calculate_lag_autocorrelation(
    data,
    n_lags=50,
    last_n_samples=None,
    sort_by="partial_autocorrelation_abs",
    acf_kwargs={},
    pacf_kwargs={},
)

Calculate autocorrelation and partial autocorrelation for a time series. This is a wrapper around statsmodels.acf [1]_ and statsmodels.pacf [2]_.

Parameters:

Name	Type	Description	Default
data	pandas Series, pandas DataFrame	Time series to calculate autocorrelation. If a DataFrame is provided, it must have exactly one column.	required
n_lags	int	Number of lags to calculate autocorrelation.	50
last_n_samples	int or None	Number of most recent samples to use. If None, use the entire series. Note that partial correlations can only be computed for lags up to 50% of the sample size. For example, if the series has 10 samples, n_lags must be less than or equal to 5. This parameter is useful to speed up calculations when the series is very long.	None
sort_by	str	Sort results by 'lag', 'partial_autocorrelation_abs', 'partial_autocorrelation', 'autocorrelation_abs' or 'autocorrelation'.	'partial_autocorrelation_abs'
acf_kwargs	dict	Optional arguments to pass to statsmodels.tsa.stattools.acf.	{}
pacf_kwargs	dict	Optional arguments to pass to statsmodels.tsa.stattools.pacf.	{}

Returns:

Name	Type	Description
results	pandas DataFrame	Autocorrelation and partial autocorrelation values.

References

.. [1] Statsmodels acf API Reference. https://www.statsmodels.org/stable/generated/statsmodels.tsa.stattools.acf.html

.. [2] Statsmodels pacf API Reference. https://www.statsmodels.org/stable/generated/statsmodels.tsa.stattools.pacf.html

Examples:

import pandas as pd
from skforecast.plot import calculate_lag_autocorrelation

data = pd.Series([1, 2, 3, 4, 5, 6, 7, 8, 9, 10])
calculate_lag_autocorrelation(data = data, n_lags = 4)

#    lag  partial_autocorrelation_abs  partial_autocorrelation  autocorrelation_abs  autocorrelation
# 0    1                     0.777778                 0.777778             0.700000         0.700000
# 1    4                     0.360707                -0.360707             0.078788        -0.078788
# 2    3                     0.274510                -0.274510             0.148485         0.148485
# 3    2                     0.227273                -0.227273             0.412121         0.412121

Source code in skforecast\plot\plot.py

def calculate_lag_autocorrelation(
    data: pd.Series | pd.DataFrame,
    n_lags: int = 50,
    last_n_samples: int | None = None,
    sort_by: str = "partial_autocorrelation_abs",
    acf_kwargs: dict[str, object] = {},
    pacf_kwargs: dict[str, object] = {},
) -> pd.DataFrame:
    """
    Calculate autocorrelation and partial autocorrelation for a time series.
    This is a wrapper around statsmodels.acf [1]_ and statsmodels.pacf [2]_.

    Parameters
    ----------
    data : pandas Series, pandas DataFrame
        Time series to calculate autocorrelation. If a DataFrame is provided,
        it must have exactly one column.
    n_lags : int
        Number of lags to calculate autocorrelation.
    last_n_samples : int or None, default None
        Number of most recent samples to use. If None, use the entire series. 
        Note that partial correlations can only be computed for lags up to 
        50% of the sample size. For example, if the series has 10 samples, 
        `n_lags` must be less than or equal to 5. This parameter is useful
        to speed up calculations when the series is very long.
    sort_by : str, default 'partial_autocorrelation_abs'
        Sort results by 'lag', 'partial_autocorrelation_abs', 
        'partial_autocorrelation', 'autocorrelation_abs' or 'autocorrelation'.
    acf_kwargs : dict, default {}
        Optional arguments to pass to statsmodels.tsa.stattools.acf.
    pacf_kwargs : dict, default {}
        Optional arguments to pass to statsmodels.tsa.stattools.pacf.

    Returns
    -------
    results : pandas DataFrame
        Autocorrelation and partial autocorrelation values.

    References
    ----------
    .. [1] Statsmodels acf API Reference.
           https://www.statsmodels.org/stable/generated/statsmodels.tsa.stattools.acf.html

    .. [2] Statsmodels pacf API Reference.
           https://www.statsmodels.org/stable/generated/statsmodels.tsa.stattools.pacf.html

    Examples
    --------
    ```python
    import pandas as pd
    from skforecast.plot import calculate_lag_autocorrelation

    data = pd.Series([1, 2, 3, 4, 5, 6, 7, 8, 9, 10])
    calculate_lag_autocorrelation(data = data, n_lags = 4)

    #    lag  partial_autocorrelation_abs  partial_autocorrelation  autocorrelation_abs  autocorrelation
    # 0    1                     0.777778                 0.777778             0.700000         0.700000
    # 1    4                     0.360707                -0.360707             0.078788        -0.078788
    # 2    3                     0.274510                -0.274510             0.148485         0.148485
    # 3    2                     0.227273                -0.227273             0.412121         0.412121
    ```

    """

    if not isinstance(data, (pd.Series, pd.DataFrame)):
        raise TypeError(
            f"`data` must be a pandas Series or a DataFrame with a single column. "
            f"Got {type(data)}."
        )
    if isinstance(data, pd.DataFrame) and data.shape[1] != 1:
        raise ValueError(
            f"If `data` is a DataFrame, it must have exactly one column. "
            f"Got {data.shape[1]} columns."
        )
    if not isinstance(n_lags, int) or n_lags <= 0:
        raise TypeError(f"`n_lags` must be a positive integer. Got {n_lags}.")

    if last_n_samples is not None:
        if not isinstance(last_n_samples, int) or last_n_samples <= 0:
            raise TypeError(f"`last_n_samples` must be a positive integer. Got {last_n_samples}.")
        data = data.iloc[-last_n_samples:]

    if sort_by not in [
        "lag", "partial_autocorrelation_abs", "partial_autocorrelation",
        "autocorrelation_abs", "autocorrelation",
    ]:
        raise ValueError(
            "`sort_by` must be 'lag', 'partial_autocorrelation_abs', 'partial_autocorrelation', "
            "'autocorrelation_abs' or 'autocorrelation'."
        )

    pacf_values = pacf(data, nlags=n_lags, **pacf_kwargs)
    acf_values = acf(data, nlags=n_lags, **acf_kwargs)

    results = pd.DataFrame(
        {
            "lag": range(n_lags + 1),
            "partial_autocorrelation_abs": np.abs(pacf_values),
            "partial_autocorrelation": pacf_values,
            "autocorrelation_abs": np.abs(acf_values),
            "autocorrelation": acf_values,
        }
    ).iloc[1:]

    if sort_by == "lag":
        results = results.sort_values(by=sort_by, ascending=True).reset_index(drop=True)
    else:
        results = results.sort_values(by=sort_by, ascending=False).reset_index(drop=True)

    return results

skforecast.plot.plot.plot_multivariate_time_series_corr

plot_multivariate_time_series_corr(corr, ax=None, **fig_kw)

Heatmap plot of a correlation matrix.

Parameters:

Name	Type	Description	Default
corr	pandas DataFrame	correlation matrix	required
ax	Axes	Pre-existing ax for the plot. Otherwise, call matplotlib.pyplot.subplots() internally.	None
fig_kw	dict	Other keyword arguments are passed to matplotlib.pyplot.subplots()	{}

Returns:

Name	Type	Description
fig	Figure	Matplotlib Figure.

Source code in skforecast\plot\plot.py

def plot_multivariate_time_series_corr(
    corr: pd.DataFrame,
    ax: matplotlib.axes.Axes | None = None,
    **fig_kw
) -> matplotlib.figure.Figure:
    """
    Heatmap plot of a correlation matrix.

    Parameters
    ----------
    corr : pandas DataFrame
        correlation matrix
    ax : matplotlib.axes.Axes, default None
        Pre-existing ax for the plot. Otherwise, call matplotlib.pyplot.subplots() 
        internally.
    fig_kw : dict
        Other keyword arguments are passed to matplotlib.pyplot.subplots()

    Returns
    -------
    fig: matplotlib.figure.Figure
        Matplotlib Figure.

    """

    if ax is None:
        fig, ax = plt.subplots(1, 1, **fig_kw)

    sns.heatmap(
        corr,
        annot=True,
        linewidths=.5,
        ax=ax,
        cmap=sns.color_palette("viridis", as_cmap=True)
    )

    ax.set_xlabel('Time series')

    return fig

skforecast.plot.plot.plot_prediction_distribution

plot_prediction_distribution(
    bootstrapping_predictions, bw_method=None, **fig_kw
)

Ridge plot of bootstrapping predictions. This plot is very useful to understand the uncertainty of forecasting predictions.

Parameters:

Name	Type	Description	Default
bootstrapping_predictions	pandas DataFrame	Bootstrapping predictions created with Forecaster.predict_bootstrapping.	required
bw_method	(str, scalar, Callable)	The method used to calculate the estimator bandwidth. This can be 'scott', 'silverman', a scalar constant or a Callable. If None (default), 'scott' is used. See scipy.stats.gaussian_kde for more information.	None
fig_kw	dict	All additional keyword arguments are passed to the pyplot.figure call.	{}

Returns:

Name	Type	Description
fig	Figure	Matplotlib Figure.

Source code in skforecast\plot\plot.py

def plot_prediction_distribution(
    bootstrapping_predictions: pd.DataFrame,
    bw_method: Any | None = None,
    **fig_kw
) -> matplotlib.figure.Figure:
    """
    Ridge plot of bootstrapping predictions. This plot is very useful to understand 
    the uncertainty of forecasting predictions.

    Parameters
    ----------
    bootstrapping_predictions : pandas DataFrame
        Bootstrapping predictions created with `Forecaster.predict_bootstrapping`.
    bw_method : str, scalar, Callable, default None
        The method used to calculate the estimator bandwidth. This can be 'scott', 
        'silverman', a scalar constant or a Callable. If None (default), 'scott' 
        is used. See scipy.stats.gaussian_kde for more information.
    fig_kw : dict
        All additional keyword arguments are passed to the `pyplot.figure` call.

    Returns
    -------
    fig : matplotlib.figure.Figure
        Matplotlib Figure.

    """

    index = bootstrapping_predictions.index.astype(str).to_list()[::-1]
    palette = sns.cubehelix_palette(len(index), rot=-.25, light=.7, reverse=False)
    fig, axs = plt.subplots(len(index), 1, sharex=True, **fig_kw)
    if not isinstance(axs, np.ndarray):
        axs = np.array([axs])

    for i, step in enumerate(index):
        plot = (
            bootstrapping_predictions.loc[step, :]
            .plot.kde(ax=axs[i], bw_method=bw_method, lw=0.5)
        )

        # Fill density area
        x = plot.get_children()[0]._x
        y = plot.get_children()[0]._y
        axs[i].fill_between(x, y, color=palette[i])
        prediction_mean = bootstrapping_predictions.loc[step, :].mean()

        # Closest point on x to the prediction mean
        idx = np.abs(x - prediction_mean).argmin()
        axs[i].vlines(x[idx], ymin=0, ymax=y[idx], linestyle="dashed", color='w')

        axs[i].spines['top'].set_visible(False)
        axs[i].spines['right'].set_visible(False)
        axs[i].spines['bottom'].set_visible(False)
        axs[i].spines['left'].set_visible(False)
        axs[i].set_yticklabels([])
        axs[i].set_yticks([])
        axs[i].set_ylabel(step, rotation='horizontal')
        axs[i].set_xlabel('prediction')

    fig.subplots_adjust(hspace=-0)
    fig.suptitle('Forecasting distribution per step')

    return fig

skforecast.plot.plot.plot_prediction_intervals

plot_prediction_intervals(
    predictions,
    y_true,
    target_variable,
    initial_x_zoom=None,
    title=None,
    xaxis_title=None,
    yaxis_title=None,
    ax=None,
    kwargs_subplots={"figsize": (7, 3)},
    kwargs_fill_between={
        "color": "#444444",
        "alpha": 0.3,
        "zorder": 1,
    },
)

Plot predicted intervals vs real values using matplotlib.

Parameters:

Name	Type	Description	Default
predictions	pandas DataFrame	Predicted values and intervals. Expected columns are 'pred', 'lower_bound' and 'upper_bound'.	required
y_true	pandas Series, pandas DataFrame	Real values of target variable.	required
target_variable	str	Name of target variable.	required
initial_x_zoom	list	Initial zoom of x-axis, by default None.	None
title	str	Title of the plot, by default None.	None
xaxis_title	str	Title of x-axis, by default None.	None
yaxis_title	str	Title of y-axis, by default None.	None
ax	matplotlib axes	Axes where to plot, by default None.	None
kwargs_subplots	dict	Additional keyword arguments (key, value mappings) to pass to plt.subplots.	{'figsize': (7, 3)}
kwargs_fill_between	dict	Additional keyword arguments (key, value mappings) to pass to ax.fill_between.	{'color': '#444444', 'alpha': 0.3}

Returns:

Type	Description
None

Source code in skforecast\plot\plot.py

def plot_prediction_intervals(
    predictions: pd.DataFrame,
    y_true: pd.Series | pd.DataFrame,
    target_variable: str,
    initial_x_zoom: list[str] | None = None,
    title: str | None = None,
    xaxis_title: str | None = None,
    yaxis_title: str | None = None,
    ax: plt.Axes | None = None,
    kwargs_subplots: dict[str, object] = {'figsize': (7, 3)},
    kwargs_fill_between: dict[str, object] = {'color': '#444444', 'alpha': 0.3, 'zorder': 1}
):
    """
    Plot predicted intervals vs real values using matplotlib.

    Parameters
    ----------
    predictions : pandas DataFrame
        Predicted values and intervals. Expected columns are 'pred', 'lower_bound'
        and 'upper_bound'.
    y_true : pandas Series, pandas DataFrame
        Real values of target variable.
    target_variable : str
        Name of target variable.
    initial_x_zoom : list, default None
        Initial zoom of x-axis, by default None.
    title : str, default None
        Title of the plot, by default None.
    xaxis_title : str, default None
        Title of x-axis, by default None.
    yaxis_title : str, default None
        Title of y-axis, by default None.
    ax : matplotlib axes, default None
        Axes where to plot, by default None.
    kwargs_subplots : dict, default {'figsize': (7, 3)}
        Additional keyword arguments (key, value mappings) to pass to `plt.subplots`.
    kwargs_fill_between : dict, default {'color': '#444444', 'alpha': 0.3}
        Additional keyword arguments (key, value mappings) to pass to `ax.fill_between`.

    Returns
    -------
    None

    """

    if ax is None:
        fig, ax = plt.subplots(**kwargs_subplots)

    if isinstance(y_true, pd.Series):
        y_true = y_true.to_frame()

    y_true.loc[predictions.index, target_variable].plot(ax=ax, label='real value')
    predictions['pred'].plot(ax=ax, label='prediction')
    ax.fill_between(
        predictions.index,
        predictions['lower_bound'],
        predictions['upper_bound'],
        label='prediction interval',
        **kwargs_fill_between
    )
    ax.set_ylabel(yaxis_title)
    ax.set_xlabel(xaxis_title)
    ax.set_title(title)
    ax.legend()

    if initial_x_zoom is not None:
        ax.set_xlim(initial_x_zoom)