How nixtla/tsfeatures works
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.py Pipeline · metrics.py Metrics · python-package.yml CI workflow · tsfeatures_r.py R bridge
Components 17
Core Python
Primary library path for panel feature extraction.
- tsfeatures API · Top-level package import that exposes the main feature extraction interface.
tsfeatures/__init__.py - Pipeline · Main function that splits a panel by series, handles frequency, and coordinates feature extraction.
tsfeatures/tsfeatures.py - Freq handling · Frequency inference and seasonal-period mapping for panel series.
tsfeatures/tsfeatures.py - Feature set · Built-in feature composition and custom callable injection points.
tsfeatures/metrics/__init__.py - Metrics · Individual time-series feature implementations used by the pipeline.
tsfeatures/metrics/metrics.py - Utils · Common helper functions used across preprocessing and feature calculations.
tsfeatures/utils.py - M4 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 · Python wrapper that calls the R tsfeatures implementation through rpy2.
tsfeatures/tsfeatures_r.py - Compare tool · 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 · Checks panel handling, edge cases, and output consistency.
tsfeatures/tests/test_pipeline.py - Feature tests · Family of tests for autocorrelation, statistics, sparsity, ARCH, Holt parameters, and PACF behavior.
tsfeatures/tests/test_statistics.py - Small series · Verifies behavior on short or degenerate time series.
tsfeatures/tests/test_small_ts.py - Mutability · Ensures feature extraction does not introduce unintended side effects.
tsfeatures/tests/test_mutability.py - Packaging · Standard Python package build and release configuration.
setup.py - Deps · Pinned or declared Python dependencies for installation and execution.
requirements.txt - CI workflow · GitHub Actions workflow for testing the package.
.github/workflows/python-package.yml - Publish workflow · GitHub Actions workflow for building and publishing releases to PyPI.
.github/workflows/python-publish.yml
Connections 19
- 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.