tsplot module

tscluster.tsplot.plot(*, X: npt.NDArray[np.float64] | None = None, cluster_centers: npt.NDArray[np.float64] | None = None, labels: npt.NDArray[np.float64] | None = None, entity_idx: List[int] | None = None, entities_labels: List[str] | None = None, label_dict: dict | None = None, annot_fontsize: float | int = 10, show_all_entities: bool = True, figsize: Tuple[float, float] | None = None, shape_of_subplot: Tuple[int, int] | None = None, xlabel: str | None = 'timesteps', ylabel: str | None = 'value', cluster_labels: List[str] | None = None, title_list: List[str] | None = None, show_all_xticklabels: bool = True, x_rotation: float | int = 45, show_X_marker: bool = False, show_cluster_center_marker: bool = False) → Tuple[matplotlib.figure.Figure, List[matplotlib.axes.Axes]]

Function to plot subplots of the time series data, cluster centers and label assignemnts. One subplot per feature. This is built on top of matplotlib.

Parameters:

Xnumpy array, default=None

The time series data in TNF format.

cluster_centersnumpy array, default=None

If numpy array, it is expected to be a 3D in TNF format. Here, N is the number of clusters. If 2-D array, then it is interpreted as a K x F array where K is the number of clusters, and F is the number of features. Suitable for fixed cluster centers clustering.

labelsnumpy array, default=None

It is expected to be a 2D array of shape (N, T) . Where N is the number of entities and T is the number of time steps. The value of the ith row at the t-th column is the label (cluster index) entity i was assigned to at time t. If 1-D array, it is interpreted as an array of length N. Where N is the number of entities. In such case, the i-th element is the cluster the i-th entity was assigned to across all time steps. Suitable for fixed assignment clustering.

entity_idxlist, default=None

list of index of entities to display in the plot. If show_all_entities is True, entity_idx will be interpreted as the index of entities to be annonated.

entities_labelslist, default=None

list of labels for annotating the entities in entity_idx. If None, then labels of entity_idx in label_dict are used.

label_dict dict, default=None

a dictionary whose keys are ‘T’, ‘N’, and ‘F’ (which are the number of time steps, entities, and features respectively). Value of each key is a list such that the value of key: - ‘T’ is a list of names/labels of each time step to be used as index of each dataframe. If None, range(0, T) is used. Where T is the number of time steps in the fitted data - ‘N’ is a list of names/labels of each entity. If None, range(0, N) is used. Where N is the number of entities/observations in the fitted data - ‘F’ is a list of names/labels of each feature to be used as column of each dataframe. If None, range(0, F) is used. Where F is the number of features in the fitted data If label_dict is not None, it is used to label timestep, entities, and features in the plot.

annot_fontsizefloat|int, default=10

The font size to be used for annotating entities in entity_idx.

show_all_entitiesbool, default=True

If True, displays all the entities in X in the plot. If False, only entities in entity_idx are plotted.

figsizetuple, default=None

The size of the figure. Should be tuple of length 2, where the first value is width of the figure, while the second value is the height of the figure.

shape_of_subplottuple, default=None

The shape of the subplots. Should be tuple of length 2, where the first value is number of rows, while the second value is the of columns in the figure. If None, (F, 1) is used. Where F is the number of features in X or cluster_centers.

xlabelstr, default=’timesteps’

The label for the x-axis of each subplots

ylabelstr, default=’timesteps’

The label for the y-axis of each subplots

cluster_labelslist, default=None

The labels to use for the clusters. If None, list(range(K)) is used. Where K is the number of clusters in cluster_centers or labels.

title_listlist, default=None

The title of each subplot (or feature).

show_all_xticklabelsbool, default=True

If True, shows labels of all time steps in the plot. If False, some may be suppressed (depending on the size of the plot)

x_rotationfloat or int, default=45

The angle (in degrees) to rotate the timestep labels

show_X_markerbool, default=False

If True, show markers in the time series plot of X.

show_cluster_center_markerbool, default=False

If True, show markers in the time series plot of the cluster centers.

Returns:

matplotlib.figure.Figure

the matplotlib figure object

list

a list of the matplotlib axes, one axes per subplot.

tscluster.tsplot.waterfall_plot(time_series: npt.NDArray[np.float64], label_dict: dict | None = None, *, xlabel: str = 'time-axis', ylabel: str = 'Features-axis', zlabel: str = 'Feature Values', title: str | None = None) → Tuple[matplotlib.figure.Figure, mpl_toolkits.mplot3d.axes3d.Axes3D]

Function to plot a waterfall plot of a single time series data. This data can be a time series of a single entity or cluster center. To make the plot interactive, use a suitable matplotlib’s magic command. E.g. %matplotlib widget. See this site for more: https://matplotlib.org/stable/users/explain/figure/interactive.html

Parameters:

time_seriesnumpy array

The time series data to plot. This data can be a time series of a single entity or cluster center. Data should be a 2-D array of shape (T, F), where T and F are the number of timesteps and features respectively.

label_dictdict, default=None

a dictionary whose keys are ‘T’, ‘N’, and ‘F’ (which are the number of time steps, entities, and features respectively). Value of each key is a list such that the value of key: - ‘T’ is a list of names/labels of each time step to be used as index of each dataframe. If None, range(0, T) is used. Where T is the number of time steps in the fitted data - ‘N’ (ignored) is a list of names/labels of each entity. If None, range(0, N) is used. Where N is the number of entities/observations in the fitted data - ‘F’ is a list of names/labels of each feature to be used as column of each dataframe. If None, range(0, F) is used. Where F is the number of features in the fitted data If label_dict is not None, it is used to label timestep and features in the plot.

xlabelstr, default=’time-axis’

The label of the x-axis (time axis)

ylabelstr, default=’Features-axis’

The label of the y-axis (feature axis)

zlabelstr, default=’Feature Values’

The label of the z-axis (axis for the values of the features)

titlestr, default=None

The title of the plot

Returns:

matplotlib.figure.Figure

the matplotlib figure object

mpl_toolkits.mplot3d.axes3d.Axes3D

the matplotlib’s 3-D axes object.