# nixtla/tsfeatures architecture

> Architecture diagram of the GitHub repository nixtla/tsfeatures, 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/nixtla/tsfeatures
- Repository: https://github.com/nixtla/tsfeatures

## Overview

1. **Repository purpose**
   - This is a Python package for extracting time-series features from a panel of series.
   - It mirrors the R package `tsfeatures` and is oriented around producing standardized feature vectors for forecasting/meta-learning workflows, especially the FFORMA feature set.

2. **Primary entry point**
   - The main public API lives in `tsfeatures/tsfeatures.py`.
   - The top-level import pattern in the README (`from tsfeatures import tsfeatures`) suggests this module exposes the core orchestration function that runs feature extraction over a pandas DataFrame.

3. **Input/output boundary**
   - The package expects a panel-style DataFrame with columns `unique_id`, `ds`, and `y`.
   - It can either take a fixed frequency or infer it from timestamps, then returns per-series feature values.
   - A built-in frequency-to-seasonal-period mapping is part of the architecture (`H`, `D`, `M`, `Q`, `W`, `Y`), with an override hook via `dict_freqs`.

4. **Feature computation layer**
   - Individual feature implementations are organized around metric functions in `tsfeatures/metrics/metrics.py`.
   - `tsfeatures/metrics/__init__.py` likely re-exports these feature functions so they can be passed as callables into the main pipeline.
   - The README shows the architecture is designed for composability: users can select built-in features or inject custom functions with the same `x, freq` signature.

5. **Pipeline orchestration**
   - The `tsfeatures` pipeline is responsible for splitting the panel by series, preparing each series as a numeric array, and invoking the selected feature functions.
   - The presence of tests such as `test_pipeline.py`, `test_mutability.py`, and `test_small_ts.py` indicates the pipeline also handles edge cases like short series, side effects, and output consistency.

6. **Supporting utilities**
   - `tsfeatures/utils.py` contains shared helpers used across feature calculations and/or preprocessing.
   - `tsfeatures/m4_data.py` appears to provide bundled sample data or dataset helpers, likely used for validation and comparisons against the M4 benchmark context described in the README.

7. **R interoperability boundary**
   - `tsfeatures/tsfeatures_r.py` is a separate integration path that calls the R implementation from Python.
   - This requires `rpy2` plus R packages `forecast` and `tsfeatures`, and it accepts feature names as strings rather than Python callables.
   - Architecturally, this module is a bridge to an external runtime, not part of the pure-Python computation path.

8. **Benchmarking and validation against R**
   - `tsfeatures/compare_with_r.py` is a command-line comparison tool for running the Python implementation against the R version on M4 subsets.
   - This is important architecturally because it establishes a reference-validation workflow for feature parity and regression checking.

9. **Test structure**
   - Tests are organized by feature family: autocorrelation (`test_acf_features.py`, `test_pacf_features.py`), statistics (`test_statistics.py`), sparsity, ARCH, Holt parameters, and pipeline behavior.
   - This reflects a modular architecture where each feature group is independently verifiable, rather than a single monolithic algorithm.

10. **Packaging and delivery**
   - The repo is a standard Python package with `setup.py` and `requirements.txt`.
   - GitHub Actions workflows handle CI builds and publishing to PyPI, so the package lifecycle includes automated testing, release packaging, and distribution.

11. **External dependencies that matter architecturally**
   - Core runtime is Python with pandas/numpy-style time-series processing.
   - The optional R bridge adds a second execution environment, which is relevant for deployments that need exact parity with the original R package.
   - The package is designed for library use rather than as an application server or UI.

12. **How to diagram the data flow**
   - The main flow is: panel DataFrame in → frequency handling/inference → per-series feature selection → feature functions in `metrics` and related modules → feature dictionary/DataFrame out.
   - A separate optional flow exists for R parity: panel DataFrame in → `tsfeatures_r` → R `tsfeatures` package via `rpy2` → comparison/validation results out.

Main entry points: [`tsfeatures/tsfeatures.py`](https://github.com/nixtla/tsfeatures/blob/main/tsfeatures/tsfeatures.py) (Pipeline), [`tsfeatures/metrics/metrics.py`](https://github.com/nixtla/tsfeatures/blob/main/tsfeatures/metrics/metrics.py) (Metrics), [`.github/workflows/python-package.yml`](https://github.com/nixtla/tsfeatures/blob/main/.github/workflows/python-package.yml) (CI workflow), [`tsfeatures/tsfeatures_r.py`](https://github.com/nixtla/tsfeatures/blob/main/tsfeatures/tsfeatures_r.py) (R bridge)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_core["Core Python"]
  node_api["tsfeatures API<br/>public entrypoint<br/>[__init__.py]"]
  node_orchestrator["Pipeline<br/>orchestration<br/>[tsfeatures.py]"]
  node_freq["Freq handling<br/>preprocessing<br/>[tsfeatures.py]"]
  node_feature_select["Feature set<br/>selection layer<br/>[__init__.py]"]
  node_metrics["Metrics<br/>feature functions<br/>[metrics.py]"]
  node_helpers["Utils<br/>shared helpers<br/>[utils.py]"]
  node_sample_data["M4 data<br/>sample data<br/>[m4_data.py]"]
end

subgraph group_parity["R Parity"]
  node_r_bridge["R bridge<br/>interop layer<br/>[tsfeatures_r.py]"]
  node_r_compare["Compare tool<br/>validation CLI<br/>[compare_with_r.py]"]
end

subgraph group_quality["Quality & Delivery"]
  node_tests_pipeline["Pipeline tests<br/>test suite<br/>[test_pipeline.py]"]
  node_tests_features["Feature tests<br/>test suites<br/>[test_statistics.py]"]
  node_tests_small["Small series<br/>test suite<br/>[test_small_ts.py]"]
  node_tests_mutability["Mutability<br/>test suite<br/>[test_mutability.py]"]
  node_package["Packaging<br/>distribution<br/>[setup.py]"]
  node_requirements["Deps<br/>[requirements.txt]"]
  node_workflow_ci["CI workflow<br/>automation<br/>[python-package.yml]"]
  node_workflow_publish["Publish workflow<br/>automation<br/>[python-publish.yml]"]
end

node_api -->|"exposes"| node_orchestrator
node_orchestrator -->|"uses"| node_freq
node_orchestrator -->|"selects"| node_feature_select
node_feature_select -->|"calls"| node_metrics
node_metrics -->|"shares helpers"| node_helpers
node_orchestrator -.->|"validated by"| node_sample_data
node_r_bridge -.->|"parallels"| node_metrics
node_r_bridge -.->|"alternative path"| node_orchestrator
node_r_compare -->|"invokes"| node_r_bridge
node_r_compare -->|"compares against"| node_orchestrator
node_tests_pipeline -->|"covers"| node_orchestrator
node_tests_features -->|"covers"| node_metrics
node_tests_small -->|"covers"| node_orchestrator
node_tests_mutability -->|"covers"| node_orchestrator
node_package -->|"released by"| node_workflow_publish
node_requirements -.->|"drives"| node_workflow_ci
node_workflow_ci -->|"runs"| node_tests_pipeline
node_workflow_ci -->|"runs"| node_tests_features
node_workflow_publish -->|"builds"| node_package

click node_api "https://github.com/nixtla/tsfeatures/blob/main/tsfeatures/__init__.py"
click node_orchestrator "https://github.com/nixtla/tsfeatures/blob/main/tsfeatures/tsfeatures.py"
click node_freq "https://github.com/nixtla/tsfeatures/blob/main/tsfeatures/tsfeatures.py"
click node_feature_select "https://github.com/nixtla/tsfeatures/blob/main/tsfeatures/metrics/__init__.py"
click node_metrics "https://github.com/nixtla/tsfeatures/blob/main/tsfeatures/metrics/metrics.py"
click node_helpers "https://github.com/nixtla/tsfeatures/blob/main/tsfeatures/utils.py"
click node_sample_data "https://github.com/nixtla/tsfeatures/blob/main/tsfeatures/m4_data.py"
click node_r_bridge "https://github.com/nixtla/tsfeatures/blob/main/tsfeatures/tsfeatures_r.py"
click node_r_compare "https://github.com/nixtla/tsfeatures/blob/main/tsfeatures/compare_with_r.py"
click node_tests_pipeline "https://github.com/nixtla/tsfeatures/blob/main/tsfeatures/tests/test_pipeline.py"
click node_tests_features "https://github.com/nixtla/tsfeatures/blob/main/tsfeatures/tests/test_statistics.py"
click node_tests_small "https://github.com/nixtla/tsfeatures/blob/main/tsfeatures/tests/test_small_ts.py"
click node_tests_mutability "https://github.com/nixtla/tsfeatures/blob/main/tsfeatures/tests/test_mutability.py"
click node_package "https://github.com/nixtla/tsfeatures/blob/main/setup.py"
click node_requirements "https://github.com/nixtla/tsfeatures/blob/main/requirements.txt"
click node_workflow_ci "https://github.com/nixtla/tsfeatures/blob/main/.github/workflows/python-package.yml"
click node_workflow_publish "https://github.com/nixtla/tsfeatures/blob/main/.github/workflows/python-publish.yml"

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_api,node_orchestrator,node_freq,node_feature_select,node_metrics,node_helpers,node_sample_data toneBlue
class node_r_bridge,node_r_compare toneAmber
class node_tests_pipeline,node_tests_features,node_tests_small,node_tests_mutability,node_package,node_requirements,node_workflow_ci,node_workflow_publish toneMint
```

## Components

### Core Python

Primary library path for panel feature extraction.

- [tsfeatures API](https://github.com/nixtla/tsfeatures/blob/main/tsfeatures/__init__.py): public entrypoint · Top-level package import that exposes the main feature extraction interface. · `tsfeatures/__init__.py`
- [Pipeline](https://github.com/nixtla/tsfeatures/blob/main/tsfeatures/tsfeatures.py): orchestration · Main function that splits a panel by series, handles frequency, and coordinates feature extraction. · `tsfeatures/tsfeatures.py`
- [Freq handling](https://github.com/nixtla/tsfeatures/blob/main/tsfeatures/tsfeatures.py): preprocessing · Frequency inference and seasonal-period mapping for panel series. · `tsfeatures/tsfeatures.py`
- [Feature set](https://github.com/nixtla/tsfeatures/blob/main/tsfeatures/metrics/__init__.py): selection layer · Built-in feature composition and custom callable injection points. · `tsfeatures/metrics/__init__.py`
- [Metrics](https://github.com/nixtla/tsfeatures/blob/main/tsfeatures/metrics/metrics.py): feature functions · Individual time-series feature implementations used by the pipeline. · `tsfeatures/metrics/metrics.py`
- [Utils](https://github.com/nixtla/tsfeatures/blob/main/tsfeatures/utils.py): shared helpers · Common helper functions used across preprocessing and feature calculations. · `tsfeatures/utils.py`
- [M4 data](https://github.com/nixtla/tsfeatures/blob/main/tsfeatures/m4_data.py): sample data · Bundled dataset helpers and reference data used for examples and validation. · `tsfeatures/m4_data.py`

### R Parity

Optional bridge and validation against the R implementation.

- [R bridge](https://github.com/nixtla/tsfeatures/blob/main/tsfeatures/tsfeatures_r.py): interop layer · Python wrapper that calls the R tsfeatures implementation through rpy2. · `tsfeatures/tsfeatures_r.py`
- [Compare tool](https://github.com/nixtla/tsfeatures/blob/main/tsfeatures/compare_with_r.py): validation CLI · Command-line workflow for comparing Python and R feature outputs. · `tsfeatures/compare_with_r.py`

### Quality & Delivery

Tests and packaging workflows that verify and release the library.

- [Pipeline tests](https://github.com/nixtla/tsfeatures/blob/main/tsfeatures/tests/test_pipeline.py): test suite · Checks panel handling, edge cases, and output consistency. · `tsfeatures/tests/test_pipeline.py`
- [Feature tests](https://github.com/nixtla/tsfeatures/blob/main/tsfeatures/tests/test_statistics.py): test suites · Family of tests for autocorrelation, statistics, sparsity, ARCH, Holt parameters, and PACF behavior. · `tsfeatures/tests/test_statistics.py`
- [Small series](https://github.com/nixtla/tsfeatures/blob/main/tsfeatures/tests/test_small_ts.py): test suite · Verifies behavior on short or degenerate time series. · `tsfeatures/tests/test_small_ts.py`
- [Mutability](https://github.com/nixtla/tsfeatures/blob/main/tsfeatures/tests/test_mutability.py): test suite · Ensures feature extraction does not introduce unintended side effects. · `tsfeatures/tests/test_mutability.py`
- [Packaging](https://github.com/nixtla/tsfeatures/blob/main/setup.py): distribution · Standard Python package build and release configuration. · `setup.py`
- [Deps](https://github.com/nixtla/tsfeatures/blob/main/requirements.txt): runtime deps · Pinned or declared Python dependencies for installation and execution. · `requirements.txt`
- [CI workflow](https://github.com/nixtla/tsfeatures/blob/main/.github/workflows/python-package.yml): automation · GitHub Actions workflow for testing the package. · `.github/workflows/python-package.yml`
- [Publish workflow](https://github.com/nixtla/tsfeatures/blob/main/.github/workflows/python-publish.yml): automation · GitHub Actions workflow for building and publishing releases to PyPI. · `.github/workflows/python-publish.yml`

## Connections

- tsfeatures API → Pipeline: exposes · Top-level import surfaces the core pipeline.
- Pipeline → Freq handling: uses · The pipeline normalizes or infers seasonal frequency before feature extraction.
- Pipeline → Feature set: selects · The pipeline chooses the active feature set or custom callables.
- Feature set → Metrics: calls · Selected feature definitions resolve to concrete metric implementations.
- Metrics → Utils: shares helpers · Feature functions reuse common utilities for calculations and preprocessing.
- Pipeline → M4 data: validated by · Reference data helps exercise expected output shapes and benchmark comparisons.
- R bridge → Metrics: parallels · The bridge mirrors the feature names and semantics of the native implementation.
- R bridge → Pipeline: alternative path · Provides an optional external-runtime route for feature extraction.
- Compare tool → R bridge: invokes · Comparison CLI runs the R-backed extraction path.
- Compare tool → Pipeline: compares against · Validation tool checks Python results against the native pipeline.
- Pipeline tests → Pipeline: covers · Pipeline tests verify panel handling and orchestration behavior.
- Feature tests → Metrics: covers · Feature-family tests validate the individual implementations.
- Small series → Pipeline: covers · Short-series tests verify edge-case handling in the pipeline.
- Mutability → Pipeline: covers · Mutability tests protect against unintended input mutation.
- Packaging → Publish workflow: released by · Packaging configuration feeds the publish workflow.
- Deps → CI workflow: drives · Declared dependencies are installed in CI runs.
- CI workflow → Pipeline tests: runs · CI executes the repository test suite.
- CI workflow → Feature tests: runs · CI validates feature implementations.
- Publish workflow → Packaging: builds · Release workflow packages and publishes the library artifact.
