tseda.decomposition.ssa_decomposition module

Singular Spectrum Analysis decomposition and reconstruction utilities.

class tseda.decomposition.ssa_decomposition.SSADecomposition(series: pandas.Series, window: int)

Bases: object

A class to perform Singular Spectrum Analysis (SSA) on a time series.

Initialize SSA decomposition for a timestamp-indexed series.

Parameters:

• series – Input numeric series indexed by datetime.

• window – Window size for SSA trajectory matrix construction.

__init__(series: pandas.Series, window: int) → None

Initialize SSA decomposition for a timestamp-indexed series.

Parameters:

• series – Input numeric series indexed by datetime.

• window – Window size for SSA trajectory matrix construction.

seasonality_check_heuristic() → bool

Heuristic seasonality check based on near-equal leading eigenvalues.

If any pair among the configured leading eigenvalues has a smaller/larger ratio of at least 0.95, mark the internal seasonality flag as True.

get_automatic_grouping_heuristic(grouping_config: dict[str, int | float | str] | None = None) → AutomaticGroupingHeuristic

Return the automatic grouping heuristic for the current eigen spectrum.

Parameters:

grouping_config – Optional per-call overrides for grouping_heuristic.* settings.

suggest_reconstruction_groups(grouping_config: dict[str, int | float | str] | None = None) → tuple[dict[str, list[int]], bool]

Return the best auto-inferred grouping and a Durbin-Watson satisfied flag.

Starting from the threshold-based initial assignment, the method expands the assignment one component (or one seasonal pair) at a time until the Durbin-Watson statistic of the noise residual falls in [dw_low, dw_high] or the candidate pool is exhausted. The assignment with the DW value closest to 2.0 is returned. When no assignment achieves a DW in range the flag is False, signalling the caller to prompt the user to try a different window.

Side effect: leaves SSA reconstruction state set to the returned assignment.

get_reconstructed_series(group_key: str) → pd.Series | None

Return a cached reconstructed series by case-insensitive group key.

Parameters:

group_key – Requested group label.

Returns:

Reconstructed series for the key, or None if unavailable.

get_group_series(group_key: str) → pd.Series | None

Alias for get_reconstructed_series for external callers.

eigenplot() → plotly.graph_objects.Figure

Create the explained-variance-by-component line plot.

Returns:

Plotly figure with component explained variance.

eigen_vector_plot() → matplotlib.pyplot.Figure

Return the SSA eigenvector matplotlib figure.

set_reconstruction(recon: dict[str, list[int]]) → None

Set decomposition groups used for signal reconstruction.

Parameters:

recon – Mapping of group names to component index lists.

wcorr_plot() → matplotlib.pyplot.Figure

Create a plot of the w-correlation matrix.

signal_reconstruction_plot() → plotly.graph_objects.Figure

Return a signal reconstruction plot for raw, smoothed, and grouped series.

This call also refreshes and caches reconstruction products and updates the seasonality heuristic flag.

loess_smother(fraction: float) → plotly.graph_objects.Figure

Fit a LOESS curve to the SSA preprocessed signal.

Parameters:

fraction – Fraction of data used for each local regression in LOESS.

Returns:

Figure with raw and LOESS-smoothed signals.

change_point_plot() → plotly.graph_objects.Figure

Return a change-point analysis plot using the smoothed signal.

Two independent PELT detectors are run:

• Trend shifts — PELT on the z-score-normalised Trend component (l2 cost, penalty log(n)). Rendered as vertical dashed lines.

• Seasonal amplitude shifts — PELT on the z-score-normalised rolling-RMS envelope of the Seasonality component, with a rolling window equal to the SSA window size (l2 cost, penalty log(n)). Rendered as vertical dotted lines.

The smoothed signal (trend + all non-noise components) is plotted as a single continuous trace. A plain-language summary of detected changes is appended below the plot.

explained_variance_by_group(group_name: str) → float

Return the explained variance (%) for a named reconstruction group.

The lookup is case-insensitive. Returns 0.0 if the group is not present in the reconstruction map.

Parameters:

group_name (str) – The group name as used in set_reconstruction().

Returns:

Explained variance percentage (0–100).

Return type:

float

explained_variance_trend() → float

Return the explained variance (%) attributed to the trend group.

Searches for a reconstruction group whose name contains ‘trend’ (case-insensitive).

Returns:

Explained variance percentage (0–100), or 0.0 if no trend group is defined.

Return type:

float

explained_variance_seasonality() → float

Return the explained variance (%) attributed to the seasonality group.

Searches for a reconstruction group whose name contains ‘season’ (case-insensitive).

Returns:

Explained variance percentage (0–100), or 0.0 if no seasonality group is defined.

Return type:

float

explained_variance_noise() → float

Return the explained variance (%) attributed to the noise group.

Searches for a reconstruction group whose name contains ‘noise’ (case-insensitive).

Returns:

Explained variance percentage (0–100), or 0.0 if no noise group is defined.

Return type:

float