pyhctsa

Highly comparative time-series analysis in Python

Documentation  ·  Getting started  ·  Method list  ·  API reference  ·  Paper

---

The PYthon toolkit for Highly Comparative Time-Series Analysis (pyhctsa) is a living library of time-series analysis methods. It computes over 6300 interpretable time-series features (6344 in the default feature set: 6104 from the operations of hctsa plus 240 pyhctsa-only features) from a single univariate series — spanning distributional shape, autocorrelation, entropy and information theory, scaling, stationarity, nonlinear dynamics, spectral and wavelet properties, model fits, and more — making it the most comprehensive feature set available in native Python.

Installation

pyhctsa requires Python 3.10 or newer:

pip install pyhctsa

This gives 6384 of the 6392 features of the hctsa v3.0.0 feature set. The other 8, the persistent-homology features (NL_PersistentHomology), need the optional ripser package; without it the calculator skips them and warns. For the full feature set, install with the tda extra:

pip install "pyhctsa[tda]"

We strongly recommend installing into a fresh virtual environment to prevent dependency clashes:

conda create -n pyhctsa python=3.12 -y && conda activate pyhctsa && pip install pyhctsa

Quickstart

Instantiate a FeatureCalculator and call extract on your data:

from pyhctsa.calculator import FeatureCalculator
from pyhctsa.utils import get_dataset

calc = FeatureCalculator()          # Loaded 1080 master operations.

e1000 = get_dataset()               # Empirical1000 dataset (downloaded once, 33 MB)
data = e1000[0]                     # a list, array, or pandas Series

res = calc.extract(data)            # pandas DataFrame, one row per series

extract accepts either a single time series or a list of series, which do not need to be the same length:

res = calc.extract(e1000[:10], verbose=True)
print(res.shape)                    # (10, F) -> N series x F features

Results are returned as a pandas.DataFrame of shape N × F, where N is the number of time-series instances and F is the number of time-series features.

Next steps

• Getting started: computing features, calling individual operations, and parallel computing with LocalDistributor.
• Advanced usage: custom feature sets from your own .yaml configuration, and feature filtering.
• Sampling rate: why the sampling rate matters, and how to check and set one rate for a whole dataset (sampling_report, resample_dataset) before extraction.
• Method list and API reference: every operation and its outputs.
• Tutorials: step-by-step notebooks.

Citation

If you use pyhctsa in your work, please cite the accompanying JOSS paper:

Moore, J. B., & Fulcher, B. D. (2026). pyhctsa: A Python package for highly comparative time-series analysis. Journal of Open Source Software, 11(123), 10581. https://doi.org/10.21105/joss.10581

BibTeX

@article{Moore2026pyhctsa,
  author  = {Moore, Joshua B. and Fulcher, Ben D.},
  title   = {pyhctsa: A Python package for highly comparative time-series analysis},
  journal = {Journal of Open Source Software},
  year    = {2026},
  volume  = {11},
  number  = {123},
  pages   = {10581},
  doi     = {10.21105/joss.10581}
}

Machine-readable metadata is provided in CITATION.cff.

Licenses

pyhctsa is licensed under the GNU General Public License v3.0 or later. It is a Python implementation of the feature library of hctsa. Some features use third-party code, bundled in pyhctsa/toolboxes/ under its own GPL-compatible license (full texts in THIRD_PARTY_LICENSES.md); others are clean-room re-implementations of published methods. Full credits are on the Acknowledgements page of the documentation.

Notes

• Version 2 and this repository's history. pyhctsa 2.0 (October 2026) lives in a re-created repository with a fresh history. Every function that depended on MATLAB code was re-implemented clean-room from published methods, and bundled third-party code is GPL-compatible (see Licenses). Earlier releases (1.x) have been yanked; please upgrade.
• AI use. Much of pyhctsa 2.0, including the clean-room re-implementations, tests and documentation, was written with AI coding assistants (Anthropic's Claude) under the direction of the maintainers. Not every contribution has been reviewed line by line by a human. Instead, each has been verified against the outputs of existing implementations (e.g., hctsa) where appropriate, or else by appropriately formulated direct tests of behavior.