tseda package

tseda package.

class tseda.NotebookThreeStepAPI(series: pandas.Series, window: int | None = None, apply_window_refinement: bool = True)

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

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]

Return the effective full configuration dictionary.

Returns:

Deep copy of the currently loaded tseda_config.yaml content.

get_grouping_heuristic_configuration() → dict[str, Any]

Return grouping heuristic configuration used for SSA auto-grouping.

Returns:

Deep copy of grouping_heuristic configuration section.

get_sampling_properties() → pandas.DataFrame

Return sampling properties used in Step 1.

Returns:

DataFrame with property/value rows.

get_summary_statistics() → pandas.DataFrame

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

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

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

Returns:

Plotly box plot figure.

get_scatter_plot() → plotly.graph_objects.Figure

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

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

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

Get the current SSA window size used by the decomposition.

Returns:

Current window size.

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

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

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

Get Step-2 eigenvalue explained-variance plot.

Returns:

Plotly eigenvalue variance figure.

get_eigen_vector_plot() → Any

Get Step-2 SSA eigenvector plot.

Returns:

Matplotlib figure generated by ssalib.

get_wcorr_plot() → Any

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]

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

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]]

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]]

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

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

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

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

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]

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

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

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

Returns:

Plotly figure from SSAResultSummary.

get_noise_variance_plot() → plotly.graph_objects.Figure

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

Returns:

Plotly figure from SSAResultSummary.

generate_observation_text() → str

Get the auto-generated observation narrative for Step 3.

Returns:

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

class tseda.SuitabilityResult(top_k_ratio: float, top_k: int, threshold: float, is_suitable: bool)

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

tseda.list_example_datasets() → list[str]

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.load_example_series(dataset_name: str, workspace_root: str | Path | None = None, timestamp_col: int | str = 0, value_col: int | str = 1) → pandas.Series

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:

• KeyError – If the dataset name is unknown.

• FileNotFoundError – If the resolved CSV path does not exist.

• ValueError – If datetime/value parsing fails.

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

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:

• FileNotFoundError – If the CSV path does not exist.

• ValueError – If no valid datetime/value rows are parsed.

Subpackages

• tseda.change_point namespace
  • Submodules
    • tseda.change_point.change_point_estimator module
      • PELT_ChangePointEstimator
      • ChangePointEstimator
• tseda.config namespace
  • Submodules
    • tseda.config.config_loader module
      • ConfigurationManager
      • get_config()
      • get_config_section()
• tseda.data_writers namespace
  • Submodules
    • tseda.data_writers.kmds_writer module
• tseda.dataloader namespace
  • Submodules
    • tseda.dataloader.coffee_prices_data_loader module
      • CoffeePricesDataLoader
    • tseda.dataloader.hyndman_examples_data_loader module
      • HyndmanExamplesDataLoader
    • tseda.dataloader.kaggle_data_loader module
    • tseda.dataloader.kmds_data_loader module
    • tseda.dataloader.local_dataloader module
      • LocalDataLoader
    • tseda.dataloader.synthetic_series_data_loader module
      • SyntheticSeriesDataLoader
    • tseda.dataloader.ticket_resolution_data_loader module
      • TicketResolutionDataLoader
    • tseda.dataloader.uci_air_quality_data_loader module
      • UCIAirQualityDataLoader
    • tseda.dataloader.white_noise_data_loader module
      • WhiteNoiseDataLoader
• tseda.decomposition namespace
  • Submodules
    • tseda.decomposition.automatic_grouping_heuristic module
      • AutomaticGroupingHeuristic
    • tseda.decomposition.ssa_decomposition module
      • SSADecomposition
    • tseda.decomposition.ssa_result_summary module
      • SSAResultSummary
• tseda.periodicity namespace
  • Submodules
    • tseda.periodicity.fft_analyzer module
      • FFT_Analyzer
• tseda.series_stats namespace
  • Submodules
    • tseda.series_stats.sampling_prop module
      • SamplingProp
    • tseda.series_stats.summary_statistics module
      • SummaryStatistics
• tseda.visualization namespace
  • Submodules
    • tseda.visualization.autocorrelation_vis module
      • ACFPlotter
    • tseda.visualization.series_histogram_visualizer module
      • SeriesHistogramVisualizer
    • tseda.visualization.series_kde_visualizer module
      • SeriesKDEVisualizer
    • tseda.visualization.series_visualizer module
      • SeriesVisualizer
      • SegmentedSeriesVisualizer

Submodules

• tseda.bump_version module
  • Usage
  • main()
• tseda.notebook_api module
  • SuitabilityResult
    • SuitabilityResult.top_k_ratio
    • SuitabilityResult.top_k
    • SuitabilityResult.threshold
    • SuitabilityResult.is_suitable
    • SuitabilityResult.top_k_ratio
    • SuitabilityResult.top_k
    • SuitabilityResult.threshold
    • SuitabilityResult.is_suitable
    • SuitabilityResult.__init__()
  • GroupingAutoTuneResult
    • GroupingAutoTuneResult.grouping
    • GroupingAutoTuneResult.dw_in_range
    • GroupingAutoTuneResult.durbin_watson
    • GroupingAutoTuneResult.initial_window
    • GroupingAutoTuneResult.final_window
    • GroupingAutoTuneResult.windows_tried
    • GroupingAutoTuneResult.suitability_passed
    • GroupingAutoTuneResult.reason
    • GroupingAutoTuneResult.grouping
    • GroupingAutoTuneResult.dw_in_range
    • GroupingAutoTuneResult.durbin_watson
    • GroupingAutoTuneResult.initial_window
    • GroupingAutoTuneResult.final_window
    • GroupingAutoTuneResult.windows_tried
    • GroupingAutoTuneResult.suitability_passed
    • GroupingAutoTuneResult.reason
    • GroupingAutoTuneResult.__init__()
  • list_example_datasets()
  • load_series_from_csv()
  • load_example_series()
  • NotebookThreeStepAPI
    • NotebookThreeStepAPI.__init__()
    • NotebookThreeStepAPI.series
    • NotebookThreeStepAPI.get_configuration()
    • NotebookThreeStepAPI.get_grouping_heuristic_configuration()
    • NotebookThreeStepAPI.get_sampling_properties()
    • NotebookThreeStepAPI.get_summary_statistics()
    • NotebookThreeStepAPI.get_kde_plot()
    • NotebookThreeStepAPI.get_box_plot()
    • NotebookThreeStepAPI.get_scatter_plot()
    • NotebookThreeStepAPI.get_acf_plot()
    • NotebookThreeStepAPI.get_pacf_plot()
    • NotebookThreeStepAPI.get_window()
    • NotebookThreeStepAPI.set_window()
    • NotebookThreeStepAPI.get_suitability_result()
    • NotebookThreeStepAPI.get_eigen_plot()
    • NotebookThreeStepAPI.get_eigen_vector_plot()
    • NotebookThreeStepAPI.get_wcorr_plot()
    • NotebookThreeStepAPI.suggest_grouping()
    • NotebookThreeStepAPI.suggest_grouping_with_window_autotune()
    • NotebookThreeStepAPI.get_grouping()
    • NotebookThreeStepAPI.set_grouping()
    • NotebookThreeStepAPI.get_reconstruction_plot()
    • NotebookThreeStepAPI.get_change_point_plot()
    • NotebookThreeStepAPI.get_loess_plot()
    • NotebookThreeStepAPI.get_noise_kde_plot()
    • NotebookThreeStepAPI.get_reconstruction_metadata()
    • NotebookThreeStepAPI.export_components_dataframe()
    • NotebookThreeStepAPI.get_variance_explained_plot()
    • NotebookThreeStepAPI.get_noise_variance_plot()
    • NotebookThreeStepAPI.generate_observation_text()