tseda.decomposition.automatic_grouping_heuristic module

Automatic SSA component grouping heuristics.

class tseda.decomposition.automatic_grouping_heuristic.AutomaticGroupingHeuristic(eigenvalues: numpy.ndarray, variance_threshold: float = 0.1, pair_similarity_tolerance: float = 0.05)

Bases: object

Suggest SSA grouping labels from the eigenvalue spectrum.

Components explaining at least variance_threshold of total variance are classified as either trend or seasonality. 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

variance_threshold: float

pair_similarity_tolerance: float

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 component indices meeting the minimum explained-variance threshold.

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, variance_threshold: float = 0.1, pair_similarity_tolerance: float = 0.05) → None