tseda.series_stats.sampling_prop module

Sampling property utilities for time-series metadata and SSA window heuristics.

class tseda.series_stats.sampling_prop.SamplingProp(series: pandas.Series)

Bases: object

Compute and expose sampling-related properties for a time series.

Initialize summary metadata for a timestamp-indexed series.

Parameters:

series – Numeric series indexed by datetimes.

__init__(series: pandas.Series) → None

Initialize summary metadata for a timestamp-indexed series.

Parameters:

series – Numeric series indexed by datetimes.

view_properties() → pandas.DataFrame

Return a tabular view of sampling metadata.

Returns:

DataFrame with property and value columns.

properties_data_table() → Any

Return sampling properties as a Dash AgGrid component.

This compatibility method is kept for callers/tests that rely on the previous API surface.

Returns:

Dash AgGrid component with the sampling property rows.

get_readable_freq(series: pandas.Series) → str

Infer and map pandas frequency aliases to readable labels.

Parameters:

series – Timestamp-indexed input series.

Returns:

Human-readable frequency label.

get_freq_window(index: pandas.Index) → int | None

Map pandas inferred frequency to a default SSA window size.

Heuristic rationale

The window in Singular Spectrum Analysis (SSA) controls the width of the trajectory matrix. A sensible starting point is one full dominant seasonal cycle so that the periodic structure appears as a pair of near-equal eigenvalues in the eigen spectrum. The table below lists the cadence-to- window mapping used as the initial assignment:

Cadence	Window	Rationale
Hourly	24	One diurnal (24-hour) cycle
Daily	5	One business week (5 trading/working days)
Weekly	4	Approximately one calendar month (4 weeks)
Monthly	12	One full annual cycle (12 months)

Required invariant after refinement

The initial value returned here is a candidate, not a final answer. At SSA construction time the caller must verify that the smallest eigenvalue explains strictly less than 10 % of total variance. If it does not, the window is doubled and SSA is recomputed; this doubling is repeated until the invariant holds or the window would exceed half the series length. The invariant ensures that the eigen spectrum has meaningful spread — i.e. the decomposition is not degenerate — and prevents the smallest component from carrying too much signal that should have been separated into distinct eigenmodes.

Parameters:

index – Datetime index from the source series.

Returns:

Initial candidate SSA window size for the inferred frequency, or None when the frequency cannot be determined.