pytsviz.viz module¶
The viz module contains functions to visualize most of the key aspects of a univariate time series such as (partial) correlograms, periodograms, line plots, …
-
pytsviz.viz.
_plot_plotly
(df, kind, x_title=None, y_title=None, x_type=None, y_type=None, **kwargs)¶ Wrapper for pandas plot function, with plotly backend and the application of the default styling template.
- Parameters
df (
DataFrame
) – Dataframe to use as the data source for the plot.kind (
str
) – The kind of plot to produce.x_type (
Optional
[Literal
[‘linear’, ‘log’, ‘date’, ‘category’, ‘multicategory’]]) – If provided, enforces the x axis data type. Can be one of ‘linear’, ‘log’, ‘date’, ‘category’, ‘multicategory’.y_type (
Optional
[Literal
[‘linear’, ‘log’, ‘date’, ‘category’, ‘multicategory’]]) – If provided, enforces the y axis data type. Can be one of ‘linear’, ‘log’, ‘date’, ‘category’, ‘multicategory’.kwargs (
Any
) – Keyword arguments for pandas.plot.
- Return type
- Returns
Plotly figure.
-
pytsviz.viz.
plot_acf
(df, y_col=None, time_col=None, partial=False, n_lags=None, title=None, show_threshold=True, show=True, **kwargs)¶ Interactive bar plot of the auto-correlation function of a time series up to a certain lag.
- Parameters
df (
DataFrame
) – Dataframe to use as the data source for the plot.y_col (
Optional
[str
]) – Name of the column from df to be used as time series values in the plot.time_col (
Optional
[str
]) – Name of the column from df to be used as time variable in the plot.partial (
bool
) – Whether to use the partial auto-correlation function.n_lags (
Optional
[int
]) – Maximum number of time steps to consider as lag.show_threshold (
bool
) – Whether to compute the ACF significance threshold, defined as the 95% confidence upper bound of a time series which has no auto-correlation, and show it as a horizontal line in the plot.show (
bool
) – Whether to callFigure.show
at the end of the function. IfFalse
, returns the figure.
- Return type
- Returns
Plotly figure if show is
True
, else nothing.
-
pytsviz.viz.
plot_decomposed_ts
(df, method, y_col=None, time_col=None, title=None, subplots=True, show=True, **decomp_kwargs)¶ Interactive plot of a decomposition of a time series.
- Parameters
df (
DataFrame
) – Dataframe to use as the data source for the plot.method (
Literal
[‘STL’, ‘seasonal_additive’, ‘seasonal_multiplicative’]) – Method of decomposition. It can be one of “STL”, “seasonal_additive” or “seasonal_multiplicative”.y_col (
Optional
[str
]) – Name of the column from df to be used as time series values in the plot.time_col (
Optional
[str
]) – Name of the column from df to be used as time variable in the plot.subplots (
bool
) – Whether to split the decomposition components into subplots.show (
bool
) – Whether to callFigure.show
at the end of the function. IfFalse
, returns the figure.decomp_kwargs (
Any
) – Keyword arguments for the selected decomposition method. See method for details.
- Return type
- Returns
Plotly figure if show is
True
, else nothing.
-
pytsviz.viz.
plot_distribution
(df, y_col=None, time_col=None, bins=None, title=None, show=True)¶ Interactive histogram of a time series. Useful to assess marginal distribution shape.
- Parameters
df (
DataFrame
) – Dataframe to use as the data source for the plot.y_col (
Optional
[str
]) – Name of the column from df to be used as time series values in the plot.time_col (
Optional
[str
]) – Name of the column from df to be used as time variable in the plot.show (
bool
) – Whether to callFigure.show
at the end of the function. IfFalse
, returns the figure.
- Return type
- Returns
Plotly figure if show is
True
, else nothing.
-
pytsviz.viz.
plot_extended_scatter_matrix
(df, time_col=None, y_cols=None, title=None, show=True)¶ Composite plot containing scatter matrix, distributions and couple-correlations of a set of time series.
- Parameters
df (
DataFrame
) – Dataframe to use as the data source for the plot.y_cols (
Optional
[List
[str
]]) – Name of the columns from df to be used as variables in the plot. IfNone
, all columns are used.time_col (
Optional
[str
]) – Name of the column from df to be used as time variable in the plot.show (
bool
) – Whether to callFigure.show
at the end of the function. IfFalse
, returns the figure.
- Return type
- Returns
Plotly figure if show is
True
, else nothing.
-
pytsviz.viz.
plot_forecast
(df, y_col, y_hat_cols, lower_col=None, upper_col=None, time_col=None, title=None, show=True)¶ Interactive plot of a time series forecast (or multiple forecasts).
- Parameters
df (
DataFrame
) – Dataframe to use as the data source for the plot.y_col (
str
) – Name of the column from df to be used as time series values in the plot.time_col (
Optional
[str
]) – Name of the column from df to be used as time variable in the plot.y_hat_cols (
List
[str
]) – Name of the columns from df to be used as forecasts for the time series in the plot.lower_col (
Optional
[str
]) – If given, name of the column to be used as lower confidence bound for the forecast.upper_col (
Optional
[str
]) – If given, name of the column to be used as upper confidence bound for the forecast.show (
bool
) – Whether to callFigure.show
at the end of the function. IfFalse
, returns the figure.
- Return type
- Returns
Plotly figure if show is
True
, else nothing.
-
pytsviz.viz.
plot_gof
(df, y_col, y_hat_col, time_col=None, acf_n_lags=None, pacf_n_lags=None, alpha=0.1, title='Goodness of Fit', subplot_titles=('Actual vs Predicted Series', 'Actual vs Predicted Scatter', 'Residuals', 'Residuals ACF', 'Residuals PACF'), show=True)¶ Interactive plot of goodness of fit visualizations. In order: Actual Series vs Predicted Series, Residuals series, and Actual vs Predicted scatter plot.
- Parameters
acf_n_lags (
Optional
[int
]) – Maximum number of time steps to consider as lag for ACF.pacf_n_lags (
Optional
[int
]) – Maximum number of time steps to consider as lag for PACF.df (
DataFrame
) – Dataframe to use as the data source for the plot.y_col (
str
) – Name of the column from df to be used as time series values in the plot.time_col (
Optional
[str
]) – Name of the column from df to be used as time variable in the plot.y_hat_col (
str
) – Name of the column from df to be used as forecast for the time series in the plot.alpha (
float
) – If a number is given, the confidence intervals for the given level are displayed in the plot.title (
str
) – Plot title.subplot_titles (
Tuple
[str
,str
,str
,str
,str
]) – Tuple of titles for each of the 3 subplots.show (
bool
) – Whether to callFigure.show
at the end of the function. IfFalse
, returns the figure.
- Return type
- Returns
Tuple of plotly figures if show is
True
, else nothing.
-
pytsviz.viz.
plot_inverse_arma_roots
(process, show=True)¶ Plot of the inverse roots of a given ARMA process.
- Parameters
process (
ArmaProcess
) – The ARMA process (statsmodels.tsa.ArmaProcess) for which the roots are computed.show (
bool
) – Whether to callFigure.show
at the end of the function. IfFalse
, returns the figure.
- Return type
- Returns
Plotly figure if show is
True
, else nothing.
-
pytsviz.viz.
plot_psd
(df, y_col=None, time_col=None, nfft=None, fs=1, min_period=0, max_period=inf, plot_time=False, title=None, show=True, **kwargs)¶ Interactive histogram of the spectral density of a time series.
- Parameters
df (
DataFrame
) – Dataframe to use as the data source for the plot.y_col (
Optional
[str
]) – Name of the column from df to be used as time series values in the plot.time_col (
Optional
[str
]) – Name of the column from df to be used as time variable in the plot.show (
bool
) – Whether to callFigure.show
at the end of the function. IfFalse
, returns the figure.nfft (
Optional
[int
]) – Length of the FFT used. IfNone
the length of df will be used.fs (
int
) – Sampling frequency of df.min_period (
int
) – Minimum period to consider.max_period (
int
) – Maximum period to consider.plot_time (
bool
) – IfTrue
, plot time on the x axis, else plot sampling frequency.
- Return type
- Returns
Plotly figure if show is
True
, else nothing.
-
pytsviz.viz.
plot_scatter_fit
(df, x_col, y_col, time_col=None, title=None, fit=False, show=True, **kwargs)¶ Interactive scatter plot between two time series with possibility of showing a fit line between them.
- Parameters
df (
DataFrame
) – Dataframe to use as the data source for the plot.x_col (
str
) – Name of the column from df to be used as x variable in the scatter plot.y_col (
str
) – Name of the column from df to be used as y variable in the scatter plot.time_col (
Optional
[str
]) – Name of the column from df to be used as time variable in the plot.fit (
Union
[bool
,Literal
[‘summary’]]) – Whether to show the fit line in the plot. If set to “summary”, displays fit statistics at the bottom.show (
bool
) – Whether to callFigure.show
at the end of the function. IfFalse
, returns the figure.kwargs – Keyword arguments for fit, if not set to
False
. They are passed topandas.plot
.
- Return type
- Returns
Plotly figure if show is
True
, else nothing.
-
pytsviz.viz.
plot_scatter_matrix
(df, x_col, y_col=None, lags_x=None, lags_y=None, time_col=None, title=None, show=True)¶ Interactive scatter matrix plot of a set of variables and possibly lagged versions of them.
- Parameters
df (
DataFrame
) – Dataframe to use as the data source for the plot.x_col (
str
) – Name of the column to be used as first variable in the matrix.y_col (
Optional
[str
]) – If given, name of the column to be used as second variable in the matrix.lags_x (
Optional
[List
[int
]]) – If given, list of lags to be applied to x_col and shown as lagged series in the matrix.lags_y (
Optional
[List
[int
]]) – If given, list of lags to be applied to y_col and shown as lagged series in the matrix.time_col (
Optional
[str
]) – Name of the column from df to be used as time variable in the plot.show (
bool
) – Whether to callFigure.show
at the end of the function. IfFalse
, returns the figure.
- Return type
- Returns
Plotly figure if show is
True
, else nothing.
-
pytsviz.viz.
plot_seasonal_ts
(df, period, y_col=None, time_col=None, title=None, subplots=False, show=True)¶ Interactive plot of the seasonal components of a time series.
- Parameters
df (
DataFrame
) – Dataframe to use as the data source for the plot.period (
Union
[Literal
[‘minute’, ‘hour’, ‘day’, ‘week’, ‘month’, ‘quarter’, ‘year’],Tuple
[Callable
[[Iterable
],Iterable
]]]) – The periodicity of the seasonal component. It can be one of ‘minute’, ‘hour’, ‘day’, ‘week’, ‘month’, ‘quarter’, ‘year’ or a couple of callables specifying both the periodicity and the granularity of data (e.g. daily periodicity, hourly granularity).y_col (
Optional
[str
]) – Name of the column from df to be used as time series values in the plot.time_col (
Optional
[str
]) – Name of the column from df to be used as time variable in the plot.subplots (
bool
) – Whether to split the seasonal components into subplots. Should be set toFalse
if the number of components is too high.show (
bool
) – Whether to callFigure.show
at the end of the function. IfFalse
, returns the figure.
- Return type
- Returns
Plotly figure if show is
True
, else nothing.
-
pytsviz.viz.
plot_ts
(df, y_cols=None, time_col=None, title=None, tf=None, tf_args=(), tf_kwargs=None, keep_original=True, show=True)¶ Interactive plot of one or mode time series, with possibility of transforming them as well.
- Parameters
df (
DataFrame
) – Dataframe to use as the data source for the plot.y_cols (
Optional
[List
[str
]]) – Name of the columns from df to be used as time series values in the plot. IfNone
, all columns are used.time_col (
Optional
[str
]) – Name of the column from df to be used as time variable in the plot.tf (
Union
[Literal
[‘Box-Cox’, ‘Yeo-Johnson’, ‘log’, ‘moving_average’],Callable
[[Iterable
],Iterable
],None
]) – If provided, a transformation to be applied to the time series. It can be one of “Box-Cox”, “Yeo-Johnson”, “log”, “moving_average” or a custom callable one.tf_args (
Tuple
) – Positional arguments for the transformation. See tf for details.tf_kwargs (
Optional
[dict
]) – Keyword arguments for the transformation. See tf for details.keep_original (
bool
) – Whether to show the original along with the transformed one. Only active if tf is notNone
.show (
bool
) – Whether to callFigure.show
at the end of the function. IfFalse
, returns the figure.
- Return type
- Returns
Plotly figure if show is
True
, else nothing.
-
pytsviz.viz.
plot_ts_analysis
(df, y_col=None, time_col=None, nfft=1024, acf_n_lags=None, pacf_n_lags=None, alpha=0.1, show=True, title=None)¶ Composite plot showing the time series, its spectral density, ACF and PACF.
- Parameters
df (
DataFrame
) – Dataframe to use as the data source for the plot.y_col (
Optional
[str
]) – Name of the column from df to be used as time series values in the plot.time_col (
Optional
[str
]) – Name of the column from df to be used as time variable in the plot.nfft (
int
) – Length of the FFT used. IfNone
the length of df will be used.acf_n_lags (
Optional
[int
]) – Maximum number of time steps to consider as lag for ACF.pacf_n_lags (
Optional
[int
]) – Maximum number of time steps to consider as lag for PACF.alpha (
float
) – If a number is given, the confidence intervals for the given level are displayed in the plot.show (
bool
) – Whether to callFigure.show
at the end of the function. IfFalse
, returns the figure.
- Return type
- Returns
Plotly figure if show is
True
, else nothing.
-
pytsviz.viz.
plot_ts_overview
(df, y_col=None, n_lags=None, alpha=0.1, show=True, title=None)¶ Composite plot showing a time series, its auto-correlation function and its distribution.
- Parameters
df (
DataFrame
) – Dataframe to use as the data source for the plot.y_col (
Optional
[str
]) – Name of the column from df to be used as time series values in the plot.n_lags (
Optional
[int
]) – Maximum number of time steps to consider as lag.alpha (
float
) – If a number is given, the confidence intervals for the given level are displayed in the plot.show (
bool
) – Whether to callFigure.show
at the end of the function. IfFalse
, returns the figure.
- Return type
- Returns
Plotly figure if show is
True
, else nothing.