How etna-team/etna works
1. What this repository is
ETNA is a Python time-series forecasting framework, not a single application. Its core product is a reusable library that standardizes how tabular time-series data is represented, transformed, modeled, evaluated, and deployed for inference.
2. Central data model
The architectural center is etna.datasets.TSDataset. It wraps multisegment time-series data into a unified structure that most other subsystems consume. This dataset abstraction is the main boundary between raw input data and all higher-level forecasting, analysis, and transformation logic.
3. Primary forecasting flow
The typical execution path is: raw data → TSDataset → transforms → model → Pipeline → forecast. etna.pipeline orchestrates this lifecycle, while etna.models provides model implementations and etna.transforms provides feature engineering, preprocessing, and inverse-transform support.
4. Transform layer
etna.transforms is one of the largest subsystems and covers most data preparation concerns: missing values, lag and rolling statistics, timestamp features, decomposition, outlier handling, encoders, embeddings, and feature selection. Transforms are designed to be composable and to preserve enough state for later inverse transformation or inference on future horizons.
5. Model layer
etna.models contains classical statistical models, machine-learning wrappers, and neural network models. The model interface is intentionally unified so the pipeline can swap implementations without changing surrounding code. There are also adapter modules for external libraries such as Prophet, statsforecast, PyTorch-based models, Chronos, and TimesFM.
6. Forecasting strategies and higher-level composition
etna.pipeline includes specialized pipeline variants such as autoregressive and hierarchical pipelines. etna.ensembles adds voting, stacking, and direct ensemble strategies, letting forecasts from multiple models be combined at the pipeline level rather than inside each model.
7. Evaluation and uncertainty
etna.metrics provides segment-aware metrics and interval metrics. etna.prediction_intervals adds multiple approaches for uncertainty estimation, including conformal, empirical, and naive-variance methods. These sit on the evaluation/prediction boundary and consume model outputs rather than raw data.
8. Analysis and diagnostics
etna.analysis is the post-modeling toolbox: EDA plots, forecast plots, decomposition search, feature relevance, feature selection diagnostics, and outlier analysis. This subsystem is mostly read-only on forecast artifacts and is intended for interpretation, debugging, and reporting rather than training.
9. Automation and tuning
etna.auto provides AutoML-style orchestration around model search and hyperparameter tuning. It integrates Optuna-based sampling and local runners, acting as a control layer above the standard pipeline/model API rather than a separate modeling stack.
10. Advanced and experimental capabilities
etna.clustering, etna.reconciliation, and etna.experimental cover less-central but important extensions: clustering time series, hierarchical forecast reconciliation, and experimental classification/change-point tools. These modules expand ETNA beyond standard forecasting while still reusing the same dataset and transform conventions.
11. Integration and operational boundaries
etna.commands exposes CLI-style entry points such as forecast and backtest commands. etna.loggers centralizes output to console, files, ClearML, and Weights & Biases. etna.core contains shared mixins, serialization, and utility code that enforce common behavior across the package.
12. Repository support structure
The repository is organized as a mature Python package: tests mirrors the library structure for unit and integration coverage, examples provides notebooks and runnable demos, docs is a Sphinx documentation site, and benchmarks measures performance. GitHub Actions, Docker images, and optional extras in packaging show that ETNA is built for both library distribution and reproducible experimentation.
Main entry points: pipeline Pipeline · models Models · tsdataset.py TSDataset · tests Tests
Components 20
Core Forecasting
Primary data model, transforms, models, pipelines, metrics, and intervals.
- TSDataset · Unified multisegment time-series container consumed by most library subsystems.
etna/datasets/tsdataset.py - Transforms · Composable preprocessing, feature engineering, decomposition, and inverse-transform logic.
etna/transforms - Models · Unified forecasting model interfaces and implementations across classical, ML, and neural approaches.
etna/models - Pipeline · Coordinates transform fitting, model training, forecasting, and backtesting flows.
etna/pipeline - Metrics · Segment-aware and interval-aware scoring for forecasts and predictions.
etna/metrics - Intervals · Conformal, empirical, and naive-variance prediction interval methods.
etna/prediction_intervals - Analysis · Read-only post-modeling plots and diagnostics for interpretation and debugging.
etna/analysis
Extensions
Optional capabilities that build on the core forecasting abstractions.
- AutoML · Automated model selection and hyperparameter tuning over the pipeline API.
etna/auto - Ensembles · Voting, stacking, and direct ensemble strategies at the pipeline level.
etna/ensembles - Clustering · Distance-based clustering for grouping and comparing time series.
etna/clustering - Reconciliation · Bottom-up and top-down forecast reconciliation for hierarchical series.
etna/reconciliation - Experimental · Classification and change-point tooling built on the same dataset conventions.
etna/experimental
Support
Operational, documentation, examples, benchmarking, and repository tooling.
- Commands · Forecast and backtest command-line entry points and resolvers.
etna/commands - Loggers · Console, file, ClearML, and Weights & Biases logging adapters.
etna/loggers - Core utils · Mixins, serialization, and package-wide utilities shared across modules.
etna/core - Third-party libs · Adapters and wrappers around external forecasting and representation libraries.
etna/libs - Docs · Sphinx documentation site and API reference.
docs - Examples · Runnable notebooks and demos covering workflows and advanced usage.
examples - Benchmarks · Performance measurement configs, scripts, and reports.
benchmarks/perfomance - Tests · Unit and integration coverage mirroring the package structure.
tests
Connections 27
- TSDataset → Transforms: input · Transforms operate on the unified dataset representation.
- TSDataset → Models: train on · Models consume standardized time-series data from TSDataset.
- Transforms → Pipeline: fit/apply · Pipeline coordinates transform fitting and application.
- Models → Pipeline: forecast via · Pipeline trains models and collects predictions.
- Pipeline → Metrics: evaluate · Backtest and validation flows score forecasts with metrics.
- Pipeline → Intervals: uncertainty · Pipelines can attach interval estimation to forecasts.
- Models → Intervals: outputs · Interval methods consume model predictions and residual behavior.
- Analysis → Models: inspect · Analysis tools interpret forecast and model artifacts.
- Analysis → Pipeline: diagnose · Plots and diagnostics operate on pipeline outputs.
- AutoML → Pipeline: search over · AutoML orchestrates repeated pipeline runs during tuning.
- AutoML → Models: sample · Search spaces include model and parameter selection.
- Ensembles → Pipeline: compose · Ensembles combine forecasts at the pipeline level.
- Clustering → TSDataset: segment data · Clustering works over multisegment datasets and derived distances.
- Reconciliation → Pipeline: post-process · Hierarchical reconciliation adjusts pipeline forecasts.
- Experimental → TSDataset: reuse · Experimental tools follow the same dataset conventions.
- Commands → Pipeline: run · CLI entrypoints trigger forecasting and backtesting workflows.
- Loggers → AutoML: report · Tuning workflows emit logs and experiment tracking.
- Core utils → Pipeline: support · Shared mixins and serialization underpin core components.
- Third-party libs → Models: wrap · External library integrations are exposed as model implementations.
- Third-party libs → Transforms: embed · Some transform families depend on external representation libraries.
- Docs → Pipeline: document · Documentation describes the main forecasting workflow.
- Examples → Pipeline: demonstrate · Notebooks showcase training, evaluation, and inference flows.
- Benchmarks → Pipeline: measure · Benchmarks assess runtime and throughput of key workflows.
- Tests → TSDataset: cover · Tests mirror and validate the dataset abstraction.
- Tests → Transforms: cover · Tests validate transform behavior and inverse transformation.
- Tests → Models: cover · Tests validate model implementations and inference.
- Tests → Pipeline: cover · Tests validate orchestration, strategies, and backtesting.