API Reference

SSA and MSSA

class py_ssa_lib.ssa_collection.BaseSSA(decomposition_strategy: SVDStrategy | None = None, weighting_strategy: WeightingStrategy | None = None)[source]

Bases: ABC

Base class for each SSA implementation

DEFAULT_DECOMPOSITION

alias of FullSVD

DEFAULT_WEIGHTING

alias of UniformWeights

K_forecast(forecast_steps: int, idx_components: list[int] | ndarray[tuple[int, ...], dtype[int64]], return_full: bool = True) → ndarray[tuple[int, ...], dtype[float64]][source]
Parameters:

  • forecast_steps (int) – Number of future observations to predict.

  • idx_components (list[int] or np.ndarray) – Components defining the forecasting subspace.

  • return_full (bool) – Whether to return the reconstructed history together with the forecasted values.

Returns:

K-vector forecast.

Return type:

ndarray

L_forecast(forecast_steps: int, idx_components: list[int] | ndarray[tuple[int, ...], dtype[int64]], return_full: bool = True) → ndarray[tuple[int, ...], dtype[float64]][source]
Parameters:

  • forecast_steps (int) – Number of future observations to predict.

  • idx_components (list[int] or np.ndarray) – Components used to estimate the recurrence relation.

  • return_full (bool) – Whether to return the reconstructed history together with the forecasted values.

Returns:

L-recurrent forecast.

Return type:

ndarray

compute_weighted_correlation_matrix() → ndarray[tuple[int, ...], dtype[float64]][source]
Returns:

Weighted component-correlation matrix with shape (d, d).

Return type:

ndarray

construct_hankel_weights() → ndarray[tuple[int, ...], dtype[int64]][source]
Returns:

Hankel weights describing observation multiplicities.

Return type:

ndarray

construct_trajectory_matrix() → ndarray[tuple[int, ...], dtype[float64]][source]
Returns:

Weighted trajectory matrix with shape (L, K*S).

Return type:

ndarray

static diagonal_averaging(X: ndarray[tuple[int, ...], dtype[float64]]) → ndarray[tuple[int, ...], dtype[float64]][source]
Parameters:

X (ndarray) – Trajectory matrix to convert back to a time series.

Returns:

Reconstructed time series obtained by anti-diagonal averaging.

Return type:

ndarray

elementary_matrix() → ndarray[tuple[int, ...], dtype[float64]][source]
Returns:

Elementary trajectory matrices for all retained SVD components.

Return type:

ndarray

estimate_ESPRIT(idx_components: list[int] | ndarray[tuple[int, ...], dtype[int64]]) → tuple[ndarray[tuple[int, ...], dtype[complex128]], ndarray[tuple[int, ...], dtype[float64]], ndarray[tuple[int, ...], dtype[float64]]][source]
Parameters:

idx_components (list[int] or np.ndarray) – Components defining the signal subspace.

Returns:

  • mu (ndarray) – Complex ESPRIT roots.

  • rho (ndarray) – Magnitudes of the roots.

  • omega (ndarray) – Angular frequencies of the roots.

estimate_LRR(idx_components: list[int] | ndarray[tuple[int, ...], dtype[int64]]) → ndarray[tuple[int, ...], dtype[float64]][source]
Parameters:

idx_components (list[int] or np.ndarray) – Components defining the signal subspace.

Returns:

Linear recurrence coefficients.

Return type:

ndarray

fit(data: Series | DataFrame | ndarray[tuple[int, ...], dtype[_ScalarType_co]], L: int | None = None, **weighting_kwargs: Any) → BaseSSA[source]
Parameters:

  • data (Series | DataFrame | ndarray) – Input time-series data.

  • L (int | None) – SSA window length.

  • **weighting_kwargs (Any) – Additional arguments passed to the weighting strategy.

Returns:

Fitted SSA/MSSA instance.

Return type:

BaseSSA

reconstruct_components(idx_components: list[int] | ndarray[tuple[int, ...], dtype[int64]]) → ndarray[tuple[int, ...], dtype[float64]][source]
Parameters:

idx_components (list[int] or np.ndarray) – Indices of components used for reconstruction.

Returns:

Reconstructed time series with shape (N, S).

Return type:

ndarray

class py_ssa_lib.ssa_collection.MSSA(decomposition_strategy: SVDStrategy | None = None, weighting_strategy: WeightingStrategy | None = None)[source]

Bases: BaseSSA

Class for the MSSA. Use for the multivariate time series analysis.

class py_ssa_lib.ssa_collection.SSA(decomposition_strategy: SVDStrategy | None = None, weighting_strategy: WeightingStrategy | None = None)[source]

Bases: BaseSSA

Class for the SSA. Use for the univariate time series analysis.

SVD Strategies

class py_ssa_lib.svd_strategies.FullSVD(**kwargs: Any)[source]

Bases: SVDStrategy

Class for performing full(exact) SVD.

decompose(X: ndarray[tuple[int, ...], dtype[float64]]) → tuple[ndarray[tuple[int, ...], dtype[float64]], ndarray[tuple[int, ...], dtype[float64]], ndarray[tuple[int, ...], dtype[float64]]][source]
Parameters:

X (ndarray) – Matrix to decompose.

Returns:

  • U (ndarray) – Left singular vectors.

  • sigma (ndarray) – Singular values.

  • Vt (ndarray) – Transposed right singular vectors.

class py_ssa_lib.svd_strategies.RandomizedSVD(n_components: int, n_oversamples: int = 10, n_iter: int | str = 'auto', random_state: int | None = None, **kwargs: Any)[source]

Bases: SVDStrategy

Class for performing approximate SVD using randomizedSVD function from sklearn.utils module.

decompose(X: ndarray[tuple[int, ...], dtype[float64]]) → tuple[ndarray[tuple[int, ...], dtype[float64]], ndarray[tuple[int, ...], dtype[float64]], ndarray[tuple[int, ...], dtype[float64]]][source]
Parameters:

X (ndarray) – Matrix to decompose.

Returns:

  • U (ndarray) – Left singular vectors.

  • sigma (ndarray) – Singular values.

  • Vt (ndarray) – Transposed right singular vectors.

class py_ssa_lib.svd_strategies.SVDStrategy[source]

Bases: ABC

Base class for performing SVD.

abstract decompose(X: ndarray[tuple[int, ...], dtype[float64]]) → tuple[ndarray[tuple[int, ...], dtype[float64]], ndarray[tuple[int, ...], dtype[float64]], ndarray[tuple[int, ...], dtype[float64]]][source]
Parameters:

X (ndarray) – Matrix to decompose.

Returns:

  • U (ndarray) – Left singular vectors.

  • sigma (ndarray) – Singular values.

  • Vt (ndarray) – Transposed right singular vectors.

Weighting Strategies

class py_ssa_lib.weights_strategies.ClusterAwareWeights[source]

Bases: WeightingStrategy

Distance-based with cluster membership awareness implementation for weighting of spectral channels in SSA and MSSA.

compute_weights(X: ndarray[tuple[int, ...], dtype[float64]], distances: Sequence[float], focal_cluster: Hashable, neighbour_clusters: Sequence[Hashable], bandwidth: float = 1.0, cluster_penalty: float = 0.5, **kwargs: Any) → ndarray[tuple[int, ...], dtype[float64]][source]
Parameters:

  • X (ndarray) – Time-series matrix.

  • distances (Sequence[float]) – Distance from the focal series to each neighbour.

  • focal_cluster (Hashable) – Cluster label of the focal series.

  • neighbour_clusters (Sequence[Hashable]) – Cluster labels of neighbouring series.

  • bandwidth (float) – Scale controlling distance-weight decay.

  • cluster_penalty (float) – Weight multiplier applied to different-cluster neighbours.

Returns:

Combined spatial and cluster-aware weights.

Return type:

ndarray

class py_ssa_lib.weights_strategies.DistanceWeights[source]

Bases: WeightingStrategy

Distance-based implementation for weighting of spectral channels in SSA and MSSA.

compute_weights(X: ndarray[tuple[int, ...], dtype[float64]], distances: Sequence[float], bandwidth: float = 1.0, **kwargs: Any) → ndarray[tuple[int, ...], dtype[float64]][source]
Parameters:

  • X (ndarray) – Time-series matrix.

  • distances (Sequence[float]) – Distance from the focal series to each series.

  • bandwidth (float) – Scale controlling distance-weight decay.

Returns:

Distance-based weights.

Return type:

ndarray

class py_ssa_lib.weights_strategies.PrecomputedWeights[source]

Bases: WeightingStrategy

Pass precomputed weights for the spectral channels in SSA and MSSA. Weights must be strictly positive!

compute_weights(X: ndarray[tuple[int, ...], dtype[float64]], weights: Sequence[float], **kwargs: Any) → ndarray[tuple[int, ...], dtype[float64]][source]
Parameters:

  • X (ndarray) – Time-series matrix.

  • weights (Sequence[float]) – User-provided weight for each series.

Returns:

Precomputed weights as a NumPy array.

Return type:

ndarray

class py_ssa_lib.weights_strategies.UniformWeights[source]

Bases: WeightingStrategy

Classical implementation for weighting of spectral channels in SSA and MSSA.

compute_weights(X: ndarray[tuple[int, ...], dtype[float64]], **kwargs: Any) → ndarray[tuple[int, ...], dtype[float64]][source]
Parameters:

X (ndarray) – Time-series matrix used to determine the number of series.

Returns:

Unit weights for all series.

Return type:

ndarray

class py_ssa_lib.weights_strategies.WeightingStrategy[source]

Bases: ABC

Base class for weighting of spectral channels.

abstract compute_weights(X: ndarray[tuple[int, ...], dtype[float64]], **kwargs: Any) → ndarray[tuple[int, ...], dtype[float64]][source]
Parameters:

  • X (ndarray) – Time-series matrix with shape (N, S).

  • **kwargs (Any) – Strategy-specific parameters.

Returns:

Weight vector with shape (S,).

Return type:

ndarray

Statistical Tools

py_ssa_lib.stat_tools.bootstrap_prediction_intervals(residuals: ndarray[tuple[int, ...], dtype[float64]], forecasts: ndarray[tuple[int, ...], dtype[float64]], alpha: float = 0.05, N_sims: int = 1000) → tuple[ndarray[tuple[int, ...], dtype[float64]], ndarray[tuple[int, ...], dtype[float64]]][source]
Parameters:

  • residuals (ndarray) – Residuals used for bootstrap resampling.

  • forecasts (ndarray) – Point forecasts for future observations.

  • alpha (float) – Significance level for the prediction interval.

  • N_sims (int) – Number of bootstrap simulations.

Returns:

  • lower_pi (ndarray) – Lower prediction bounds.

  • upper_pi (ndarray) – Upper prediction bounds.

  • This is a bootstrap method for the prediction intervals discucced in the online textbook of Rob J Hyndman and George Athanasopoulos https (//otexts.com/fpp3/prediction-intervals.html.)

  • It computes lower and upper prediction intervals. This method is model free and requires only the independence of residuals and allows to get reasonable prediction intervals for lower computational costs

  • and milder conditions. This means one can use it for any other model besides the MSSA/SSA.

  • In the case of the SSA one starts with the computation of residuals between original time series and the reconstruted one. It is crucial to check for the abscence of an autocorrelation within the obtained

  • residuals. Using predefined numbers of components one performs either L- or K-forecast for M future steps. These values are then passed to the corresponding input parameters. Additionally, one can adjust

  • the confidence level and simulation number as well.

  • In the case of MSSA, one has to pick the time series of the interest with the same index. The algorithm doesn’t change.

Visualization

py_ssa_lib.vis_tools.plot_contributions(ssa: BaseSSA, n_components: int | None = None, figsize: tuple[float, float] = (10, 4), **plot_kwargs: Any) → tuple[Figure, ndarray[tuple[int, ...], dtype[_ScalarType_co]]][source]
Parameters:

  • ssa (BaseSSA) – Fitted SSA/MSSA model.

  • n_components (int | None) – Number of components to display.

  • figsize (tuple) – Figure dimensions.

  • **plot_kwargs (Any) – Arguments passed to matplotlib plot.

Returns:

Figure and relative/cumulative contribution axes.

Return type:

Figure, ndarray

py_ssa_lib.vis_tools.plot_eigenvectors(ssa: BaseSSA, components: list[int] | ndarray[tuple[int, ...], dtype[_ScalarType_co]] = array([0, 1, 2, 3, 4]), ncols: int = 2, figsize: tuple[float, float] | None = None, **plot_kwargs: Any) → tuple[Figure, ndarray[tuple[int, ...], dtype[_ScalarType_co]]][source]
Parameters:

  • ssa (BaseSSA) – Fitted SSA/MSSA model.

  • components (list[int] | NDArray) – Components to visualize.

  • ncols (int) – Number of subplot columns.

  • figsize (tuple | None) – Figure dimensions.

  • **plot_kwargs (Any) – Arguments passed to matplotlib plot.

Returns:

Figure and component axes.

Return type:

Figure, ndarray

py_ssa_lib.vis_tools.plot_elementary_matrices(ssa: BaseSSA, components: list[int] | ndarray[tuple[int, ...], dtype[_ScalarType_co]] = array([0, 1, 2, 3, 4]), ncols: int = 3, figsize: tuple[float, float] | None = None, cmap: str = 'viridis', **imshow_kwargs: Any) → tuple[Figure, ndarray[tuple[int, ...], dtype[_ScalarType_co]]][source]
Parameters:

  • ssa (BaseSSA) – Fitted SSA/MSSA model.

  • components (list[int] | NDArray) – Elementary matrices to visualize.

  • ncols (int) – Number of subplot columns.

  • figsize (tuple | None) – Figure dimensions.

  • cmap (str) – Matplotlib color map.

  • **imshow_kwargs (Any) – Arguments passed to imshow.

Returns:

Figure and matrix axes.

Return type:

Figure, ndarray

py_ssa_lib.vis_tools.plot_esprit_roots(ssa: BaseSSA, idx_components: list[int] | ndarray[tuple[int, ...], dtype[_ScalarType_co]] = array([0, 1, 2, 3, 4]), figsize: tuple[float, float] = (6, 6), circle_kwargs: dict[str, Any] | None = None, **scatter_kwargs: Any) → tuple[Figure, Axes][source]
Parameters:

  • ssa (BaseSSA) – Fitted SSA/MSSA model.

  • idx_components (list[int] | NDArray) – Components defining the ESPRIT signal subspace.

  • figsize (tuple) – Figure dimensions.

  • circle_kwargs (dict | None) – Styling arguments for the unit circle.

  • **scatter_kwargs (Any) – Arguments passed to the root scatter plot.

Returns:

Figure and ESPRIT-root axis.

Return type:

Figure, Axes

py_ssa_lib.vis_tools.plot_weighted_correlation(ssa: BaseSSA, figsize: tuple[float, float] = (7, 6), cmap: str = 'viridis', **imshow_kwargs: Any) → tuple[Figure, Axes][source]
Parameters:

  • ssa (BaseSSA) – Fitted SSA/MSSA model.

  • figsize (tuple) – Figure dimensions.

  • cmap (str) – Matplotlib color map.

  • **imshow_kwargs (Any) – Arguments passed to imshow.

Returns:

Figure and correlation-matrix axis.

Return type:

Figure, Axes