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 4500 interpretable time-series 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

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 791 master operations.

e1000 = get_dataset()               # bundled Empirical 1000 dataset
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.

New to pyhctsa? Step-by-step notebooks and example workflows live in /tutorials, and a walkthrough is available in the getting started guide.

Usage

Custom feature sets

By default, FeatureCalculator initializes the full feature set. To compute a subset, pass the corresponding configuration .yaml file:

custom_calc = FeatureCalculator(config_path="subset.yaml")

The number of master operations (callable functions) specified by the .yaml is displayed for verification, e.g. Loaded 700 master operations..

Calling individual operations

Individual operations can be imported directly from their module. For example, raw_hrv_meas lives in the medical module:

from pyhctsa.operations.medical import raw_hrv_meas

data = ...              # your ArrayLike data
res = raw_hrv_meas(data)  # a dictionary or scalar value

Note

Individual operations can only be called directly on individual time-series instances.

Operations are grouped into the following modules — see the method list for the full catalogue:

changepoint	correlation	criticality	distribution
entropy	extreme_events	graph	hypothesis_tests
information	medical	model_fit	nonlinearity
physics	pre_process	scaling	spectral
stationarity	surrogates	symbolic	wavelet

Note

These conceptual groupings are a convenience only, and are not intended as definitive classifications.

Parallel computing

Time-series feature extraction is computationally intensive. To speed up processing, pyhctsa can distribute the workload across multiple CPU cores on your local machine using the LocalDistributor:

from pyhctsa.calculator import FeatureCalculator
from pyhctsa.distribute import LocalDistributor

calc = FeatureCalculator()

# it is generally recommended to set n_workers to the number of physical CPU cores
dist = LocalDistributor(n_workers=4)

res = calc.extract(data, distributor=dist)

Coming from MATLAB hctsa? A mapping between legacy operation names and their pyhctsa equivalents is available in the name mappings table.

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

@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

Internal licenses

Code for computing features from time-series data is licensed under the GNU General Public License version 3.

External packages and dependencies

While the majority of features in pyhctsa rely on standard Python libraries, a small subset of features require external toolboxes. The following external time-series analysis code packages are bundled with the software (in pyhctsa/toolboxes) and are used by the feature-extraction calculator:

Package	Author	License
Time-series analysis code	Michael Small	unlicensed
Time-series analysis code	Max Little	GPL
TISEAN (v3.0.1)	Hegger, Kantz & Schreiber	GPL

The following codebases have been adapted directly into Python code within pyhctsa, rather than being included as external toolboxes:

Code	Author	License
Embedding statistics	Danny Kaplan	GPL
Histogram code	Rudy Moddemeijer	unlicensed

AI usage disclosure

Portions of this codebase (including tests and function documentation) were refactored and generated with the assistance of Large Language Models (LLMs). All AI-generated contributions have been reviewed and verified by the human maintainers.