tseda.notebook_api module

Notebook-oriented API wrappers for the three-step tseda workflow.

This module exposes a stable, developer-friendly surface that mirrors the Dash UI capabilities while remaining fully scriptable in Python notebooks.

class tseda.notebook_api.SuitabilityResult(top_k_ratio: float, top_k: int, threshold: float, is_suitable: bool)[source]

Bases: object

Result object for the SSA dataset suitability check.

top_k_ratio

Fraction of total variance explained by the top-k eigenvectors.

Type:

float

top_k

Effective number of eigenvectors used in the ratio.

Type:

int

threshold

Minimum required explained-variance threshold.

Type:

float

is_suitable

True when top_k_ratio >= threshold.

Type:

bool

top_k_ratio: float
top_k: int
threshold: float
is_suitable: bool
__init__(top_k_ratio: float, top_k: int, threshold: float, is_suitable: bool) → None
class tseda.notebook_api.GroupingAutoTuneResult(grouping: dict[str, list[int]], dw_in_range: bool, durbin_watson: float | None, initial_window: int, final_window: int, windows_tried: list[int], suitability_passed: bool, reason: str)[source]

Bases: object

Result payload from automatic window reassignment for DW gating.

grouping

Final grouping assignment applied to reconstruction.

Type:

dict[str, list[int]]

dw_in_range

Whether final Durbin-Watson value is in configured range.

Type:

bool

durbin_watson

Final Durbin-Watson statistic, if available.

Type:

float | None

initial_window

Window before auto-tuning.

Type:

int

final_window

Final window after auto-tuning.

Type:

int

windows_tried

Ordered list of windows evaluated.

Type:

list[int]

suitability_passed

Whether suitability gate passed at final window.

Type:

bool

reason

Machine-readable terminal status.

Type:

str

grouping: dict[str, list[int]]
dw_in_range: bool
durbin_watson: float | None
initial_window: int
final_window: int
windows_tried: list[int]
suitability_passed: bool
reason: str
__init__(grouping: dict[str, list[int]], dw_in_range: bool, durbin_watson: float | None, initial_window: int, final_window: int, windows_tried: list[int], suitability_passed: bool, reason: str) → None
tseda.notebook_api.list_example_datasets() → list[str][source]

Return the registry keys for built-in repository example datasets.

Returns:

Sorted list of example dataset names that can be passed to load_example_series().

tseda.notebook_api.load_series_from_csv(csv_path: str | Path, timestamp_col: int | str = 0, value_col: int | str = 1, **read_csv_kwargs: Any) → pandas.Series[source]

Load a timestamp-indexed numeric series from a CSV file.

Parameters:

  • csv_path – CSV file path.

  • timestamp_col – Timestamp column index or name.

  • value_col – Numeric value column index or name.

  • **read_csv_kwargs – Extra keyword arguments forwarded to pandas.read_csv().

Returns:

Timestamp-indexed numeric series.

Raises:
tseda.notebook_api.load_example_series(dataset_name: str, workspace_root: str | Path | None = None, timestamp_col: int | str = 0, value_col: int | str = 1) → pandas.Series[source]

Load one of the repository example datasets as a pandas Series.

Parameters:

  • dataset_name – Key from EXAMPLE_DATASETS.

  • workspace_root – Optional workspace root. If omitted, uses current working directory.

  • timestamp_col – Timestamp column index or name for the source CSV.

  • value_col – Value column index or name for the source CSV.

Returns:

Timestamp-indexed numeric series for the requested dataset.

Raises:
class tseda.notebook_api.NotebookThreeStepAPI(series: pandas.Series, window: int | None = None, apply_window_refinement: bool = True)[source]

Bases: object

Notebook-first wrapper exposing the same three-step workflow as the UI.

The class keeps decomposition state (window, SSA model, grouping) so each feature can be called independently in notebooks while preserving continuity across steps.

Create a notebook workflow session for one time series.

Parameters:

  • series – Timestamp-indexed numeric input series.

  • window – Optional initial SSA window. If omitted, the cadence-based heuristic from tseda.series_stats.sampling_prop.SamplingProp is used.

  • apply_window_refinement – Whether to apply the same eigen-tail refinement loop used by the UI.

Raises:

ValueError – If a valid default window cannot be inferred.

__init__(series: pandas.Series, window: int | None = None, apply_window_refinement: bool = True) → None[source]

Create a notebook workflow session for one time series.

Parameters:

  • series – Timestamp-indexed numeric input series.

  • window – Optional initial SSA window. If omitted, the cadence-based heuristic from tseda.series_stats.sampling_prop.SamplingProp is used.

  • apply_window_refinement – Whether to apply the same eigen-tail refinement loop used by the UI.

Raises:

ValueError – If a valid default window cannot be inferred.

property series: pandas.Series

Return the validated input series.

get_configuration() → dict[str, Any][source]

Return the effective full configuration dictionary.

Returns:

Deep copy of the currently loaded tseda_config.yaml content.

get_grouping_heuristic_configuration() → dict[str, Any][source]

Return grouping heuristic configuration used for SSA auto-grouping.

Returns:

Deep copy of grouping_heuristic configuration section.

get_sampling_properties() → pandas.DataFrame[source]

Return sampling properties used in Step 1.

Returns:

DataFrame with property/value rows.

get_summary_statistics() → pandas.DataFrame[source]

Return descriptive summary statistics for the current series.

Returns:

DataFrame containing mean, variance, percentiles, skewness, and kurtosis.

get_kde_plot(show_kde: bool = True, bin_count: int | None = None, bin_algorithm: str = 'fd') → plotly.graph_objects.Figure[source]

Get the Step-1 distribution plot (histogram and optional KDE).

Parameters:

  • show_kde – Whether to overlay the KDE curve.

  • bin_count – Explicit histogram bin count.

  • bin_algorithm – Bin selection rule used when bin_count is omitted; supports numpy rules such as "scott", "fd", and "sturges".

Returns:

Plotly figure with histogram and optional KDE curve.

get_box_plot() → plotly.graph_objects.Figure[source]

Get the Step-1 box plot for value spread diagnostics.

Returns:

Plotly box plot figure.

get_scatter_plot() → plotly.graph_objects.Figure[source]

Get the Step-1 scatter/line plot with trend overlay.

Returns:

Plotly time-series scatter figure.

get_acf_plot(lags: int = 40) → plotly.graph_objects.Figure[source]

Get the Step-1 autocorrelation plot.

Parameters:

lags – Maximum lag count.

Returns:

Plotly ACF figure.

get_pacf_plot(lags: int = 40, method: str = 'yw') → plotly.graph_objects.Figure[source]

Get the Step-1 partial autocorrelation plot.

Parameters:

  • lags – Maximum lag count.

  • method – PACF estimator method forwarded to statsmodels.

Returns:

Plotly PACF figure.

get_window() → int[source]

Get the current SSA window size used by the decomposition.

Returns:

Current window size.

set_window(window: int, apply_window_refinement: bool = False) → int[source]

Set and rebuild the SSA window.

Parameters:

  • window – New SSA window size.

  • apply_window_refinement – Whether to apply refinement loop after setting.

Returns:

Effective window after optional refinement.

Raises:

ValueError – If window is not positive.

get_suitability_result(top_k_eigenvectors: int | None = None, min_explained_variance: float | None = None) → SuitabilityResult[source]

Evaluate the same top-k eigenvalue suitability gate used by the UI.

Parameters:

  • top_k_eigenvectors – Number of leading eigenvalues to sum. If omitted, uses suitability_check.top_k_eigenvectors from config.

  • min_explained_variance – Minimum required variance concentration ratio. If omitted, uses suitability_check.min_explained_variance.

Returns:

SuitabilityResult with pass/fail and computed ratios.

get_eigen_plot() → plotly.graph_objects.Figure[source]

Get Step-2 eigenvalue explained-variance plot.

Returns:

Plotly eigenvalue variance figure.

get_eigen_vector_plot() → Any[source]

Get Step-2 SSA eigenvector plot.

Returns:

Matplotlib figure generated by ssalib.

get_wcorr_plot() → Any[source]

Get Step-2 weighted-correlation matrix plot.

Returns:

Matplotlib figure with the SSA w-correlation matrix.

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

Run automatic grouping heuristic and apply the suggested grouping.

Parameters:

grouping_config – Optional per-call overrides for grouping_heuristic settings (for example pool_selection_method, kneedle_min_distance, and pair_similarity_tolerance).

Returns:

A tuple of (grouping, durbin_watson_in_range) where grouping has Trend, Seasonality, and Noise keys.

suggest_grouping_with_window_autotune(grouping_config: Mapping[str, int | float | str] | None = None, max_window: int | None = None, doubling_factor: int = 2) → GroupingAutoTuneResult[source]

Auto-suggest grouping and reassign window until DW gate is met.

The method mirrors UI behavior used during manual retries: run grouping, evaluate DW, and when not in range, increase window size and retry until either DW is satisfied or the max window limit is reached.

Parameters:

  • grouping_config – Optional overrides for grouping_heuristic.

  • max_window – Upper bound for reassignment; defaults to len(series)//2.

  • doubling_factor – Multiplier for each reassignment step.

Returns:

GroupingAutoTuneResult with final grouping, DW status, and diagnostics.

Raises:

ValueError – If doubling_factor is less than 2.

get_grouping() → dict[str, list[int]][source]

Get the active component grouping.

Returns:

Grouping dictionary. Empty dict if not set yet.

set_grouping(grouping: Mapping[str, Sequence[int]] | None = None, trend: Sequence[int] | None = None, seasonality: Sequence[int] | None = None, noise: Sequence[int] | None = None) → dict[str, list[int]][source]

Set and apply reconstruction grouping for Step 2.

You can either pass grouping directly or use explicit trend, seasonality, and noise sequences.

Parameters:

  • grouping – Mapping from group name to component indices.

  • trend – Component indices for trend.

  • seasonality – Component indices for seasonality.

  • noise – Component indices for noise.

Returns:

Normalized grouping that was applied.

Raises:

ValueError – If indices overlap or are out of range.

get_reconstruction_plot(auto_suggest_if_missing: bool = True) → plotly.graph_objects.Figure[source]

Get Step-2 reconstruction plot for currently grouped components.

Parameters:

auto_suggest_if_missing – If True and no grouping exists yet, auto-suggest and apply a grouping first.

Returns:

Plotly reconstruction figure.

Raises:

ValueError – If no grouping is set and auto suggestion is disabled.

get_change_point_plot(auto_suggest_if_missing: bool = True) → plotly.graph_objects.Figure[source]

Get Step-2 change-point plot from grouped reconstruction.

Parameters:

auto_suggest_if_missing – Whether to auto-suggest grouping if absent.

Returns:

Plotly change-point figure.

get_loess_plot(fraction: float | None = None) → plotly.graph_objects.Figure[source]

Get LOESS verification plot for the reconstructed signal.

Parameters:

fraction – LOESS fraction in (0, 1]. When omitted, uses config loess.default_fraction.

Returns:

Plotly figure with raw and LOESS-smoothed signals.

get_noise_kde_plot(bandwidth: str | float = 'scott', auto_suggest_if_missing: bool = True) → plotly.graph_objects.Figure[source]

Get a KDE plot for the reconstructed Noise component.

Parameters:

  • bandwidth – scipy.stats.gaussian_kde bandwidth specification (for example "scott", "silverman", or a scalar).

  • auto_suggest_if_missing – Whether to auto-suggest grouping if absent.

Returns:

Plotly figure with KDE of noise values.

Raises:

ValueError – If noise series is unavailable.

get_reconstruction_metadata(auto_suggest_if_missing: bool = True) → dict[str, Any][source]

Return key reconstruction diagnostics (explained variance and DW).

Parameters:

auto_suggest_if_missing – Whether to auto-suggest grouping if absent.

Returns:

Dictionary containing per-group explained variance and Durbin-Watson.

export_components_dataframe(auto_suggest_if_missing: bool = True) → pandas.DataFrame[source]

Export timestamp, trend, seasonality, and noise components as a DataFrame.

Parameters:

auto_suggest_if_missing – Whether to auto-suggest grouping if absent.

Returns:

DataFrame with timestamp, Trend, Seasonality, and Noise columns where available.

get_variance_explained_plot() → plotly.graph_objects.Figure[source]

Get Step-3 cumulative explained-variance-by-rank plot.

Returns:

Plotly figure from SSAResultSummary.

get_noise_variance_plot() → plotly.graph_objects.Figure[source]

Get Step-3 remaining-noise-variance-by-rank plot.

Returns:

Plotly figure from SSAResultSummary.

generate_observation_text() → str[source]

Get the auto-generated observation narrative for Step 3.

Returns:

Multi-paragraph text combining sampling, statistics, decomposition, and residual-diagnostic interpretation.