pyhctsa: One Time Series, Hundreds of Questions, Part I

You usually know how a time series was collected. The harder question is what the series is doing.

This can include questions such as: Is it periodic? Does it contain long-range memory? Are its extreme values clustered? Would a simple autoregressive model predict it? Does it behave differently in the first and second half? A plot gives you a feel for some of this, but plots become less helpful when you have 500 signals and need a consistent answer.

This is where pyhctsa comes in. It approaches the problem in an unusual way. Instead of asking you to choose one family of measurements, it runs a large and varied library of time-series operations. The output is a regular pandas DataFrame: one row per series and one column per feature.

That turns a collection of signals into a table that you can explore with the rest of Python’s data stack.

This first part covers the package’s central idea, its standout capabilities, and the mechanics of extracting features. Part II uses those features for visual exploration and machine learning.

ChatGPT definitely understands well what the package does.

Highly comparative time-series analysis

Most time-series packages are organised around a task. A forecasting package helps you predict future values. A spectral package estimates frequency content. A change-point package searches for regime shifts.

Highly comparative time-series analysis starts somewhere else: calculate many scientifically motivated measurements, then discover which measurements respond to your data.

The original hctsa project developed this approach in MATLAB. pyhctsa brings a growing reimplementation of that feature library into Python. Its operations cover areas such as:

• autocorrelation and other correlation statistics;

• distributions, entropy, stationarity, and scaling;

• spectral and wavelet measurements;

• nonlinear dynamics, criticality, and surrogate tests;

• symbolic transformations, graph features, and medical signal measures.

That breadth is the package’s defining feature. You do not need to bet the analysis on sample entropy, a Fourier transform, or an autoregressive model before you have seen the data. You can treat all of them as candidate views of the same signal.

There is a cost. Broad feature extraction takes more computation than a hand-picked set, and a large result table needs careful cleaning. The package gives you a search space, not an automatic conclusion.

Installation

As of the date of this post pyhctsa requires Python 3.10 or newer. The current project includes compiled and adapted external time-series code. Its declared dependencies include NumPy, SciPy, pandas, statsmodels, scikit-learn, antropy, PyWavelets, and several packages used by particular operation families. The calculator skips operations whose optional dependencies are missing and records them internally.

Your first feature matrix

The repository ships with a small sample named e1000, which is useful for checking that the installation works. This is a list of NumPy arrays that are the individual time series.

The FeatureCalculator() loads the default YAML configuration. During initialisation it reports how many master operations it loaded. One operation can return a dictionary or a short vector, so the resulting DataFrame may contain more columns than the number printed at startup.

The table has the shape analysts want:

instance      feature_1  feature_2  feature_3  ...
sample_1          ...        ...        ...
sample_2          ...        ...        ...
sample_3          ...        ...        ...

Labels become the DataFrame index. Supplying them early saves you from matching anonymous rows back to files later. Note that in this example, the produced dataframe has 5 rows, one for each sample, and a total of 5271 columns, all of which are certain features calculated by pyhctsa—such as statistics describing distribution, autocorrelation, entropy, stationarity, and other dynamics.

Unequal lengths are allowed

Many feature-extraction interfaces expect a rectangular array. Real collections are often untidy: one machine ran for 40 minutes, another for an hour, and a third lost a block of samples.

Luckily, pyhctsa accepts a list of one-dimensional arrays, so each series can have a different length.

This is a small interface decision with a large practical benefit. You can analyse variable-length recordings without padding them with artificial values. Individual features may still have their own minimum data requirements, so check failed or missing outputs before modelling.

For equal-length data, pass a two-dimensional NumPy array with shape (n_series, n_samples). But do not transpose it. pyhctsa treats each row as one time series.

A configuration file is an analysis protocol

The package does not hide its feature selection in Python code. FeatureCalculator builds operations from YAML files. The repository includes a broad hctsa.yaml and module-level configurations for entropy, spectral analysis, wavelets, medical measures, and other families.

You can therefore choose a feature set without rewriting the extraction pipeline:

The YAML layer is more interesting than a list of function names. It can define parameter grids, request z-scoring or absolute values, and select outputs from operations that return several measurements. One master function can therefore generate several named feature variants.

A small custom configuration might look like this:

correlation:
  first_crossing:
    base_name: first_crossing
    ordered_args: [corr_fun, threshold, what_out]
    configs:
      - corr_fun: ac
        threshold: [0, "1/e"]
        what_out: both
        zscore: true

entropy:
  sample_entropy:
    base_name: sample_entropy
    ordered_args: [m, r]
    configs:
      - m: [2, 3]
        r: [0.1, 0.2]
        zscore: true

Save it as my_features.yaml, then load it through the same interface:

This will produce a total of 36 feature columns. The first four are for first_crossing, two each for the two supplied values for the correlation of 0 and 1/e. The other 32 are for sample_entropy, here for the choice of m=2 it returns a set of 7 values twice, for two different values of r, and for m=3 it returns a set of 9 values twice, for the two different r values.

Function names and parameters can change as the alpha-stage package develops, so base a custom file on the YAML shipped with your installed version. The useful design idea remains stable: the configuration records exactly which measurements and parameter choices produced your table. Commit that file beside the analysis and it becomes part of the experiment.

Call one operation when you know what you want

Mass extraction is the main attraction, but pyhctsa does not force every job through FeatureCalculator. You can import an operation and call it on one series.

The repository’s getting-started tutorial uses the rescaled auto-density (rad) operation:

Medical operations work in the same way:

An individual operation may return one scalar, in the first example above, or a dictionary of related values, in the medical operations example. Direct calls help when you are reproducing a known metric, testing an idea in a notebook, or inspecting the meaning of a feature selected by a model.

They also make pyhctsa useful as a library of implementations. The package gathers methods that would otherwise send you across papers, old toolboxes, and separate Python packages.

Inspect before you trust

Feature names in hctsa are compact and often encode parameters. Do not treat the columns as anonymous machine-learning inputs.

Python’s inspection tools help you connect an operation to its documentation:

You can also list the operation modules available in your installed version:

This matters during interpretation. A classifier may prefer a feature based on a transition matrix or an autocorrelation crossing. Its name tells you where to look; the operation’s docstring tells you what calculation generated the value.

Where pyhctsa fits

pyhctsa is strongest when you have many univariate series and a question about their structure:

• Which recordings differ between experimental groups?

• Can a compact set of features separate machine states?

• Which measurements change before a fault?

• Do clusters of signals correspond to known behaviours?

• Which candidate dynamics should you investigate with a narrower method?

It can support classification, clustering, anomaly investigation, quality control, and exploratory scientific analysis. It is less suited to problems that require raw sequence alignment, multivariate interactions at each timestamp, or a dedicated forecasting model. You can still use its output alongside those methods. A feature matrix often adds an interpretable summary of each series.

The package’s distinctive move is simple: postpone the choice of measurement. Calculate a broad collection, compare how those measurements behave, then return to the handful that explain the structure you care about.

Part II puts that idea to work. We will generate signals with different dynamics, extract features, remove failed columns, scale the unusually shaped values, visualise the result, and build a classifier without leaking information across validation folds.