pytseg package

pytseg.seg

Toolbox for univariate time series segmentation.

pytseg.seg.cut(x: ndarray, alpha: float = 0.95, l0: float = 3) → ndarray[source]

Cut a univariate time series into a set of distinguishable segments. This algorithm closely follows “Heuristic segmentation of a nonstationary time series”, Fukuda et al. (2004).

Parameters:

  • x (np.ndarray) – Time series observations to cut. Array of shape (n_observations,).

  • alpha (float, optional) – Significance Threshold. The default is .95.

  • l0 (float, optional) – Minimum segment length, has to be 3 or more. The default is 3.

Returns:

s – Array of segment indices for x.

Return type:

np.ndarray

pytseg.seg.normalize(x: ndarray, t: ndarray | None, scaler: TransformerMixin = MinMaxScaler()) → Tuple[ndarray, ndarray][source]

Normalize a time series: evenly spaced and rescaled data.

Parameters:

  • x (np.ndarray) – Time series observations. Array of shape (n_observations,).

  • t (Union[np.ndarray,None]) – Time series time steps for each observation. Array of shape (n_observations,). If set to None, the default t = np.arange(x.size) is considered.

  • scaler (sklearn.base.TransformerMixin) – Rescaler for x. The default is MinMaxScaler().

Returns:

  • X (np.ndarray) – Normalized and evenly spaced time series observations.

  • t (np.ndarray) – Evenly spaced time series time steps.

pytseg.seg.segment_clustering(x: ~numpy.ndarray, s: ~numpy.ndarray, n_clusters: int = 2, random_state: int | ~numpy.random.mtrand.RandomState = 0, kmeans_kwarg_dict: dict = {}, feature_maps: ~typing.List[~typing.Callable[[~numpy.ndarray], float]] = [<function mean>, <function std>], feature_scaler: ~sklearn.base.TransformerMixin = StandardScaler()) → ndarray[source]

Perform clustization for a segmented univariate time series using sklearn.cluster.KMeans.

Parameters:

  • x (np.ndarray) – Time series observations.

  • s (np.ndarray) – Array of segment indices for x (from cut).

  • n_clusters (int, optional) – Number of clusters to consider. The default is 2.

  • random_state (Union[int,np.random.mtrand.RandomState], optional) – Random seed (or state) of the clustering algorithm. The default is 0.

  • kmeans_kwarg_dict (dict, optional) – Optional keyword arguments for KMeans. The default is {}.

  • feature_maps (List[Callable[[np.ndarray], float]], optional) – Feature maps: each segment is mapped to a float. The default is [np.mean, np.std].

  • feature_scaler (sklearn.base.TransformerMixin, optional) – Rescaler for all features. The default is StandardScaler().

Returns:

labels – Array of labels (cluster index).

Return type:

np.ndarray

pytseg.seg.segment_stationarity(x: ndarray, s: ndarray, threshold: float = 0.01) → ndarray[source]

Identify stationarity for a segmented univariate time series.

Parameters:

  • x (np.ndarray) – Time series observations.

  • s (np.ndarray) – Array of segment indices for x (from cut).

  • threshold (float, optional) – Stationarity threshold: stationarity is identified if the standard deviation of a segment is smaller than (or equal to) threshold * std, where std is the standard deviation of the whole time series. The default is .01.

Returns:

labels – Array of labels (True: stationary or False: non-stationary).

Return type:

np.ndarray

pytseg.seg.segmentize(a: ndarray, s: ndarray) → List[ndarray][source]

Get list of array segments from segment indices.

Parameters:

  • a (np.ndarray) – Array to segment.

  • s (np.ndarray) – Array of segment indices for a (from cut).

Returns:

a_seg – List of array segments.

Return type:

np.ndarray

pytseg.seg_multi

Toolbox for multivariate time series segmentation.

pytseg.seg_multi.cut_multi(X: ndarray, alpha: float = 0.95, l0: float = 3) → List[ndarray][source]

Cut a multivariate time series, see seg.cut.

Parameters:

  • X (np.ndarray) – Time series observations to cut. Array of shape (n_observations, n_series).

  • alpha (float, optional) – Significance Threshold. The default is .95.

  • l0 (float, optional) – Minimum segment length, has to be 3 or more. The default is 3.

Returns:

S – List of arrays of segment indices for X.

Return type:

List[np.ndarray]

pytseg.seg_multi.joint_labels_multi(t: ndarray, S: List[ndarray], labels_multi: List[ndarray], joint_label_fun: Callable[[list], float]) → Tuple[ndarray, ndarray][source]

Join labels/segments from multiple time series into one label/segment series.

Parameters:

  • t (np.ndarray) – Time series time steps for each observation.

  • S (List[np.ndarray]) – List of arrays of segment indices for t (from cut_multi).

  • labels_multi (List[np.ndarray]) – List of label arrays.

  • joint_label_fun (Callable[[list],float]) – Function to join labels from multiple observations into one joint label.

Returns:

  • s (np.ndarray) – Array of segment indices for t.

  • l (np.ndarray) – Array of labels for t.

pytseg.seg_multi.normalize_multi(X: ndarray, t: ndarray | None, scaler: TransformerMixin = MinMaxScaler()) → Tuple[ndarray, ndarray][source]

Normalize a multivariate time series: evenly spaced and rescaled data.

Parameters:

  • X (np.ndarray) – Time series observations. Array of shape (n_observations, n_series).

  • t (Union[np.ndarray,None]) – Time series time steps for each observation. Array of shape (n_observations,). If set to None, the default t = np.arange(X.shape[0]) is considered.

  • scaler (sklearn.base.TransformerMixin) – Rescaler for X. The default is MinMaxScaler().

Returns:

  • X (np.ndarray) – Normalized and evenly spaced time series observations.

  • t (np.ndarray) – Evenly spaced time series time steps.

pytseg.seg_multi.segment_stationarity_multi(X: ndarray, S: List[ndarray], t: ndarray | None = None, threshold: float = 0.025) → Tuple[ndarray, ndarray][source]

Identify stationarity for a segmented multivariate time series.

Parameters:

  • X (np.ndarray) – Time series observations to cut. Array of shape (n_observations, n_series).

  • S (List[np.ndarray]) – List of arrays of segment indices for X (from cut_multi).

  • t (Union[np.ndarray,None], optional) – Time series time steps for each observation. Array of shape (n_observations,). If set to None, the default t = np.arange(X.shape[0]) is considered. The default is None.

  • threshold (float, optional) – Stationarity threshold, see seg.segment_stationarity. The default is .025.

Returns:

  • s (np.ndarray) – Array of segment indices for t.

  • l (np.ndarray) – Array of labels for t.

pytseg.seg_multi.segmentize_multi(A: ndarray, S: List[ndarray]) → List[List[ndarray]][source]

Get list of array segments from segment index list, see seg.segmentize.

Parameters:

  • A (np.ndarray) – Arrays to segment: (n_arrays, n_elements).

  • S (List[np.ndarray]) – List of arrays of segment indices for A (from cut_multi).

Returns:

A_seg – List of array segments (as list of results from seg.segmentize).

Return type:

List[List[np.ndarray]]

pytseg.plot

Plotting helper functions.

pytseg.plot.plot(x: ndarray, s: ndarray | None = None, t: ndarray | None = None, l: ndarray | None = None, cmap: str = 'brg', figure_kwarg_dict: dict = {}, plot_kwarg_dict: dict = {}, new_fig_: bool = True, show_legend_: bool = False, show_fig_: bool = True) → None[source]

Plot univariate time series.

Parameters:

  • x (np.ndarray) – Time series observations.

  • s (Union[np.ndarray,None], optional) – Array of segment indices for x (from seg.cut). If set to None, no segments are considered. The default is None.

  • t (Union[np.ndarray,None], optional) – Time series time steps for each observation. If set to None, the default t = np.arange(x.size) is considered. The default is None.

  • l (Union[np.ndarray,None], optional) – Array of labels for each segment in s. If set to None, no labels are considered. The default is None.

  • cmap (str, optional) – Color map name for plotting different segments. The default is 'brg'.

  • figure_kwarg_dict (dict, optional) – Additional keyword arguments for the figure. The default is {}.

  • plot_kwarg_dict (dict, optional) – Additional keyword arguments for the plots. The default is {}.

  • new_fig (bool, optional) – Create new figure. Inteded for internal use. The default is True.

  • show_legend (bool, optional) – Show legend. Inteded for internal use. The default is False.

  • show_fig (bool, optional) – Show figure. Inteded for internal use. The default is True.

Return type:

None.

pytseg.plot.plot_multi(X: ndarray, S: List[ndarray] | None = None, t: ndarray | None = None, L: List[ndarray] | None = None, cmap: str = 'brg', figure_kwarg_dict: dict = {}, plot_kwarg_dict: dict = {}, label: str | None = None) → None[source]

Plot multivariate time series.

Parameters:

  • X (np.ndarray) – Time series observations.

  • S (Union[List[np.ndarray],None], optional) – List of segment index arrays for X (from seg_multi.cut_multi). If set to None, no segments are considered. The default is None.

  • t (Union[np.ndarray,None], optional) – Time series time steps for each observation. If set to None, the default in plot is considered. The default is None.

  • L (Union[List[np.ndarray],None], optional) – List of label arrays for each segment in S. If set to None, no labels are considered. The default is None.

  • cmap (str, optional) – Color map name for plotting different segments. The default is 'brg'.

  • figure_kwarg_dict (dict, optional) – Additional keyword arguments for the figure. The default is {}.

  • plot_kwarg_dict (dict, optional) – Additional keyword arguments for the plots. The default is {}.

  • label (Union[str,None], optional) – Label prefix for legend. If set to None, no legend is shown. The default is None.

Return type:

None.

pytseg.data

Data helper functions.

pytseg.data.test_fun(t: ndarray | None = None, λ0: float = 1, λ1: float = 1, λ2: float = 0.1, λ3: float = 0.006666666666666667, λ4: float = 1, λ5: float = 0.01, λ6: float = 0.004, λ7: float = -1, λ8: float = 0.01, λ9: float = 3000, λ10: float = 0.002, λ11: float = 5000, λ12: float = 0.001, λ13: float = 1, λ14: float = 0, λ15: float = 0) → Tuple[ndarray, ndarray][source]

Create univariate test time series.

Parameters:

  • t (np.ndarray, optional) – Time series time steps for each observation. Array of shape (n_observations,). If set to None, the default t = np.arange(7000) is considered.

  • λ0 (float, optional) – Test function parameter. The default is 1.

  • λ1 (float, optional) – Test function parameter. The default is 1.

  • λ2 (float, optional) – Test function parameter. The default is 1/10.

  • λ3 (float, optional) – Test function parameter. The default is 1/150.

  • λ4 (float, optional) – Test function parameter. The default is 1.

  • λ5 (float, optional) – Test function parameter. The default is 1/100.

  • λ6 (float, optional) – Test function parameter. The default is 1/250.

  • λ7 (float, optional) – Test function parameter. The default is -1.

  • λ8 (float, optional) – Test function parameter. The default is 1/100.

  • λ9 (float, optional) – Test function parameter. The default is 3000.

  • λ10 (float, optional) – Test function parameter. The default is 1/500.

  • λ11 (float, optional) – Test function parameter. The default is 5000.

  • λ12 (float, optional) – Test function parameter. The default is 1/1000.

  • λ13 (float, optional) – Test function parameter. The default is 1.

  • λ14 (float, optional) – Test function parameter. The default is 0.

  • λ15 (float, optional) – Test function parameter. The default is 0.

Returns:

  • x (np.ndarray) – Time series observations. Array of shape (n_observations,).

  • t (np.ndarray) – Time series time steps for each observation. Array of shape (n_observations,).