# etna-team/etna architecture

> Architecture diagram of the GitHub repository etna-team/etna, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-05-19). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/etna-team/etna
- Repository: https://github.com/etna-team/etna

## Overview

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: [`etna/pipeline`](https://github.com/etna-team/etna/tree/master/etna/pipeline) (Pipeline), [`etna/models`](https://github.com/etna-team/etna/tree/master/etna/models) (Models), [`etna/datasets/tsdataset.py`](https://github.com/etna-team/etna/blob/master/etna/datasets/tsdataset.py) (TSDataset), [`tests`](https://github.com/etna-team/etna/tree/master/tests) (Tests)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_core["Core Forecasting"]
  node_tsdataset[("TSDataset<br/>data model<br/>[tsdataset.py]")]
  node_transforms["Transforms<br/>feature prep"]
  node_models["Models"]
  node_pipeline["Pipeline<br/>orchestration"]
  node_metrics(("Metrics<br/>evaluation"))
  node_prediction_intervals["Intervals<br/>uncertainty"]
  node_analysis["Analysis<br/>diagnostics"]
end

subgraph group_extensions["Extensions"]
  node_auto["AutoML<br/>search orchestration"]
  node_ensembles["Ensembles<br/>forecast combination"]
  node_clustering["Clustering<br/>series grouping"]
  node_reconciliation["Reconciliation<br/>hierarchy alignment"]
  node_experimental["Experimental<br/>research features"]
end

subgraph group_support["Support"]
  node_commands["Commands<br/>CLI entrypoints"]
  node_loggers["Loggers<br/>observability"]
  node_core_utils["Core utils<br/>shared infra"]
  node_libs["Third-party libs<br/>adapters"]
  node_docs["Docs<br/>documentation"]
  node_examples["Examples<br/>notebooks"]
  node_benchmarks["Benchmarks<br/>performance"]
  node_tests["Tests<br/>verification"]
end

node_tsdataset -->|"input"| node_transforms
node_tsdataset -->|"train on"| node_models
node_transforms -->|"fit/apply"| node_pipeline
node_models -->|"forecast via"| node_pipeline
node_pipeline -->|"evaluate"| node_metrics
node_pipeline -->|"uncertainty"| node_prediction_intervals
node_models -->|"outputs"| node_prediction_intervals
node_analysis -->|"inspect"| node_models
node_analysis -->|"diagnose"| node_pipeline
node_auto -->|"search over"| node_pipeline
node_auto -->|"sample"| node_models
node_ensembles -->|"compose"| node_pipeline
node_clustering -->|"segment data"| node_tsdataset
node_reconciliation -->|"post-process"| node_pipeline
node_experimental -->|"reuse"| node_tsdataset
node_commands -->|"run"| node_pipeline
node_loggers -->|"report"| node_auto
node_core_utils -->|"support"| node_pipeline
node_libs -->|"wrap"| node_models
node_libs -->|"embed"| node_transforms
node_docs -.->|"document"| node_pipeline
node_examples -.->|"demonstrate"| node_pipeline
node_benchmarks -.->|"measure"| node_pipeline
node_tests -.->|"cover"| node_tsdataset
node_tests -.->|"cover"| node_transforms
node_tests -.->|"cover"| node_models
node_tests -.->|"cover"| node_pipeline

click node_tsdataset "https://github.com/etna-team/etna/blob/master/etna/datasets/tsdataset.py"
click node_transforms "https://github.com/etna-team/etna/tree/master/etna/transforms"
click node_models "https://github.com/etna-team/etna/tree/master/etna/models"
click node_pipeline "https://github.com/etna-team/etna/tree/master/etna/pipeline"
click node_metrics "https://github.com/etna-team/etna/tree/master/etna/metrics"
click node_prediction_intervals "https://github.com/etna-team/etna/tree/master/etna/prediction_intervals"
click node_analysis "https://github.com/etna-team/etna/tree/master/etna/analysis"
click node_auto "https://github.com/etna-team/etna/tree/master/etna/auto"
click node_ensembles "https://github.com/etna-team/etna/tree/master/etna/ensembles"
click node_clustering "https://github.com/etna-team/etna/tree/master/etna/clustering"
click node_reconciliation "https://github.com/etna-team/etna/tree/master/etna/reconciliation"
click node_experimental "https://github.com/etna-team/etna/tree/master/etna/experimental"
click node_commands "https://github.com/etna-team/etna/tree/master/etna/commands"
click node_loggers "https://github.com/etna-team/etna/tree/master/etna/loggers"
click node_core_utils "https://github.com/etna-team/etna/tree/master/etna/core"
click node_libs "https://github.com/etna-team/etna/tree/master/etna/libs"
click node_docs "https://github.com/etna-team/etna/tree/master/docs"
click node_examples "https://github.com/etna-team/etna/tree/master/examples"
click node_benchmarks "https://github.com/etna-team/etna/tree/master/benchmarks/perfomance"
click node_tests "https://github.com/etna-team/etna/tree/master/tests"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_tsdataset,node_transforms,node_models,node_pipeline,node_metrics,node_prediction_intervals,node_analysis toneBlue
class node_auto,node_ensembles,node_clustering,node_reconciliation,node_experimental toneAmber
class node_commands,node_loggers,node_core_utils,node_libs,node_docs,node_examples,node_benchmarks,node_tests toneMint
```

## Components

### Core Forecasting

Primary data model, transforms, models, pipelines, metrics, and intervals.

- [TSDataset](https://github.com/etna-team/etna/blob/master/etna/datasets/tsdataset.py): data model · Unified multisegment time-series container consumed by most library subsystems. · `etna/datasets/tsdataset.py`
- [Transforms](https://github.com/etna-team/etna/tree/master/etna/transforms): feature prep · Composable preprocessing, feature engineering, decomposition, and inverse-transform logic. · `etna/transforms`
- [Models](https://github.com/etna-team/etna/tree/master/etna/models): forecast models · Unified forecasting model interfaces and implementations across classical, ML, and neural approaches. · `etna/models`
- [Pipeline](https://github.com/etna-team/etna/tree/master/etna/pipeline): orchestration · Coordinates transform fitting, model training, forecasting, and backtesting flows. · `etna/pipeline`
- [Metrics](https://github.com/etna-team/etna/tree/master/etna/metrics): evaluation · Segment-aware and interval-aware scoring for forecasts and predictions. · `etna/metrics`
- [Intervals](https://github.com/etna-team/etna/tree/master/etna/prediction_intervals): uncertainty · Conformal, empirical, and naive-variance prediction interval methods. · `etna/prediction_intervals`
- [Analysis](https://github.com/etna-team/etna/tree/master/etna/analysis): diagnostics · Read-only post-modeling plots and diagnostics for interpretation and debugging. · `etna/analysis`

### Extensions

Optional capabilities that build on the core forecasting abstractions.

- [AutoML](https://github.com/etna-team/etna/tree/master/etna/auto): search orchestration · Automated model selection and hyperparameter tuning over the pipeline API. · `etna/auto`
- [Ensembles](https://github.com/etna-team/etna/tree/master/etna/ensembles): forecast combination · Voting, stacking, and direct ensemble strategies at the pipeline level. · `etna/ensembles`
- [Clustering](https://github.com/etna-team/etna/tree/master/etna/clustering): series grouping · Distance-based clustering for grouping and comparing time series. · `etna/clustering`
- [Reconciliation](https://github.com/etna-team/etna/tree/master/etna/reconciliation): hierarchy alignment · Bottom-up and top-down forecast reconciliation for hierarchical series. · `etna/reconciliation`
- [Experimental](https://github.com/etna-team/etna/tree/master/etna/experimental): research features · Classification and change-point tooling built on the same dataset conventions. · `etna/experimental`

### Support

Operational, documentation, examples, benchmarking, and repository tooling.

- [Commands](https://github.com/etna-team/etna/tree/master/etna/commands): CLI entrypoints · Forecast and backtest command-line entry points and resolvers. · `etna/commands`
- [Loggers](https://github.com/etna-team/etna/tree/master/etna/loggers): observability · Console, file, ClearML, and Weights & Biases logging adapters. · `etna/loggers`
- [Core utils](https://github.com/etna-team/etna/tree/master/etna/core): shared infra · Mixins, serialization, and package-wide utilities shared across modules. · `etna/core`
- [Third-party libs](https://github.com/etna-team/etna/tree/master/etna/libs): adapters · Adapters and wrappers around external forecasting and representation libraries. · `etna/libs`
- [Docs](https://github.com/etna-team/etna/tree/master/docs): documentation · Sphinx documentation site and API reference. · `docs`
- [Examples](https://github.com/etna-team/etna/tree/master/examples): notebooks · Runnable notebooks and demos covering workflows and advanced usage. · `examples`
- [Benchmarks](https://github.com/etna-team/etna/tree/master/benchmarks/perfomance): performance · Performance measurement configs, scripts, and reports. · `benchmarks/perfomance`
- [Tests](https://github.com/etna-team/etna/tree/master/tests): verification · Unit and integration coverage mirroring the package structure. · `tests`

## Connections

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