plotting

TimeSeriesDisplay

add_time_series(*, data, num_points=None, name_on_hover=None, legend_group=None, **kwargs)

Add a time series to the subplot grid.

Parameters:

Name	Type	Description	Default
data	LazyFrame	Panel LazyFrame time series data.	required
num_points	Optional[int]	Number of data points to plot. If None, plot all points. If a float value is passed, plot the corresponding percentage of points. Defaults to None.	None
name_on_hover	Optional[str]	Text that will be displayed on hover. Defaults to the name of the target column.	None
legend_group	Optional[str]	Legend group the trace belongs to. Defaults to None.	None
**kwargs		Additional keyword arguments to pass to plotly.graph_objects.Line object.	{}

Returns:

Name	Type	Description
self	Self	Instance of TimeSeriesDisplay.

Raises:

Type	Description
ValueError	If num_points is not a positive integer.

from_panel(*, y, num_cols=None, num_series=None, seed=None, default_title, **kwargs) classmethod

Initialize a time series display from a Panel LazyFrame.

The initialisation defines a plotly.graphic_objects.Figure figure with the given number of columns and rows, and the entities in the data.

Parameters:

Name	Type	Description	Default
y	LazyFrame	Panel LazyFrame time series data.	required
num_cols	Optional[int]	Number of columns in the subplot grid. Defaults to 2.	None
num_series	Optional[int]	Number of series in the subplot grid. If None, displays all series. Defaults to None.	None
seed	Optional[int]	Seed for the random sample of entities to plot. Defaults to None.	None
default_title	str	Default title for the figure.	required
**kwargs		Additional keyword arguments to pass to plotly.graph_objects.Figure object.	{}

Returns:

Name	Type	Description
self	Self	Instance of TimeSeriesDisplay.

Raises:

Type	Description
ValueError	If any of num_cols or num_series is not a positive integer.

plot_comet(y_train, y_test, y_pred, scoring=None, **kwargs)

Given a train-test-split of panel data (y_train, y_test) and forecast y_pred, returns a Comet plot i.e. scatterplot of volatility per entity in y_train against the forecast scores.

Parameters:

Name	Type	Description	Default
y_train	DataFrame	Panel DataFrame of train dataset.	required
y_test	DataFrame	Panel DataFrame of test dataset.	required
y_pred	DataFrame	Panel DataFrame of forecasted values to score against y_test.	required
scoring	Optional[metric]	If None, defaults to SMAPE.	None

Returns:

Name	Type	Description
figure	Figure	Plotly scatterplot.

plot_entities(y, **kwargs)

Given panel DataFrame of observed values y, returns bar chart of entity counts, which is the number of observed values per entity.

Parameters:

Name	Type	Description	Default
y	DataFrame | LazyFrame	Panel DataFrame of observed values.	required
**kwargs		Additional keyword arguments to pass to a plotly.graph_objects.Layout object.	{}

Returns:

Name	Type	Description
figure	Figure	Plotly bar chart.

plot_forecasts(*, y_true, y_pred, num_series=None, num_cols=None, num_points=None, seed=None, layout_kwargs=None, line_kwargs=None)

Given panel DataFrames of observed values y and forecasts y_pred, returns subplots for each individual entity / time-series.

Parameters:

Name	Type	Description	Default
y	Union[DataFrame, LazyFrame]	Panel DataFrame of observed values.	required
num_series	Optional[int]	Number of entities / time-series to plot. If None, plot all entities. Defaults to None.	None
num_points	Optional[int]	Plot last_n most recent values in y. If None, plot all points. If a float value is passed, plot the correspinding percentage of the points. Defaults to None.	None
num_cols	Optional[int]	Number of columns to arrange subplots. Defaults to 2.	None
seed	Optional[int]	Random seed for sampling entities / time-series. Defaults to None.	None
layout_kwargs	Optional[Dict[str, Any]]	Additional keyword arguments to pass to plotly.graph_objects.Figure.update_layout or, equivalently, a plotly.graph_objects.Layout object.	None
line_kwargs	Optional[Dict[str, Any]]	Additional keyword arguments to pass to a plotly.graph_objects.Line object.	None

Returns:

Name	Type	Description
figure	Figure	Plotly instance of Figure with all the subplots.

plot_fva(y_true, y_pred, y_pred_bench, scoring=None, **kwargs)

Given two panel data forecasts y_pred and y_pred_bench, returns scatterplot of benchmark scores against forecast scores. Each dot represents a single entity / time-series.

Parameters:

Name	Type	Description	Default
y_true	DataFrame	Panel DataFrame of test dataset.	required
y_pred	DataFrame	Panel DataFrame of forecasted values.	required
y_pred_bench	DataFrame	Panel DataFrame of benchmark forecast values.	required
scoring	Optional[metric]	If None, defaults to SMAPE.	None

Returns:

Name	Type	Description
figure	Figure	Plotly scatterplot.

plot_panel(y, *, num_series=None, num_cols=None, num_points=None, seed=None, layout_kwargs=None, line_kwargs=None)

Given panel DataFrames of observed values y, returns subplots for each individual entity / time-series.

Parameters:

Name	Type	Description	Default
y	Union[DataFrame, LazyFrame]	Panel DataFrame of observed values.	required
num_series	Optional[int]	Number of entities / time-series to plot. If None, plot all entities. Defaults to None.	None
num_points	Optional[int | float]	Plot last_n most recent values in y. If None, plot all points. If a float value is passed, plot the correspinding percentage of the points. Defaults to None.	None
num_cols	Optional[int]	Number of columns to arrange subplots. Defaults to 2.	None
seed	Optional[int]	Random seed for sampling entities / time-series. Defaults to None.	None
layout_kwargs	Optional[Dict[str, Any]]	Additional keyword arguments to pass to a plotly.graph_objects.Layout object.	None
line_kwargs	Optional[Dict[str, Any]]	Additional keyword arguments to pass to a plotly.graph_objects.Line object.	None

Returns:

Name	Type	Description
figure	Figure	Plotly instance of Figure with all the subplots.

plot_residuals(y_resids, n_bins=None, **kwargs)

Given panel DataFrame of residuals across splits y_resids, returns binned counts plot of forecast residuals colored by entity / time-series.

Useful for residuals analysis (bias and normality) at scale.

Parameters:

Name	Type	Description	Default
y_resids	Union[DataFrame, LazyFrame]	Panel DataFrame of forecast residuals (i.e. observed less forecast).	required
n_bins	int	Number of bins.	None

Returns:

Name	Type	Description
figure	Figure	Plotly histogram.

smape(y_true, y_pred)

Return symmetric mean absolute percentage error (sMAPE).

Use third version of SMAPE formula from https://en.wikipedia.org/wiki/Symmetric_mean_absolute_percentage_error to deal with zero division error

Parameters:

Name	Type	Description	Default
y_true	DataFrame	Ground truth (correct) target values.	required
y_pred	DataFrame	Predicted values.	required

Returns:

Name	Type	Description
scores	DataFrame	Score per series.