tseda.decomposition.automatic_grouping_heuristic module

Automatic SSA component grouping heuristics.

class tseda.decomposition.automatic_grouping_heuristic.AutomaticGroupingHeuristic(eigenvalues: numpy.ndarray, pool_selection_method: str = 'kneedle', variance_threshold: float = 0.1, pair_similarity_tolerance: float = 0.05, kneedle_min_distance: float = 0.03, min_signal_components: int = 1, min_noise_components: int = 2)

Bases: object

Suggest SSA grouping labels from the eigenvalue spectrum.

The initial trend/seasonality candidate pool is selected from the leading eigenvalues up to a detected noise floor (kneedle-style elbow on the normalized log-spectrum). Near-equal adjacent pairs are treated as seasonal pairs; the remaining eligible components are treated as trend. All other components fall into noise.

eigenvalues: numpy.ndarray

pool_selection_method: str

variance_threshold: float

pair_similarity_tolerance: float

kneedle_min_distance: float

min_signal_components: int

min_noise_components: int

property explained_variance_ratios: numpy.ndarray

Return per-component explained variance ratios.

is_near_equal_pair(left_index: int, right_index: int) → bool

Return True when two eigenvalues differ by at most the configured tolerance.

has_seasonal_pair(max_components: int | None = None) → bool

Return True when any adjacent eligible pair satisfies the similarity rule.

eligible_component_indices() → list[int]

Return initial signal-pool component indices for grouping.

Default strategy uses a kneedle-style elbow to estimate the noise floor. Legacy variance_threshold mode is retained as a configurable fallback.

suggest_reconstruction() → dict[str, list[int]]

Return a trend/seasonality/noise grouping suggestion.

suggest_next_expansion(current: dict[str, list[int]]) → tuple[dict[str, list[int]], bool]

Expand the current assignment by one step from the noise pool.

Takes the lowest-index (highest-eigenvalue) component in the noise pool. If it and its immediate successor form a near-equal adjacent pair, both are added to seasonality; otherwise the single component is added to trend.

Returns:

A tuple of the updated assignment dict and True when an expansion was made, or (current, False) when the noise pool is exhausted.

__init__(eigenvalues: numpy.ndarray, pool_selection_method: str = 'kneedle', variance_threshold: float = 0.1, pair_similarity_tolerance: float = 0.05, kneedle_min_distance: float = 0.03, min_signal_components: int = 1, min_noise_components: int = 2) → None