hctsa turns thousands of time series features into a matrix you can cluster

From many signals to one feature matrix

hctsa is a MATLAB package for running highly comparative time-series analysis, abbreviated HCTSA. The README states the method plainly: it extracts thousands of time-series features from a collection of univariate time series, and then gives you a range of tools for visualizing and analyzing the resulting time-series feature matrix.

The idea behind the approach is comparative. Instead of choosing one or two measures that suit a particular signal, you compute a very large set of generic measures, which describe how the signal behaves in time rather than what it means, and then let the data tell you which of those measures separate your classes. The documentation lists four families of tooling built on that matrix: normalizing and clustering the time-series data, producing low-dimensional representations of it, identifying and interpreting the features that discriminate between classes of time series, and fitting and evaluating multivariate classification models.

The repository layout mirrors that pipeline. Calculation and FeatureSets hold the feature computation, Operations the processing steps, PlottingAnalysis the visualisation and analysis, TimeSeries the data handling, PeripheryFunctions the supporting utilities, and Toolboxes a directory of external packages bundled for convenience.

The audience is researchers in time-series analysis, and the documentation points at the underlying papers: the 2017 Cell Systems article on automated time-series phenotyping using massive feature extraction, and the 2013 Journal of the Royal Society Interface paper on the empirical structure of time series and their methods.

Installing: a fork, a submodule and one script

Installation follows a git-first path, and the README recommends forking the repository and cloning it locally if you are comfortable with git.

For updates, you add an upstream remote and pull from it:

git remote add upstream git://github.com/benfulcher/hctsa.git

git pull upstream main

The submodule detail matters. To get the latest toolboxes, including the optimized catch22 feature set, in one step, you clone with the recurse-submodules flag. If you do not, startup.m fetches the catch22 submodule for you the first time it runs:

git clone --recurse-submodules

Users who are not familiar with git are given an alternative: download the repository as a ZIP through the green Code button. Once the files are on your machine, you install the package by running the install.m script, and the documentation link in the README covers the details.

So the installation is a source checkout plus one script. There is no compiled installer and no package manager entry, which is normal for MATLAB research code but worth knowing if your environment expects a binary.

The top level also carries ToolboxDependencies.txt, which lists the external packages the toolbox expects, and a Tests directory with a unit test workflow in the CI configuration.

The five call quick start on the sample data

Once installed, the README shows that computing and exploring a feature matrix takes five lines of MATLAB, run in sequence over a sample time-series dataset.

TS_Init('INP_test_ts.mat','hctsa'); % format time series into HCTSA.mat
TS_Compute;                         % compute all features (uses Parallel Computing Toolbox if available)
TS_Normalize;                       % normalize the resulting feature matrix, into HCTSA_N.mat
TS_Cluster;                         % cluster time series and features by similarity
TS_PlotDataMatrix;                  % plot the clustered feature matrix

Each step is a separate script that leaves a file behind, which is a deliberate design. TS_Init formats the input time series into HCTSA.mat. TS_Compute calculates every feature and notes in the comment that it uses the Parallel Computing Toolbox if it is available. TS_Normalize normalizes the resulting feature matrix into HCTSA_N.mat. TS_Cluster groups time series and features by similarity, and TS_PlotDataMatrix draws the clustered matrix.

Two things follow from the way this is written. The intermediate files mean you can inspect and reuse each stage, so a failed or interrupted computation is not lost work. And the compute step is the expensive one, which is why the documentation links to resources for distributing an hctsa computation on a computing cluster, and to an archive of downloadable feature matrices for existing datasets with example workflows.

The demonstration image in the README is a low-dimensional feature-based projection of EEG time series where clicking through the points inspects the underlying series, which is a good picture of the workflow the package supports.

The environment you need before anything runs

The requirements are stated in the README and they are not trivial.

MATLAB R2022a or later is needed. On top of that, five add-on toolboxes are required: Statistics and Machine Learning, Signal Processing, Curve Fitting, Wavelet, and Econometrics. Each is a separate licence in MATLAB terms, and a research group without them will hit an error when a feature set needs one of them.

There is a documented fallback for that case. Many features in hctsa rely on external packages, and those are provided for convenience in the Toolboxes directory, each with its own associated licence. The README is explicit that if some of them are unavailable, hctsa can still be used, but only a reduced set of time-series features will be computed. That is a different result, and it is worth knowing before you compare a feature matrix computed on one machine with one computed on another.

Two of the external packages are named. TISEAN, the package for nonlinear time-series analysis, at version 3.0.1 and under the GPL, and Joseph Lizier's Java Information Dynamics Toolkit for studying information-theoretic measures of computation. The latter is Java, which tells you the toolbox expects a Java runtime on the path for those particular features.

The Parallel Computing Toolbox is optional, in the sense that TS_Compute says it uses it if available. Its absence makes the feature computation slower rather than impossible.

catch22 is the faster alternative, with far fewer features

The documentation names an alternative feature set explicitly, and it is the most useful comparison in the project because it is a comparison of scale rather than of quality.

catch22 is described as much faster, and it computes a small feature set, where hctsa computes thousands. The distinction matters for anyone with a large dataset or a limited compute budget. A feature matrix of thousands of columns also carries a statistical cost, since with enough features you can separate classes that have nothing to do with each other, and the analysis then has to work harder to establish that the differences are real.

The difference in approach is therefore a trade between breadth and cost. hctsa maximises the number of generic descriptions of each signal, which is what makes the comparative method work, and pays for it in computation time, storage and the need for careful feature selection and interpretation afterwards. catch22 accepts a much smaller descriptive vocabulary, computes quickly, and gives up the ability to find discriminating features outside that vocabulary.

The manual also lists other time-series packages available in R, Python and Julia, and the README points to pyhctsa, a native Python implementation planned to reproduce the hctsa v3.0.0 feature set. That last point is worth flagging for anyone planning a long-term project: the Python route is described as future development, and the documentation for it lives in a separate repository.

The rest of the documentation supports the whole workflow rather than one script: the CompEngine time-series data archive, downloadable feature matrices with example workflows, a distributed computation guide, a list of publications that have used hctsa, and a section of frequently asked questions.

Two licences, one package, and a commercial path

The licensing is the part of this project that most affects adoption, because it is not a single licence.

Two licences apply to the two core functionalities. The framework for running hctsa analyses and visualisations is under the Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International Licence, and a licence for commercial use is available from Engine Analytics. The code for computing features from time-series data is under the GNU General Public License version 3.

The split is logical rather than administrative. The framework is documentation, scripts and visualisation code, which the author chose to share non-commercially, while the feature computation code is under the GPL, which is a copyleft licence designed for software. The README is explicit that for commercial use of hctsa, including licensing and consulting, you should contact Engine Analytics.

Two further layers sit on top. The external packages bundled in the Toolboxes directory carry their own licences, TISEAN among them under the GPL, and the MATLAB add-on toolboxes are licensed by MathWorks under their own terms.

If you are planning to use hctsa in a commercial setting, the arrangement to settle is the non-commercial clause on the framework, and that conversation has to happen with Engine Analytics rather than with the repository. For academic work, the two licences are compatible with the way the package is meant to be used, and the README asks that you cite the two open access articles if you use the software.

The release history is recent: version 2.0.0 was published on 2026-08-04, a 3.0.0 alpha on 2026-08-18 and version 3.0.0 on 2026-10-19, with the last push to the default branch following two days later.

Editorial conclusion

Adopt hctsa when your research question is about what distinguishes groups of time series rather than about one signal, and when you have MATLAB with the required add-on toolboxes and time for a feature matrix that can take a while to compute. Do not adopt it for commercial deployment without talking to Engine Analytics, because the framework licence is non-commercial, and do not adopt it expecting a Python package, since pyhctsa is still described as future development. Before you start, read the GitBook manual for the feature set you need, check ToolboxDependencies.txt for the external packages, and run the quick start on the sample data so you know how long the compute step takes on your machine.

Frequently asked questions

Official sources

1. benfulcher/hctsa on GitHub
2. Issues
3. Project website
4. README
5. Releases