# -*- coding: utf-8 -*-
#
# Author: Taylor G Smith <taylor.smith@alkaline-ml.com>
#
# Plotting wrapper functions
from __future__ import absolute_import
from ..compat.pandas import plotting as pd_plotting
from ..compat.matplotlib import get_compatible_pyplot
from statsmodels.graphics import tsaplots
import os
# User may not have matplotlib
try:
# Gets the MPL.pyplot import (combatibilitized). Only use debug mode if set
# on the machine in an environment variable
debug = os.environ.get("PMDARIMA_MPL_DEBUG", "false").lower() == "true"
# If it's a Travis CI machine, we want to set the backend via env variable
backend = os.environ.get("PMD_MPL_BACKEND", None)
mpl = get_compatible_pyplot(backend=backend, debug=debug)
except ImportError:
mpl = None
__all__ = [
'autocorr_plot',
'decomposed_plot',
'plot_acf',
'plot_pacf'
]
def _err_for_no_mpl():
if mpl is None:
# Per Issue #47:
raise ImportError(
"You do not have matplotlib installed. In order to "
"create plots, you'll need to pip install matplotlib!")
def _get_plt():
"""Get MPL pyplot if it exists or raise an error if not"""
_err_for_no_mpl()
return mpl
def _show_or_return(obj, show):
if show:
# We never cover this in tests, unfortunately. Even with the
# cleanup tag, Travis doesn't play super nice with showing and
# closing lots of plots over and over. But it's just one line...
mpl.show()
# returns None implicitly
else:
return obj
[docs]def decomposed_plot(decomposed_tuple, figure_kwargs=None, show=True):
"""
Plot the decomposition of a time series.
This includes the 'x', 'trend', 'seasonal', and 'random' components.
Parameters
----------
decomposed_tuple : tuple
Tuple of series that consist of data, trend, seasonal, and random.
figure_kwargs : dict, optional (default=None)
Optional dictionary of keyword arguments that are passed to figure.
show : bool, optional (default=True)
Whether to show the plot after it's been created. If not, will return
the plot as an Axis object instead.
Notes
-----
This method will only show the plot if ``show=True`` (which is the default
behavior). To simply get the axis back (say, to add to another canvas),
use ``show=False``.
"""
_err_for_no_mpl()
fig, axes = mpl.subplots(4, 1, sharex=True, **figure_kwargs)
y_labels = ['data', 'trend', 'seasonal', 'random']
for ax in axes.flat:
ax.set(ylabel=y_labels.pop(0))
axes[0].plot(decomposed_tuple.x)
axes[1].plot(decomposed_tuple.trend)
axes[2].plot(decomposed_tuple.seasonal)
axes[3].plot(decomposed_tuple.random)
return _show_or_return(axes, show)
[docs]def autocorr_plot(series, show=True):
"""Plot a series' auto-correlation.
A wrapper method for the Pandas ``autocorrelation_plot`` method.
Parameters
----------
series : array-like, shape=(n_samples,)
The series or numpy array for which to plot an auto-correlation.
show : bool, optional (default=True)
Whether to show the plot after it's been created. If not, will return
the plot as an Axis object instead.
Notes
-----
This method will only show the plot if ``show=True`` (which is the default
behavior). To simply get the axis back (say, to add to another canvas),
use ``show=False``.
Examples
--------
>>> autocorr_plot([1, 2, 3], False) # doctest: +SKIP
<matplotlib.axes._subplots.AxesSubplot object at 0x127f41dd8>
Returns
-------
res : Axis or None
If ``show`` is True, does not return anything. If False, returns
the Axis object.
"""
_err_for_no_mpl()
res = pd_plotting.autocorrelation_plot(series)
return _show_or_return(res, show)
[docs]def plot_acf(series, ax=None, lags=None, alpha=None, use_vlines=True,
unbiased=False, fft=True, title='Autocorrelation',
zero=True, vlines_kwargs=None, show=True, **kwargs):
"""Plot a series' auto-correlation as a line plot.
A wrapper method for the statsmodels ``plot_acf`` method.
Parameters
----------
series : array-like, shape=(n_samples,)
The series or numpy array for which to plot an auto-correlation.
ax : Matplotlib AxesSubplot instance, optional
If given, this subplot is used to plot in instead of a new figure being
created.
lags : int, array-like or None, optional (default=None)
int or Array of lag values, used on horizontal axis. Uses
np.arange(lags) when lags is an int. If not provided,
``lags=np.arange(len(corr))`` is used.
alpha : scalar, optional (default=None)
If a number is given, the confidence intervals for the given level are
returned. For instance if alpha=.05, 95 % confidence intervals are
returned where the standard deviation is computed according to
Bartlett's formula. If None, no confidence intervals are plotted.
use_vlines : bool, optional (default=True)
If True, vertical lines and markers are plotted.
If False, only markers are plotted. The default marker is 'o'; it can
be overridden with a ``marker`` kwarg.
unbiased : bool, optional (default=False)
If True, then denominators for autocovariance are n-k, otherwise n
fft : bool, optional (default=True)
If True, computes the ACF via FFT.
title : str, optional (default='Autocorrelation')
Title to place on plot. Default is 'Autocorrelation'
zero : bool, optional (default=True)
Flag indicating whether to include the 0-lag autocorrelation.
Default is True.
vlines_kwargs : dict, optional (default=None)
Optional dictionary of keyword arguments that are passed to vlines.
show : bool, optional (default=True)
Whether to show the plot after it's been created. If not, will return
the plot as an Axis object instead.
**kwargs : kwargs, optional
Optional keyword arguments that are directly passed on to the
Matplotlib ``plot`` and ``axhline`` functions.
Notes
-----
This method will only show the plot if ``show=True`` (which is the default
behavior). To simply get the axis back (say, to add to another canvas),
use ``show=False``.
Examples
--------
>>> plot_acf([1, 2, 3], show=False) # doctest: +SKIP
<matplotlib.figure.Figure object at 0x122fab4e0>
Returns
-------
plt : Axis or None
If ``show`` is True, does not return anything. If False, returns
the Axis object.
"""
_err_for_no_mpl()
res = tsaplots.plot_acf(
x=series, ax=ax, lags=lags, alpha=alpha, use_vlines=use_vlines,
unbiased=unbiased, fft=fft, title=title, zero=zero,
vlines_kwargs=vlines_kwargs, **kwargs)
return _show_or_return(res, show)
[docs]def plot_pacf(series, ax=None, lags=None, alpha=None, method='yw',
use_vlines=True, title='Partial Autocorrelation', zero=True,
vlines_kwargs=None, show=True, **kwargs):
"""Plot a series' partial auto-correlation as a line plot.
A wrapper method for the statsmodels ``plot_pacf`` method.
Parameters
----------
series : array-like, shape=(n_samples,)
The series or numpy array for which to plot an auto-correlation.
ax : Matplotlib AxesSubplot instance, optional
If given, this subplot is used to plot in instead of a new figure being
created.
lags : int, array-like or None, optional (default=None)
int or Array of lag values, used on horizontal axis. Uses
np.arange(lags) when lags is an int. If not provided,
``lags=np.arange(len(corr))`` is used.
alpha : scalar, optional (default=None)
If a number is given, the confidence intervals for the given level are
returned. For instance if alpha=.05, 95 % confidence intervals are
returned where the standard deviation is computed according to
Bartlett's formula. If None, no confidence intervals are plotted.
method : str, optional (default='yw')
Specifies which method for the calculations to use. One of
{'ywunbiased', 'ywmle', 'ols', 'ld', 'ldb', 'ldunbiased', 'ldbiased'}:
- yw or ywunbiased : yule walker with bias correction in denominator
for acovf. Default.
- ywm or ywmle : yule walker without bias correction
- ols - regression of time series on lags of it and on constant
- ld or ldunbiased : Levinson-Durbin recursion with bias correction
- ldb or ldbiased : Levinson-Durbin recursion without bias correction
use_vlines : bool, optional (default=True)
If True, vertical lines and markers are plotted.
If False, only markers are plotted. The default marker is 'o'; it can
be overridden with a ``marker`` kwarg.
title : str, optional (default='Partial Autocorrelation')
Title to place on plot. Default is 'Partial Autocorrelation'
zero : bool, optional (default=True)
Flag indicating whether to include the 0-lag autocorrelation.
Default is True.
vlines_kwargs : dict, optional (default=None)
Optional dictionary of keyword arguments that are passed to vlines.
show : bool, optional (default=True)
Whether to show the plot after it's been created. If not, will return
the plot as an Axis object instead.
**kwargs : kwargs, optional
Optional keyword arguments that are directly passed on to the
Matplotlib ``plot`` and ``axhline`` functions.
Notes
-----
This method will only show the plot if ``show=True`` (which is the default
behavior). To simply get the axis back (say, to add to another canvas),
use ``show=False``.
Examples
--------
>>> plot_pacf([1, 2, 3, 4], show=False) # doctest: +SKIP
<matplotlib.figure.Figure object at 0x129df1630>
Returns
-------
plt : Axis or None
If ``show`` is True, does not return anything. If False, returns
the Axis object.
"""
_err_for_no_mpl()
res = tsaplots.plot_pacf(
x=series, ax=ax, lags=lags, alpha=alpha, method=method,
use_vlines=use_vlines, title=title, zero=zero,
vlines_kwargs=vlines_kwargs, **kwargs)
return _show_or_return(res, show)