pytsviz package

pytsviz is a Python tool for quick visualization and analysis of time series. It is partially based on the tsviz R package. Is is still under heavy development, so feel free to point out any issues.

pytsviz.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.

  • title (Optional[str]) – Plot title.

  • 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 call Figure.show at the end of the function. If False, returns the figure.

Return type

Optional[BaseFigure]

Returns

Plotly figure if show is True, else nothing.

pytsviz.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.

  • title (Optional[str]) – Plot title.

  • subplots (bool) – Whether to split the decomposition components into subplots.

  • show (bool) – Whether to call Figure.show at the end of the function. If False, returns the figure.

  • decomp_kwargs (Any) – Keyword arguments for the selected decomposition method. See method for details.

Return type

Optional[BaseFigure]

Returns

Plotly figure if show is True, else nothing.

pytsviz.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.

  • bins (Optional[int]) – Number of bins in the histogram.

  • title (Optional[str]) – Plot title.

  • show (bool) – Whether to call Figure.show at the end of the function. If False, returns the figure.

Return type

Optional[BaseFigure]

Returns

Plotly figure if show is True, else nothing.

pytsviz.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. If None, all columns are used.

  • time_col (Optional[str]) – Name of the column from df to be used as time variable in the plot.

  • title (Optional[str]) – Plot title.

  • show (bool) – Whether to call Figure.show at the end of the function. If False, returns the figure.

Return type

Optional[BaseFigure]

Returns

Plotly figure if show is True, else nothing.

pytsviz.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.

  • title (Optional[str]) – Plot title.

  • show (bool) – Whether to call Figure.show at the end of the function. If False, returns the figure.

Return type

Optional[BaseFigure]

Returns

Plotly figure if show is True, else nothing.

pytsviz.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 call Figure.show at the end of the function. If False, returns the figure.

Return type

Optional[BaseFigure]

Returns

Tuple of plotly figures if show is True, else nothing.

pytsviz.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 call Figure.show at the end of the function. If False, returns the figure.

Return type

Optional[BaseFigure]

Returns

Plotly figure if show is True, else nothing.

pytsviz.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 call Figure.show at the end of the function. If False, returns the figure.

  • nfft (Optional[int]) – Length of the FFT used. If None 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) – If True, plot time on the x axis, else plot sampling frequency.

  • title (Optional[str]) – Plot title.

Return type

Optional[BaseFigure]

Returns

Plotly figure if show is True, else nothing.

pytsviz.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.

  • title (Optional[str]) – Plot title.

  • 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 call Figure.show at the end of the function. If False, returns the figure.

  • kwargs – Keyword arguments for fit, if not set to False. They are passed to pandas.plot.

Return type

Optional[BaseFigure]

Returns

Plotly figure if show is True, else nothing.

pytsviz.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.

  • title (Optional[str]) – Plot title.

  • show (bool) – Whether to call Figure.show at the end of the function. If False, returns the figure.

Return type

Optional[BaseFigure]

Returns

Plotly figure if show is True, else nothing.

pytsviz.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.

  • title (Optional[str]) – Plot title.

  • subplots (bool) – Whether to split the seasonal components into subplots. Should be set to False if the number of components is too high.

  • show (bool) – Whether to call Figure.show at the end of the function. If False, returns the figure.

Return type

Optional[BaseFigure]

Returns

Plotly figure if show is True, else nothing.

pytsviz.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. If None, all columns are used.

  • time_col (Optional[str]) – Name of the column from df to be used as time variable in the plot.

  • title (Optional[str]) – Plot title.

  • 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 not None.

  • show (bool) – Whether to call Figure.show at the end of the function. If False, returns the figure.

Return type

Optional[BaseFigure]

Returns

Plotly figure if show is True, else nothing.

pytsviz.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. If None 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 call Figure.show at the end of the function. If False, returns the figure.

  • title (Optional[str]) – Plot title.

Return type

Optional[BaseFigure]

Returns

Plotly figure if show is True, else nothing.

pytsviz.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 call Figure.show at the end of the function. If False, returns the figure.

  • title (Optional[str]) – Plot title.

Return type

Optional[BaseFigure]

Returns

Plotly figure if show is True, else nothing.